Commit ebb60cec authored by Guido Gunther's avatar Guido Gunther

Merge branch 'devkit' into 'master'

Rearranged the development kits, adding some i.MX8 information

See merge request Librem5/!94
parents b86e085f 96098af3
Pipeline #2678 passed with stage
in 3 minutes and 48 seconds
......@@ -4,7 +4,9 @@ Setting up a Development Environment
.. toctree::
:maxdepth: 2
......@@ -4,8 +4,7 @@ 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.
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
......@@ -16,10 +15,13 @@ Also take a look at the :ref:`mini-tutorials` page for some common
commands and some application setup that is not board specific.
.. toctree::
:maxdepth: 1
:maxdepth: 2
.. _`EmCraft i.MX 8M SoM`:
.. _dev-kit:
Dev Kit
This page will be populated with information on the i.MX8 based dev kits
once they are finalized and shipped. Check back for updates!
.. toctree::
.. _imx6:
i.MX6 Development Board
The current development board is the Boundarydevices `Nitrogen board <>`_ with i.MX6 Quad plus CPU. This page describes how to set it up for development.
The original development board for the Librem 5 was the Boundary Devices
`Nitrogen board <>`_
with i.MX6 Quad plus CPU. This board has been replaced for Librem 5 development
by the :ref:`imx8_devkit`.
This page has been retained for informational purposes, and describes how to
set it up for development.
Package contents
.. _legacy_devkits:
Legacy Development Kits
This section contains information on Librem 5 development kits that were not
generally available or are considered to be obsolete for current development.
.. toctree::
.. _imx8_devkit:
i.MX8 Development Board
.. note:: This page is incomplete and is being revised.
Installing the SOM
.. If the SOM is not yet installed
Power board without SOM via USB-C
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).
Plugin the SOM
Attach USB to serial adapter
Solder in the UART debug plug
.. _attach-usb-to-serial-adapter-1:
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.
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
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
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}"
Install uuu
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 :
git clone
cd mfgtools
cmake ./
sudo make install
Using the convenient script
scripts/ -i
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
scripts/ -xk
Flash u-boot
Using SDP
The uboot that gets flashed is ``files/u-boot-devkit-recovery.imx``. Put
the "Boot Mode" switch in the USB position:
sudo uuu uuu_scripts/u-boot_flash_librem5-devkit.lst
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
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
Flash eMMC
.. _using-sdp-1:
Using SDP
The eMMC that gets flashed is files/devkit.img . Put the "Boot Mode"
switch in the USB position.
**This will erase everything on your eMMC:**
sudo uuu uuu_scripts/flash_librem5-devkit.lst
Create test initramfs
Download the latest image and kernel
Download the latest kernel and RS9116 out of tree modules.
./scripts/ -k
Extract the kernel
The kernel needs to be extracted from the deb for the SDP boot.
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.
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/ -t build/test_rootfs.tgz -o files/test_initramfs.img
You can include a locally generated kernel, modules and devicetree as
./scripts/ -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
sudo uuu uuu_scripts/test_librem5.lst
Reflash 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
Run the script on the target to reflash.
RS9116 normal operation
To use the RS9116 without flashing just load the modules by hand.
root@pureos-test:~# modprobe rsi_sdio
Hardware Components
LCD Panel
The panel is a Rockchip JH057N00900 (5.7", TFT 720*1440 Pixels) using a
ST7703 IC.
.. _real-hardware:
Real hardware
.. toctree::
......@@ -21,8 +21,6 @@ with the `Nitrogen6 MAX i.MX6 board <
Once the i.MX8 CPU was released, and the
`EmCraft i.MX 8M SoM <>`_
was available, a few were ordered so the rest of the dev board
could be designed around this EmCraft SoM. Until the dev kit is
available, the :ref:`Dev-kit` page will remain empty. However
once the dev kit *is* available, this is where you will find
complete information on the hardware and how to set up your dev
could be designed around this EmCraft SoM. The :ref:`imx8_devkit` page is where
you will find information on the hardware and how to set up your development
kit to start using it.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment