Commit 0307814c authored by Bob Ham's avatar Bob Ham
Browse files

Merge branch 'devkit-clean-up' into 'master'

Tidy up new devkit information

See merge request Librem5/developer.puri.sm!96
parents 842df384 535613c0
Pipeline #2836 passed with stage
in 10 minutes and 43 seconds
......@@ -3,6 +3,11 @@
Setting up a Development Environment
====================================
This chapter describes how to set up an development environment for the
Librem 5 phone that enables you to create, test, package and deploy
applications. Development and testing can be performed using either the phone
itself, a development kit or with an emulator that runs on a workstation.
.. toctree::
:maxdepth: 2
......
......@@ -4,7 +4,8 @@ Development Kits
================
The development boards for the Librem 5 are built around the
`EmCraft i.MX 8M SoM`_, a development platform based on the i.MX8 CPU.
`EmCraft i.MX 8M SoM`_, a development platform based on the i.MX8 CPU. There
is a list of :ref:`imx8_devkit_known_issues` with the development boards.
It is possible to develop software for the Librem 5 without a development kit.
If you are developing applications that do not rely on specific features of the
......@@ -17,8 +18,9 @@ commands and some application setup that is not board specific.
.. toctree::
:maxdepth: 2
Boards/First-Steps
Boards/imx8
Boards/Known_Issues
Boards/Troubleshooting
Boards/dev-kit/modem
Boards/mini-tutorials
Boards/Legacy/index
......
.. _imx8_devkit_known_issues:
Known Issues
============
.. note:: This section is incomplete and is being revised.
This page will contain a list of issues that were known at the time of the
kit's release, providing links to issue trackers where relevant.
Known issues with the operating system and applications under development for
the Librem 5 can be found in the lists of issues for the `OS Issues`_ and
`Apps Issues`_ repositories.
Status of Subsystems
--------------------
The following table shows the status of the subsystems on the development
board, indicating the level to which the hardware has been validated and
whether user space software is in place to drive it.
.. csv-table:: Status of subsystems
:header: "Subystem", "Validated", "Integrated"
"Charge Controller", "Yes", ""
"USB-C", "Yes", ""
"Serial Downloader", "Yes", ""
"eMMC boot", "Yes", ""
"SoM - with 3GB RAM, 32GB eMMC", "Yes", ""
"UART Debug", "Yes", ""
"Powering from 18650 battery", "Yes", ""
"Charge controller's thermistor", "Yes", ""
"Ethernet", "Yes", ""
"Audio Codec", "Yes", ""
"Mini-HDMI", "Yes", ""
"WWAN module", "Yes", ""
"WWAN antenna", "Yes", ""
"SIM card (able to make a call)", "Yes", ""
"WWAN kill via GPIO3_IO04 (420 in Linux) & HKS", "Yes", ""
"GNSS (aka GPS)", "Yes", ""
"USB Hub and micro-SD", "Yes", ""
"USB Host", "Yes", ""
"USB Peripheral", "Yes", ""
"RedPine WiFi/BT M.2 module", "Yes", ""
"RTC", "Yes", ""
"Haptic motor", "Yes", ""
"buttons (power button, reset button, volume up, volume down)", "Yes", ""
"User LED", "Yes", ""
"Power indicator LEDs", "Yes", ""
"HP_DET", "Yes", ""
"Display's LED backlight", "Yes", ""
"SPI NOR Flash", "Yes", ""
"Speaker", "Yes", ""
"Headphone jack", "Yes", ""
"Smart card reader", "Yes", ""
"Touch controller", "Yes", ""
"JTAG", "Yes", ""
"IMU", "Partially", ""
"Proximity/Ambient light sensor", "Partially", ""
"WLAN/BT antennae", "Partially", ""
"On-board microphone", "Partially", ""
"Headset microphone", "Partially", ""
"HKSs", "Partially", ""
"MIPI DSI LCD panel", "Partially", ""
"USB-C role switching", "No", ""
"Microphone select IC", "No", ""
"Bluetooth (UART4)", "No", ""
"Camera", "No", ""
"USB OTG", "No", ""
"WWAN I2S interface", "No", ""
"Bluetooth I2S interface", "No", ""
.. _`Apps Issues`: https://source.puri.sm/Librem5/Apps_Issues
.. _`OS Issues`: https://source.puri.sm/Librem5/OS-issues
.. _first-steps:
.. _imx6_first_steps:
First Steps
===========
The development board (whether a physical one or an emulated one) will give you a place to see the effects of the active Librem 5 development. The software running on this board will become the software running on the Librem 5 phone but you don't have to wait for your Librem 5 phone to interact with it!
The development board (whether a physical one or an emulated one) will give you
a place to see the effects of the active Librem 5 development. The software
running on this board will become the software running on the Librem 5 phone
but you don't have to wait for your Librem 5 phone to interact with it!
Regardless of which development board you are using, here are some first steps you will take when booting the system.
If you are using the i.MX6 development board, here are some first steps you
will take when booting the system.
.. _make-bootable-drive:
......
......@@ -8,4 +8,5 @@ generally available or are considered to be obsolete for current development.
.. toctree::
First-Steps
imx6
.. _imx8_devkit_troubleshooting:
Troubleshooting
===============
This page provides information for developers who need to investigate a problem
with a development kit and want to diagnose it. It contains some useful
starting points for investigation and instructions for performing tasks that
may be needed to help with testing.
.. contents::
Installing the SOM
------------------
If the SOM is not installed or has been removed, follow these instructions to
install it.
1. Power board without SOM via USB-C.
2. Check the voltages.
.. figure:: images/voltage-points.png
:scale: 50%
:alt: The voltage points to measure
The voltage points to measure (click to enlarge)
+------------------+-----------------+
| Point | Voltage |
+==================+=================+
| VBUS | 5.2V |
+------------------+-----------------+
| VBAT | 4.2V |
+------------------+-----------------+
| VBAT\ :sub:`REG` | 4.2V |
+------------------+-----------------+
| 5V\ :sub:`SOM` | 5.0V |
+------------------+-----------------+
| 3V3 | 3.3V |
+------------------+-----------------+
| 3V3\ :sub:`P` | ~0(without SOM) |
+------------------+-----------------+
Each voltage is measured against ground (green circle in above image).
3. Plug in the SOM.
Attaching a USB to Serial Adapter
---------------------------------
.. _attach-usb-to-serial-adapter-1:
1. Solder in the UART debug plug
2. Attach USB to Serial Adapter
.. figure:: images/uart-pinout.png
:scale: 50%
:alt: UART pinout (click to enlarge)
UART pinout
+-----+-------+
| PIN | Color |
+=====+=======+
| 1 | black |
+-----+-------+
| 2 | n/c |
+-----+-------+
| 3 | n/c |
+-----+-------+
| 4 | green |
+-----+-------+
| 5 | white |
+-----+-------+
| 6 | n/c |
+-----+-------+
PIN 1 is the one closest to the volume button while PIN 6 is the one
closest to the power button.
Booting via nfsroot
-------------------
The SOM comes with a pre-flashed u-boot so you can connect the
USB-to-UART-Debug cable and boot the device. Breaking into uboot you can
boot using a nfsroot filesystem via
::
setenv nfsrootboot "setenv bootargs ${args_common} debug root=/dev/nfs ip=:::::eth0:dhcp nfsrootdebug nfsroot=<nfsserverip>:<nfsrootpath>,v3,tcp; dhcp ${loadaddr} Image-librem5-devkit; dhcp ${fdt_addr} librem5-devkit.dtb; booti ${loadaddr} - ${fdt_addr}"
setenv bootcmd run nfsrootboot
saveenv
boot
You need to fill in **nfsrootpath** and **nfsserverip** above. At
**nfsrootpath** there needs to be a armhf or arm64 root filesystem which
you can e.g. create via Debian's deboostrap.
For that to work the **BOOT MODE** switch needs to be set to **eMMC**
(instead of **USB**).
Installing a Minimal Linux on the eMMC
--------------------------------------
You can use ``dd`` to copy a pre-built image onto the eMMC or you can just use
``debootstrap`` to create one from scratch. This can be useful if you don't
want that many services starting up by default:
.. code:: bash
e2fsck /dev/mmcblk0p2
mount /dev/mmcblk0p2 /mnt
debootstrap --arch=arm64 buster /mnt
Back in u-boot we can switch to using the rootfs on the eMMC then (we're
still pulling kernel and device tree via tftp though:
::
setenv emmcboot "setenv bootargs ${args_common} debug root=/dev/mmcblk0p2; dhcp ${loadaddr} Image-librem5-devkit; dhcp ${fdt_addr} librem5-devkit.dtb; booti ${loadaddr} - ${fdt_addr}"
Flashing u-boot
---------------
From u-boot using tftp
~~~~~~~~~~~~~~~~~~~~~~
You must have a tftp server setup for this:
::
setenv ipaddr <tftp server ip>
setenv serverip <target ip addr>
tftp 0x43000000 u-boot-devkit-recovery.imx
mmc write 0x43000000 0x42 0x800
From the kernel command line
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Download the u-boot binary ``u-boot-devkit-recovery.imx``:
::
dd if=u-boot-devkit-recovery.imx of=/dev/mmcblk0 bs=1024 seek=33
Reflashing the RS9116
---------------------
By default no rsi\ :sub:`\*` modules get loaded. The modules without
firmware are in
"/lib/modules/<kernel:sub:`ver`>/drivers/net/wireless/rsi" . The
create\ :sub:`initramfs` script above adds the rsi firmware and reflash
modules in "/usr/src".
There is a convenience script "flash:sub:`rsi`.sh" that wiil perform the
necessary steps. What the script does is it backs up the rsi modules in
/lib/modules, copies the firmware into lib firmware and the modprobes
the rsi flashing modules. It replaces the original modules when it's
done.
Run the script on the target to reflash.::
root@pureos-test:~# flash_rsi.sh
Creating a Test initramfs
-------------------------
Download the latest image and kernel
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Download the latest kernel and RS9116 out of tree modules.::
./scripts/fetch_latest.sh -k
Extract the kernel
~~~~~~~~~~~~~~~~~~
The kernel needs to be extracted from the deb for the SDP boot.::
./scripts/extract_kernel.sh
Build the test filesystem tarball
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This will create a minimal debian rootfs tarball to be used to create an
initramfs. If you need additional packages you can add them to the
packages variable in the script.::
./scripts/create_tarball.sh
Create the initramfs
~~~~~~~~~~~~~~~~~~~~
This will take the tarball created above and customize it to be able to
flash the RS9116 module and also adds some test scripts.::
./scripts/create_initramfs.sh -t build/test_rootfs.tgz -o files/test_initramfs.img
You can include a locally generated kernel, modules and devicetree as
well.::
./scripts/create_initramfs.sh -t build/test_rootfs.tgz -o files/test_initramfs.img -i <path to kernel>
Boot the initramfs
~~~~~~~~~~~~~~~~~~
The initramfs can be booted on a board with an empty eMMC for testing
and RS9116 flashing. Ensure the boot mode switch is switched to USB
boot. Run the command below and then plug in the USB C port of the
devkit.::
sudo uuu uuu_scripts/test_librem5.lst
RS9116 normal operation
~~~~~~~~~~~~~~~~~~~~~~~
To use the RS9116 without flashing just load the modules by hand.::
root@pureos-test:~# modprobe rsi_sdio
.. _imx8_devkit:
i.MX8 Development Board
=======================
Librem 5 Development Kit
========================
.. note:: This page is incomplete and is being revised.
Installing the SOM
------------------
The scripts mentioned on this page can be obtained from the `librem5-devkit-tools`_
repository.
.. If the SOM is not yet installed
If you experience problems with the development kit, you may find it useful to
consult the :ref:`imx8_devkit_troubleshooting` guide.
Power board without SOM via USB-C
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. _`librem5-devkit-tools`: https://source.puri.sm/Librem5/librem5-devkit-tools
Check the voltages
~~~~~~~~~~~~~~~~~~
.. Sections to add:
What's in the box
plugging in via USB-C (power adaptor vs. hub),
connecting via ssh, connecting HDMI, mouse, keyboard
900mA supply
Host mode, hub, no serial out
Device mode, serial
USB 2 to USB 3 hub to USB-C devkit
FTDI cables USB-to-serial
.. figure:: images/voltage-points.png
:scale: 50%
:alt: The voltage points to measure
.. contents::
The voltage points to measure (click to enlarge)
+------------------+-----------------+
| Point | Voltage |
+==================+=================+
| VBUS | 5.2V |
+------------------+-----------------+
| VBAT | 4.2V |
+------------------+-----------------+
| VBAT\ :sub:`REG` | 4.2V |
+------------------+-----------------+
| 5V\ :sub:`SOM` | 5.0V |
+------------------+-----------------+
| 3V3 | 3.3V |
+------------------+-----------------+
| 3V3\ :sub:`P` | ~0(without SOM) |
+------------------+-----------------+
Each voltage is measured against ground (green circle in above image).
Connecting the Board to a Power Supply
--------------------------------------
Plugin the SOM
~~~~~~~~~~~~~~
In the default configuration, as shipped, USB in is peripheral mode and a
"wall wart" AC adaptor is used for power.
Attach USB to serial adapter
----------------------------
Alternate Configuration #1 - USB C Console
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Solder in the UART debug plug
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1. Attach the development board to a USB C or USB 3 port on the host that is
capable of providing 900mA of current.
.. _attach-usb-to-serial-adapter-1:
2. ~30 seconds after boot a new device will appear at ``/dev/ttyACM0`` -- this
is a serial console to the development board.
Attach USB to serial Adapter
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If your PC cannot provide the necessary power you may need a USB 3 powered hub
between the host and the development board.
.. figure:: images/uart-pinout.png
:scale: 50%
:alt: UART pinout (click to enlarge)
Alternate Configuration #2 - USB C Host
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
UART pinout
In this configuration, USB host mode is used to allow keyboard, mouse and flash
memory sticks to be connected to the development board.
+-----+-------+
| PIN | Color |
+=====+=======+
| 1 | black |
+-----+-------+
| 2 | n/c |
+-----+-------+
| 3 | n/c |
+-----+-------+
| 4 | green |
+-----+-------+
| 5 | white |
+-----+-------+
| 6 | n/c |
+-----+-------+
1. On the target, backup the device tree and copy in the USB host version::
PIN 1 is the one closest to the volume button while PIN 6 is the one
closest to the power button.
cp /boot/dtbs/librem5-evk.dtb /boot/dtbs/librem5-evk.dtb.bak
cp /boot/dtbs/librem5-evk-usbhost.dtb /boot/dtbs/librem5-evk.dtb
2. Attach a USB C hub to the development board.
3. Attach power to the USB C hub.
4. Plug in USB devices and they should appear in the output of the ``dmesg``
and ``lsusb`` tools.
Power on/off
------------
If the user holds the power button for ~2 seconds then a power
down/reboot dialog would pop up; a quick press & release would turn the
display on/off. If the button is held for ~5 seconds the SoC triggers an
event to shut down, pressing it again for ~2 seconds will turn it back
on. The button is also attached to the charge controller's QON# pin,
which when held for ~15 seconds is able to put the dev kit into a
"shipping mode" where the charge controller is completely off, or
holding it for ~18 seconds will cause it to perform a complete power
cycle.
Booting via nfsroot
-------------------
The SOM comes with a pre-flashed u-boot so you can connect the
USB-to-UART-Debug cable and boot the device. Breaking into uboot you can
boot using a nfsroot filesystem via
::
setenv nfsrootboot "setenv bootargs ${args_common} debug root=/dev/nfs ip=:::::eth0:dhcp nfsrootdebug nfsroot=<nfsserverip>:<nfsrootpath>,v3,tcp; dhcp ${loadaddr} Image-librem5-devkit; dhcp ${fdt_addr} librem5-devkit.dtb; booti ${loadaddr} - ${fdt_addr}"
setenv bootcmd run nfsrootboot
saveenv
boot
You need to fill in **nfsrootpath** and **nfsserverip** above. At
**nfsrootpath** there needs to be a armhf or arm64 root filesystem which
you can e.g. create via Debian's deboostrap.
On a development kit with an operating system installed, if the user holds the
power button for ~2 seconds then a power down/reboot dialog should pop up; a
quick press and release should turn the display on/off.
For that to work the **BOOT MODE** switch needs to be set to **eMMC**
(instead of **USB**).
If the button is held for ~5 seconds the SoC triggers an event to shut down;
pressing it again for ~2 seconds will turn it back on.
Installing a minimal Linux on the eMMC
--------------------------------------
You can use ``dd`` to copy a pre-built image onto the eMMC or you can just use
``debootstrap`` to create one from scratch. This can be useful if you don't
want that many services starting up by default:
.. code:: bash
e2fsck /dev/mmcblk0p2
mount /dev/mmcblk0p2 /mnt
debootstrap --arch=arm64 buster /mnt
Back in u-boot we can switch to using the rootfs on the eMMC then (we're
still pulling kernel and device tree via tftp though:
::
setenv emmcboot "setenv bootargs ${args_common} debug root=/dev/mmcblk0p2; dhcp ${loadaddr} Image-librem5-devkit; dhcp ${fdt_addr} librem5-devkit.dtb; booti ${loadaddr} - ${fdt_addr}"
The button is also attached to the charge controller's QON# pin, which when
held for ~15 seconds is able to put the dev kit into a "shipping mode" where
the charge controller is completely off, or holding it for ~18 seconds will
cause it to perform a complete power cycle.
Install uuu
-----------
By hand
.. There is apparently a Debian package for this.
By Hand
~~~~~~~
The NXP mfgtool uuu is required to boot a board that has no bootloader
or is otherwise "bricked". Either download, build and install uuu :
The NXP mfgtool ``uuu`` is required to boot a board that has no bootloader
or is otherwise "bricked". Either download, build and install ``uuu``:
::
......@@ -150,21 +93,60 @@ or is otherwise "bricked". Either download, build and install uuu :
make
sudo make install
Using the convenient script
Using the Convenient Script
~~~~~~~~~~~~~~~~~~~~~~~~~~~
Alternatively, you can use this script from the `librem5-devkit-tools`_
repository to build and install ``uuu``:
::
scripts/build_uuu.sh -i
Udev Rules
----------
If you want to run ``uuu`` as non-root add the following udev rules
.. code:: bash
cat <<EOF > /etc/udev/rules.d/99_librem5_devkit.rules
SUBSYSTEM!="usb", GOTO="librem5_devkit_rules_end"
# Devkit USB flash
ATTR{idVendor}=="1fc9", ATTR{idProduct}=="012b", GROUP+="plugdev", TAG+="uaccess"
ATTR{idVendor}=="0525", ATTR{idProduct}=="a4a5", GROUP+="plugdev", TAG+="uaccess"
ATTR{idVendor}=="0525", ATTR{idProduct}=="b4a4", GROUP+="plugdev", TAG+="uaccess"
LABEL="librem5_devkit_rules_end"
EOF
sudo udevadm control -R
sudo adduser <youruser> plugdev
newgrp plugdev
Make sure you replug the serial cable in case you have plugged it in
already. With the above rules you can skip the ``sudo`` in front of the
``uuu`` invocations below.
.. _imx8_devkit_flash_test_image:
Flash the Test Image
--------------------
The eMMC that gets flashed is ``files/devkit-test.img``. Put the "Boot
Mode" switch in the USB position.
**This will erase everything on your eMMC:**
::
scripts/get_image.sh
sudo uuu uuu_scripts/flash_librem5-devkiti-test.lst
Download Target Binaries
------------------------
~~~~~~~~~~~~~~~~~~~~~~~~
You can manually download or build the required binaries. There is also
a convenience script to download pre-built binaries from the Purism
servers.
::
servers.::
scripts/fetch_latest.sh -xk
......@@ -187,27 +169,6 @@ You can also just boot to u-boot without flashing anything:
sudo uuu uuu_scripts/u-boot_librem5-devkit.lst
From u-boot using tftp
~~~~~~~~~~~~~~~~~~~~~~