From c4d986fc23825071116626943b3b3f75b955e1ff Mon Sep 17 00:00:00 2001 From: David Boddie Date: Tue, 9 Apr 2019 18:05:54 +0200 Subject: [PATCH 01/13] Mention initial setup and reflashing, split into guides --- Development_Environment/Boards/HowTo.rst | 3 + .../Boards/HowTo/Building_uuu.rst | 57 +++++++ .../Boards/HowTo/Flashing_eMMC.rst | 147 ++++++++++++++++++ .../Boards/HowTo/Initial_Test_Run.rst | 89 +++++++++++ .../Boards/HowTo/USB_Access.rst | 2 +- Development_Environment/Boards/imx8.rst | 58 ++----- links.txt | 1 + 7 files changed, 313 insertions(+), 44 deletions(-) create mode 100644 Development_Environment/Boards/HowTo/Building_uuu.rst create mode 100644 Development_Environment/Boards/HowTo/Flashing_eMMC.rst create mode 100644 Development_Environment/Boards/HowTo/Initial_Test_Run.rst diff --git a/Development_Environment/Boards/HowTo.rst b/Development_Environment/Boards/HowTo.rst index 6ccd79e..90a42d6 100644 --- a/Development_Environment/Boards/HowTo.rst +++ b/Development_Environment/Boards/HowTo.rst @@ -10,8 +10,11 @@ how to perform routine tasks. :maxdepth: 1 HowTo/Bluetooth_Connections + HowTo/Building_uuu HowTo/Data_Connections HowTo/Ethernet_over_USB + HowTo/Flashing_eMMC + HowTo/Initial_Test_Run HowTo/Install_Plasma_Mobile HowTo/Inertial_Module HowTo/Location_Services diff --git a/Development_Environment/Boards/HowTo/Building_uuu.rst b/Development_Environment/Boards/HowTo/Building_uuu.rst new file mode 100644 index 0000000..9ee9369 --- /dev/null +++ b/Development_Environment/Boards/HowTo/Building_uuu.rst @@ -0,0 +1,57 @@ +.. _imx8_devkit_howto_building_uuu: + +Building uuu from Source +======================== + +If you are not using ``uuu`` included in your favorite distribution, you can +build it manually instead. On a Debian-based system, you will need to install +some dependencies before building:: + + sudo apt-get -y install libusb-1.0-0-dev libzip-dev libbz2-dev + +Then you can proceed with the build:: + + git clone https://source.puri.sm/Librem5/mfgtools + mkdir mfgtools-build + cd mfgtools-build + cmake ../mfgtools + make + +The ``uuu`` binary will find itself in ``mfgtools-build/uuu/uuu``. + +Udev Rules +---------- + +We recommend running ``uuu`` as an unprivileged user. On Debian-based systems, issue the following commands **as root** to make the development board accessible to your user over USB whenever it's connected: + +.. code:: bash + + cat < /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 + udevadm control -R + +Users of non-Debian systems may need to add the ``plugdev`` group if it does not already exist. This group grants permission to its members to access the devices it owns: + +.. code:: bash + + groupadd plugdev + +You will need to add your user to the ``plugdev`` group to access the development board: + +.. code:: bash + + sudo usermod -a -G plugdev $USER + +You can log in to the new group without having to log out by running this command: + +.. code:: bash + + newgrp plugdev + +Next time you plug in the USB cable, the development board's USB interface will be accessible by your user. diff --git a/Development_Environment/Boards/HowTo/Flashing_eMMC.rst b/Development_Environment/Boards/HowTo/Flashing_eMMC.rst new file mode 100644 index 0000000..eeb19a9 --- /dev/null +++ b/Development_Environment/Boards/HowTo/Flashing_eMMC.rst @@ -0,0 +1,147 @@ +.. _imx8_devkit_flashing_emmc: + +Flashing the eMMC +================= + +The main purpose of the image included on the eMMC is factory testing, therefore it's strongly recommended to flash an up-to-date one immediately. + +The scripts mentioned in this section can be obtained from the `librem5-devkit-tools`_ repository. + +Install uuu +----------- + +The NXP mfgtool ``uuu`` is required to boot a board that has no bootloader +or is otherwise "bricked". + +You can obtain a package for Debian-based systems from `the Purism CI server`_ +or :ref:`build uuu from source `. + +To install the package, run the ``dpkg`` tool in the following way:: + + sudo dpkg -i uuu_1.2.31-2~300.gbp6983a9_amd64.deb + +The precise ``.deb`` package file name may differ from the one given above. + +.. _`the Purism CI server`: https://arm01.puri.sm/job/debs/job/deb-mfgtools-buster-amd64/ + +Downloading Flashing Scripts +---------------------------- + +Files from the `librem5-devkit-tools`_ repository are responsible for the downloading of the image files, and for coordinating their transfers to the dev kit. + +Check out the repository before proceeding. + +.. _imx8_devkit_flash_test_image: + +Flash the Image +--------------- + +**Note:** If your workstation cannot provide the necessary power for this +process you may need a USB 3 powered hub between the host and the development +board. + +Put the "Boot Mode" switch in the USB position. Attach the development board +to a USB C or USB 3 port on the host that is capable of providing 900mA of +current. The HID device should appear in the output of the ``lsusb`` command, +like this:: + + Bus 001 Device 005: ID 1fc9:012b NXP Semiconductors + +The ``librem5-devkit-flash-image`` script will download and flash the newest +available rootfs and U-Boot images. You may need to install some Python modules +before running the script. On Debian 9 (Stretch), Ubuntu 18.04 LTS (Bionic +Beaver) and later, this command should install these modules:: + + sudo apt-get -y install python3-jenkins python3-tqdm python3-yaml + +Now you can proceed with the flashing, using the script as shown below to +download temporary copies of U-Boot, kernel and the base system, before +flashing them on the board. Use the ``--skip-cleanup`` and ``--dir`` command +line options to keep the downloaded files after flashing. + +**This will erase everything on the board's eMMC:** + +.. code:: bash + + cd librem5-devkit-tools + export PATH=$PATH:/path-to-your-workspace/mfgtools-build/uuu/ + ./scripts/librem5-devkit-flash-image + +If you use the ``--dir`` option to download the files into a directory and +``--skip-cleanup`` to keep them after flashing, you can re-flash the eMMC using +the same files by entering the download directory and running ``uuu``. +For example, this is how you would download the files to the ``/tmp/devkit`` +directory and flash the eMMC, then re-flash it later as required. + +**This will erase everything on the board's eMMC:** + +.. code:: bash + + cd librem5-devkit-tools + export PATH=$PATH:/path-to-your-workspace/mfgtools-build/uuu/ + ./scripts/librem5-devkit-flash-image --dir /tmp/devkit --skip-cleanup + + # Re-flash the eMMC later: + cd /tmp/devkit + uuu flash_devkit.lst + +It can also be useful to use the ``--skip-flash`` if you only want to download +the files without flashing the eMMC. + +Reboot +------ + +Flip the boot switch back to eMMC position and press the reboot button. The +output of the ``lsusb`` command should show a multifunction gadget, like this:: + + Bus 003 Device 068: ID 1d6b:0104 Linux Foundation Multifunction Composite Gadget + +The serial console should appear at ``/dev/ttyACM0``, and a new newtwork interface will appear, confirming a successful reflash. + +As usual, don't hesitate to `get in touch`_ if you find yourself stuck. + +.. _imx8_devkit_lcd_display: + +HDMI +---- + +After flashing the latest image, connect to it using serial console in the same way as previously, and log in as ``root``. + +Copy the ``librem5-evk-hdmi.dtb`` file to the correct place:: + + root@pureos:~# cp /boot/dtbs/librem5-evk.dtb /boot/dtbs/librem5-evk.dtb.bak + root@pureos:~# cp /usr/lib/linux-image-`uname -r`/freescale/librem5-evk-hdmi.dtb /boot/dtbs/librem5-evk.dtb + +**Note:** The LCD panel is disabled when using this `dtb` file. + +Connect the HDMI monitor and reboot the system:: + + root@pureos:~# reboot + +After the system exits u-boot, a row of penguins will appear in the top-left +corner of the monitor. Afterwards, Phosh will occupy the display, showing a +login screen on a gray background. + +Flash U-Boot +------------ + +If you only need to flash a new version of U-Boot onto the eMMC then follow +these instructions instead of running the ``librem5-devkit-flash-image`` script. + +Using SDP +~~~~~~~~~ + +The version of U-Boot that gets flashed is ``files/u-boot-devkit-recovery.imx``. +Put the "Boot Mode" switch in the USB position:: + + cd librem5-devkit-tools + export PATH=$PATH:/path-to-your-workspace/mfgtools-build/uuu/ + uuu uuu_scripts/u-boot_flash_librem5-devkit.lst + +You can also just boot to U-Boot without flashing anything:: + + cd librem5-devkit-tools + export PATH=$PATH:/path-to-your-workspace/mfgtools-build/uuu/ + uuu uuu_scripts/u-boot_librem5-devkit.lst + +.. include:: /links.txt diff --git a/Development_Environment/Boards/HowTo/Initial_Test_Run.rst b/Development_Environment/Boards/HowTo/Initial_Test_Run.rst new file mode 100644 index 0000000..49c501a --- /dev/null +++ b/Development_Environment/Boards/HowTo/Initial_Test_Run.rst @@ -0,0 +1,89 @@ +.. _imx8_devkit_initial_test_run: + +Initial Test Run +---------------- + +There are two simple ways to verify that the development board is +functioning. It is useful to try both of these to ensure that you can access +the board via serial and Ethernet connections. + +If neither of these procedures work for you, please `get in touch`_. + +First of all, make sure that the boot mode switch is set to eMMC -- see the +labelled photo below. + +.. figure:: ../images/dev-board-sockets-buttons-switches.png + :scale: 50% + :align: center + :alt: Ports, right hand side, top to bottom: 3.5mm audio socket, RJ45 + Ethernet socket, mini HDMI socket, USB C socket, micro SD card + socket. + Kill switch side, left to right: reset button, boot mode switch, + camera + microphone kill switch, cellular kill switch, Wi-Fi kill + switch. + Button side, right to left: smart card socket, volume down button, + volume up button, power button, micro SIM card socket. + +.. _imx8_devkit_usb_console: + +USB Console +~~~~~~~~~~~ + +Connect the board to a workstation using the USB A to USB C cable provided. +The haptic motor will sound briefly and the board should appear shortly +after as a USB serial device to the workstation. + +:: + + Bus 003 Device 025: ID 0525:a4a7 Netchip Technology, Inc. Linux-USB Serial Gadget (CDC ACM mode) + +It will appear in the ``/dev/`` directory as a serial port, such as +``/dev/ttyACM0``, which you can use to access the board's serial console if +you have permission to read and write to that device:: + + picocom -b 115200 /dev/ttyACM0 + +This should produce the output like this:: + + Debian GNU/Linux buster/sid pureos-test ttyGS0 + + pureos-test login: + +It should be possible to log in using ``purism`` as the user name and ``123456`` +as the password. + +**Note:** You may have trouble accessing the serial device if your user is not +a member of the ``dialout`` group on your workstation. For example, you may get +an error like this:: + + FATAL: cannot open /dev/ttyACM0: Permission denied + +In this case, you can either add your user to the ``dialout`` group or, as a +workaround, run ``picocom`` using the ``sudo`` command. + +.. _imx8_devkit_ethernet: + +Ethernet Connection +~~~~~~~~~~~~~~~~~~~ + +Connect the board to a network using the Ethernet socket and a suitable +cable. Connect the board to the provided power supply using the provided +cable. Two green LEDs will immediately light up between the SoM and the +battery holder. After a moment, the orange Ethernet light should start +blinking and the haptic motor will sound briefly. The board should be +accessible over the network via SSH. + +The image shipped with the boards will claim the IP address ``192.168.42.202`` with the ``/24`` netmask. Later images will try to obtain an IP address using DHCP -- see below for information. + +It should be possible to log in using ``purism`` as the user name and +``123456`` as the password:: + + $ ssh purism@192.168.42.202 + +If you update the image on the development board, it will try to obtain an IP address using DHCP. You will need to determine this address by accessing the DHCP client table for your local network. For example, if the board has been assigned the IP address ``192.168.1.110`` you can log in with the following command:: + + $ ssh purism@192.168.1.110 + +If you have difficulty determining the IP address of the board in the case where it uses DHCP, please contact your local network administrator for assistance. + +.. include:: /links.txt diff --git a/Development_Environment/Boards/HowTo/USB_Access.rst b/Development_Environment/Boards/HowTo/USB_Access.rst index 2d5660b..977f8a8 100644 --- a/Development_Environment/Boards/HowTo/USB_Access.rst +++ b/Development_Environment/Boards/HowTo/USB_Access.rst @@ -5,7 +5,7 @@ In the default configuration, as shipped, USB in is peripheral mode and a "wall wart" AC adaptor can be used for power. In this mode, it is also possible to connect the development board to a workstation's USB **3.0+** port (where VBUS can supply up to 900mA) and access a serial console, as described in -:ref:`devkit_test_run`. +:ref:`imx8_devkit_initial_test_run`. Alternate Configuration - USB C Host ------------------------------------ diff --git a/Development_Environment/Boards/imx8.rst b/Development_Environment/Boards/imx8.rst index 4ada2c9..2923993 100644 --- a/Development_Environment/Boards/imx8.rst +++ b/Development_Environment/Boards/imx8.rst @@ -47,8 +47,7 @@ The dev kit accepts the following items, not included in the package: - a Mini/2FF GPG smart card (25x15mm) Notably, the development board has an Ethernet port, a single USB-C port, and -a Mini-HDMI port. The attached display does not function correctly at the -time of writing (2018-12-09), so an external display is highly recommended. +a Mini-HDMI port. .. _dev_board_figure: @@ -80,30 +79,26 @@ time of writing (2018-12-09), so an external display is highly recommended. See :ref:`hardware_reference` for information about the specific parts used for the sockets, buttons and switches. -.. _devkit_test_run: +Setting up the Board +-------------------- -Test Run --------- +In its original factory state, the board is lacking some essential features. We +recommend that you consider :ref:`imx8_devkit_flashing_emmc` before using the +board for development. However, you may want to consider performing an +:ref:`imx8_devkit_initial_test_run` to verify that the board can be powered on +and recognized by your workstation before reflashing the eMMC. -There are two simple ways to verify that the development board is -functioning. It is useful to try both of these to ensure that you can access -the board via serial and Ethernet connections. - -If neither of these procedures work for you, please `get in touch`_. - -First of all, make sure that the boot mode switch is set to eMMC -- see the -`labelled photo `_ above. - -.. _`get in touch`: https://developer.puri.sm/Librem5/Contact.html - -.. _imx8_devkit_usb_console: +It may also be useful to consult the :ref:`imx8_devkit_known_issues` page and +:ref:`imx8_devkit_troubleshooting` guide if problems occur. Updating the Software --------------------- -There are three main software components that can be updated: the bootloader, -the kernel and the distribution packages. The installed packages can be updated -in the normal way using the``apt`` tool to update and upgrade them:: +After the image on the development board has been :ref:`updated from the original +factory image `, there are three main software +components that can be updated: the bootloader, the kernel and the distribution +packages. The installed packages can be updated in the normal way using +the``apt`` tool to update and upgrade them:: sudo apt update sudo apt full-upgrade @@ -369,29 +364,6 @@ 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. -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: - -:: - - cd librem5-devkit-tools - export PATH=$PATH:/path-to-your-workspace/mfgtools-build/uuu/ - uuu uuu_scripts/u-boot_flash_librem5-devkit.lst - -You can also just boot to u-boot without flashing anything: - -:: - - cd librem5-devkit-tools - export PATH=$PATH:/path-to-your-workspace/mfgtools-build/uuu/ - uuu uuu_scripts/u-boot_librem5-devkit.lst - Configure Wi-Fi --------------- diff --git a/links.txt b/links.txt index dce6621..bdb548c 100644 --- a/links.txt +++ b/links.txt @@ -16,6 +16,7 @@ .. _`Flatpak documentation`: http://docs.flatpak.org/en/latest/ .. _`Freedesktop quick reference`: http://docs.flatpak.org/en/latest/freedesktop-quick-reference.html .. _`GdkPixbuf.Pixbuf`: https://lazka.github.io/pgi-docs/#GdkPixbuf-2.0/classes/Pixbuf.html +.. _`get in touch`: https://developer.puri.sm/Librem5/Contact.html .. _`Gio.GApplication documentation`: https://developer.gnome.org/gio/stable/GApplication.html#g-application-id-is-valid .. _`Gio.Menu`: https://lazka.github.io/pgi-docs/#Gio-2.0/classes/Menu.html .. _`git-buildpackage`: http://honk.sigxcpu.org/projects/git-buildpackage/manual-html/gbp.html -- GitLab From 19752090db869b7870e39a3f567481ef8f8e337c Mon Sep 17 00:00:00 2001 From: David Boddie Date: Wed, 10 Apr 2019 16:09:49 +0200 Subject: [PATCH 02/13] Put flashing back in the main page, turn other sections into How To guides --- Development_Environment/Boards/HowTo.rst | 2 + .../Boards/HowTo/Bluetooth_Connections.rst | 28 ++- .../Boards/HowTo/Flashing_eMMC.rst | 124 ---------- .../Boards/HowTo/Making_Cases.rst | 9 + .../Boards/HowTo/Updating_Software.rst | 26 ++ .../Boards/HowTo/Wireless_Networking.rst | 31 +++ Development_Environment/Boards/imx8.rst | 230 ++---------------- 7 files changed, 109 insertions(+), 341 deletions(-) create mode 100644 Development_Environment/Boards/HowTo/Making_Cases.rst create mode 100644 Development_Environment/Boards/HowTo/Updating_Software.rst diff --git a/Development_Environment/Boards/HowTo.rst b/Development_Environment/Boards/HowTo.rst index 90a42d6..e6e582a 100644 --- a/Development_Environment/Boards/HowTo.rst +++ b/Development_Environment/Boards/HowTo.rst @@ -18,10 +18,12 @@ how to perform routine tasks. HowTo/Install_Plasma_Mobile HowTo/Inertial_Module HowTo/Location_Services + HowTo/Making_Cases HowTo/Proximity HowTo/Rebuilding_the_Kernel HowTo/Simple_Input_Output HowTo/SSH_Access HowTo/Touchscreen + HowTo/Updating_Software HowTo/USB_Access HowTo/Wireless_Networking diff --git a/Development_Environment/Boards/HowTo/Bluetooth_Connections.rst b/Development_Environment/Boards/HowTo/Bluetooth_Connections.rst index d10a8fc..9f0ceda 100644 --- a/Development_Environment/Boards/HowTo/Bluetooth_Connections.rst +++ b/Development_Environment/Boards/HowTo/Bluetooth_Connections.rst @@ -3,16 +3,36 @@ Bluetooth Connections ===================== -Once you have :ref:`configured Bluetooth ` for -the development board, you can check that it can be paired with other devices -and used for data transfer with the following instructions. - .. contents:: :local: +Configure Bluetooth +------------------- + +Before attempting to use Bluetooth, ensure that the Wi-Fi/Bluetooth switch is +set to the ON position on the board. + +To enable Bluetooth you must first make sure the relevant module is loaded:: + + modprobe rsi_sdio + +It should then be possible to query the Bluetooth device:: + + hcitool dev + +This should produce output like this:: + + Devices: + hci0 88:DA:1A:9E:BA:95 + +The exact device address will be different for your board. + Finding Another Device ---------------------- +Once you have for the development board, you can check that it can be paired +with other devices and used for data transfer with the following instructions. + Ensure that the Wi-Fi/Bluetooth switch is set to the ON position on the board. From a workstation, log in to the development board using either ``ssh`` or diff --git a/Development_Environment/Boards/HowTo/Flashing_eMMC.rst b/Development_Environment/Boards/HowTo/Flashing_eMMC.rst index eeb19a9..e3831d5 100644 --- a/Development_Environment/Boards/HowTo/Flashing_eMMC.rst +++ b/Development_Environment/Boards/HowTo/Flashing_eMMC.rst @@ -1,127 +1,3 @@ -.. _imx8_devkit_flashing_emmc: - -Flashing the eMMC -================= - -The main purpose of the image included on the eMMC is factory testing, therefore it's strongly recommended to flash an up-to-date one immediately. - -The scripts mentioned in this section can be obtained from the `librem5-devkit-tools`_ repository. - -Install uuu ------------ - -The NXP mfgtool ``uuu`` is required to boot a board that has no bootloader -or is otherwise "bricked". - -You can obtain a package for Debian-based systems from `the Purism CI server`_ -or :ref:`build uuu from source `. - -To install the package, run the ``dpkg`` tool in the following way:: - - sudo dpkg -i uuu_1.2.31-2~300.gbp6983a9_amd64.deb - -The precise ``.deb`` package file name may differ from the one given above. - -.. _`the Purism CI server`: https://arm01.puri.sm/job/debs/job/deb-mfgtools-buster-amd64/ - -Downloading Flashing Scripts ----------------------------- - -Files from the `librem5-devkit-tools`_ repository are responsible for the downloading of the image files, and for coordinating their transfers to the dev kit. - -Check out the repository before proceeding. - -.. _imx8_devkit_flash_test_image: - -Flash the Image ---------------- - -**Note:** If your workstation cannot provide the necessary power for this -process you may need a USB 3 powered hub between the host and the development -board. - -Put the "Boot Mode" switch in the USB position. Attach the development board -to a USB C or USB 3 port on the host that is capable of providing 900mA of -current. The HID device should appear in the output of the ``lsusb`` command, -like this:: - - Bus 001 Device 005: ID 1fc9:012b NXP Semiconductors - -The ``librem5-devkit-flash-image`` script will download and flash the newest -available rootfs and U-Boot images. You may need to install some Python modules -before running the script. On Debian 9 (Stretch), Ubuntu 18.04 LTS (Bionic -Beaver) and later, this command should install these modules:: - - sudo apt-get -y install python3-jenkins python3-tqdm python3-yaml - -Now you can proceed with the flashing, using the script as shown below to -download temporary copies of U-Boot, kernel and the base system, before -flashing them on the board. Use the ``--skip-cleanup`` and ``--dir`` command -line options to keep the downloaded files after flashing. - -**This will erase everything on the board's eMMC:** - -.. code:: bash - - cd librem5-devkit-tools - export PATH=$PATH:/path-to-your-workspace/mfgtools-build/uuu/ - ./scripts/librem5-devkit-flash-image - -If you use the ``--dir`` option to download the files into a directory and -``--skip-cleanup`` to keep them after flashing, you can re-flash the eMMC using -the same files by entering the download directory and running ``uuu``. -For example, this is how you would download the files to the ``/tmp/devkit`` -directory and flash the eMMC, then re-flash it later as required. - -**This will erase everything on the board's eMMC:** - -.. code:: bash - - cd librem5-devkit-tools - export PATH=$PATH:/path-to-your-workspace/mfgtools-build/uuu/ - ./scripts/librem5-devkit-flash-image --dir /tmp/devkit --skip-cleanup - - # Re-flash the eMMC later: - cd /tmp/devkit - uuu flash_devkit.lst - -It can also be useful to use the ``--skip-flash`` if you only want to download -the files without flashing the eMMC. - -Reboot ------- - -Flip the boot switch back to eMMC position and press the reboot button. The -output of the ``lsusb`` command should show a multifunction gadget, like this:: - - Bus 003 Device 068: ID 1d6b:0104 Linux Foundation Multifunction Composite Gadget - -The serial console should appear at ``/dev/ttyACM0``, and a new newtwork interface will appear, confirming a successful reflash. - -As usual, don't hesitate to `get in touch`_ if you find yourself stuck. - -.. _imx8_devkit_lcd_display: - -HDMI ----- - -After flashing the latest image, connect to it using serial console in the same way as previously, and log in as ``root``. - -Copy the ``librem5-evk-hdmi.dtb`` file to the correct place:: - - root@pureos:~# cp /boot/dtbs/librem5-evk.dtb /boot/dtbs/librem5-evk.dtb.bak - root@pureos:~# cp /usr/lib/linux-image-`uname -r`/freescale/librem5-evk-hdmi.dtb /boot/dtbs/librem5-evk.dtb - -**Note:** The LCD panel is disabled when using this `dtb` file. - -Connect the HDMI monitor and reboot the system:: - - root@pureos:~# reboot - -After the system exits u-boot, a row of penguins will appear in the top-left -corner of the monitor. Afterwards, Phosh will occupy the display, showing a -login screen on a gray background. - Flash U-Boot ------------ diff --git a/Development_Environment/Boards/HowTo/Making_Cases.rst b/Development_Environment/Boards/HowTo/Making_Cases.rst new file mode 100644 index 0000000..7c78f89 --- /dev/null +++ b/Development_Environment/Boards/HowTo/Making_Cases.rst @@ -0,0 +1,9 @@ +Making Cases for the Development Board +====================================== + +Printable Case +-------------- + +.. _`on youmagine.com`: https://www.youmagine.com/designs/librem5-devkit-case + +A printable case model has been designed by MrPickleGG and is available `on youmagine.com`_. diff --git a/Development_Environment/Boards/HowTo/Updating_Software.rst b/Development_Environment/Boards/HowTo/Updating_Software.rst new file mode 100644 index 0000000..0ef530e --- /dev/null +++ b/Development_Environment/Boards/HowTo/Updating_Software.rst @@ -0,0 +1,26 @@ +Updating the Software +===================== + +After the image on the development board has been :ref:`updated from the original +factory image `, there are three main software +components that can be updated: the bootloader, the kernel and the distribution +packages. The installed packages can be updated in the normal way using +the``apt`` tool to update and upgrade them:: + + sudo apt update + sudo apt full-upgrade + +Currently, the bootloader can only be updated by reflashing the eMMC on the +board -- see :ref:`imx8_devkit_flashing_emmc` for instructions. This limitation +will be fixed when the following issue is resolved: + + * `Package u-boot and m4.bin as Deb packages `_ + +The kernel can be upgraded from a package file using ``dpkg``. In the future it +will also be possible to upgrade the kernel using ``apt`` when these issues are +resolved: + + * `Build a "proper" kernel package `_ + * `Upload built kernels `_ + +These instructions will be updated as developments occur. diff --git a/Development_Environment/Boards/HowTo/Wireless_Networking.rst b/Development_Environment/Boards/HowTo/Wireless_Networking.rst index 1d5af88..d59fdf4 100644 --- a/Development_Environment/Boards/HowTo/Wireless_Networking.rst +++ b/Development_Environment/Boards/HowTo/Wireless_Networking.rst @@ -1,6 +1,37 @@ Wireless Networking =================== +Configure Wi-Fi +--------------- + +Before attempting to use Wi-Fi, ensure that the Wi-Fi/Bluetooth switch is set +to the ON position on the board. + +For either method below you must first make sure the relevant module is loaded:: + + modprobe rsi_sdio + +Then you can configure the network interface. + +Configure with nmtui +~~~~~~~~~~~~~~~~~~~~ + +In a console, run ``nmtui`` to access the textual user interface to Network +Manager. Choose the option to activate a connection then choose your WiFi +network. The list may initially be empty because it sometimes takes 15 +seconds after loading the module to populate it with available networks. + +Configure with nmcli +~~~~~~~~~~~~~~~~~~~~ + +If you know which network you want to connect to, you can just use ``nmcli`` +directly:: + + nmcli device wifi rescan + nmcli device wifi list + nmcli device wifi connect SSID-Name password wireless-password + + If you have your Ethernet cable plugged in, you should automatically get a DHCP address on ``eth0``. Alternatively, you can bring up the wireless interface with a DHCP address using Network Manager by running the text user interface diff --git a/Development_Environment/Boards/imx8.rst b/Development_Environment/Boards/imx8.rst index 2923993..196de03 100644 --- a/Development_Environment/Boards/imx8.rst +++ b/Development_Environment/Boards/imx8.rst @@ -3,11 +3,7 @@ Librem 5 Development Kit ======================== -.. note:: This page is incomplete and is being regularly updated. - -If you experience problems with the development kit, you may find it useful to -consult the :ref:`imx8_devkit_known_issues` page and -:ref:`imx8_devkit_troubleshooting` guide. +.. note:: If you experience problems with the development kit, you may find it useful to consult the :ref:`imx8_devkit_known_issues` page and :ref:`imx8_devkit_troubleshooting` guide. .. Sections to add: connecting HDMI, mouse, keyboard @@ -15,8 +11,8 @@ consult the :ref:`imx8_devkit_known_issues` page and .. contents:: :local: -Dev kit package ---------------- +Development Kit Package +----------------------- The package contains: @@ -80,7 +76,7 @@ See :ref:`hardware_reference` for information about the specific parts used for the sockets, buttons and switches. Setting up the Board --------------------- +~~~~~~~~~~~~~~~~~~~~ In its original factory state, the board is lacking some essential features. We recommend that you consider :ref:`imx8_devkit_flashing_emmc` before using the @@ -91,97 +87,10 @@ and recognized by your workstation before reflashing the eMMC. It may also be useful to consult the :ref:`imx8_devkit_known_issues` page and :ref:`imx8_devkit_troubleshooting` guide if problems occur. -Updating the Software ---------------------- - -After the image on the development board has been :ref:`updated from the original -factory image `, there are three main software -components that can be updated: the bootloader, the kernel and the distribution -packages. The installed packages can be updated in the normal way using -the``apt`` tool to update and upgrade them:: - - sudo apt update - sudo apt full-upgrade - -Currently, the bootloader can only be updated by reflashing the eMMC on the -board -- see :ref:`imx8_devkit_flashing_emmc` for instructions. This limitation -will be fixed when the following issue is resolved: - - * `Package u-boot and m4.bin as Deb packages `_ - -The kernel can be upgraded from a package file using ``dpkg``. In the future it -will also be possible to upgrade the kernel using ``apt`` when these issues are -resolved: - - * `Build a "proper" kernel package `_ - * `Upload built kernels `_ - -These instructions will be updated as developments occur. - -USB Console -~~~~~~~~~~~ - -Connect the board to a workstation using the USB A to USB C cable provided. -The haptic motor will sound briefly and the board should appear shortly -after as a USB serial device to the workstation. - -:: - - Bus 003 Device 025: ID 0525:a4a7 Netchip Technology, Inc. Linux-USB Serial Gadget (CDC ACM mode) - -It will appear in the ``/dev/`` directory as a serial port, such as -``/dev/ttyACM0``, which you can use to access the board's serial console if -you have permission to read and write to that device:: - - picocom -b 115200 /dev/ttyACM0 - -This should produce the output like this:: - - Debian GNU/Linux buster/sid pureos-test ttyGS0 - - pureos-test login: - -It should be possible to log in using ``purism`` as the user name and -``123456`` as the password. - -**Note:** You may have trouble accessing the serial device if your user is not -a member of the ``dialout`` group on your workstation. For example, you may get -an error like this:: - - FATAL: cannot open /dev/ttyACM0: Permission denied - -In this case, you can either add your user to the ``dialout`` group or, as a -workaround, run ``picocom`` using the ``sudo`` command. - -.. _imx8_devkit_ethernet: - -Ethernet Connection -~~~~~~~~~~~~~~~~~~~ - -Connect the board to a network using the Ethernet socket and a suitable -cable. Connect the board to the provided power supply using the provided -cable. Two green LEDs will immediately light up between the SoM and the -battery holder. After a moment, the orange Ethernet light should start -blinking and the haptic motor will sound briefly. The board should be -accessible over the network via SSH. - -The image shipped with the boards will claim the IP address ``192.168.42.202`` with the ``/24`` netmask. Later images will try to obtain an IP address using DHCP -- see below for information. - -It should be possible to log in using ``purism`` as the user name and -``123456`` as the password:: - - $ ssh purism@192.168.42.202 - -If you update the image on the development board, it will try to obtain an IP address using DHCP. You will need to determine this address by accessing the DHCP client table for your local network. For example, if the board has been assigned the IP address ``192.168.1.110`` you can log in with the following command:: - - $ ssh purism@192.168.1.110 - -If you have difficulty determining the IP address of the board in the case where it uses DHCP, please contact your local network administrator for assistance. - .. _imx8_devkit_flashing_emmc: -Flashing eMMC -------------- +Flashing the eMMC +----------------- The main purpose of the image included on the eMMC is factory testing, therefore it's strongly recommended to flash an up-to-date one immediately. @@ -193,63 +102,16 @@ Install uuu The NXP mfgtool ``uuu`` is required to boot a board that has no bootloader or is otherwise "bricked". -.. There is apparently a Debian package for this. +You can obtain a package for Debian-based systems from `the Purism CI server`_ +or :ref:`build uuu from source `. -Build by Hand -^^^^^^^^^^^^^ +To install the package, run the ``dpkg`` tool in the following way:: -If you are not using ``uuu`` included in your favorite distribution, you can -build it manually instead. On a Debian-based system, you will need to install -some dependencies before building:: + sudo dpkg -i uuu_1.2.31-2~300.gbp6983a9_amd64.deb - sudo apt-get -y install libusb-1.0-0-dev libzip-dev libbz2-dev +The precise ``.deb`` package file name may differ from the one given above. -Then you can proceed with the build:: - - git clone https://source.puri.sm/Librem5/mfgtools - mkdir mfgtools-build - cd mfgtools-build - cmake ../mfgtools - make - -The ``uuu`` binary will find itself in ``mfgtools-build/uuu/uuu``. - -Udev Rules -^^^^^^^^^^ - -We recommend running ``uuu`` as an unprivileged user. On Debian-based systems, issue the following commands **as root** to make the development board accessible to your user over USB whenever it's connected: - -.. code:: bash - - cat < /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 - udevadm control -R - -Users of non-Debian systems may need to add the ``plugdev`` group if it does not already exist. This group grants permission to its members to access the devices it owns: - -.. code:: bash - - groupadd plugdev - -You will need to add your user to the ``plugdev`` group to access the development board: - -.. code:: bash - - sudo usermod -a -G plugdev $USER - -You can log in to the new group without having to log out by running this command: - -.. code:: bash - - newgrp plugdev - -Next time you plug in the USB cable, the development board's USB interface will be accessible by your user. +.. _`the Purism CI server`: https://arm01.puri.sm/job/debs/job/deb-mfgtools-buster-amd64/ Downloading Flashing Scripts ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -272,7 +134,7 @@ to a USB C or USB 3 port on the host that is capable of providing 900mA of current. The HID device should appear in the output of the ``lsusb`` command, like this:: - Bus 001 Device 005: ID 1fc9:012b NXP Semiconductors + Bus 001 Device 005: ID 1fc9:012b NXP Semiconductors The ``librem5-devkit-flash-image`` script will download and flash the newest available rootfs and U-Boot images. You may need to install some Python modules @@ -364,68 +226,10 @@ 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. -Configure Wi-Fi ---------------- - -Before attempting to use Wi-Fi, ensure that the Wi-Fi/Bluetooth switch is set -to the ON position on the board. - -For either method below you must first make sure the relevant module is loaded:: - - modprobe rsi_sdio - -Then you can configure the network interface. - -**Note:** The rsi_sdio module is blacklisted, so you will need to edit -/etc/modprobe.d/librem5-devkit.conf if you want Wi-Fi enabled at boot time. - -Configure with nmtui -~~~~~~~~~~~~~~~~~~~~ - -In a console, run ``nmtui`` to access the textual user interface to Network -Manager. Choose the option to activate a connection then choose your WiFi -network. The list may initially be empty because it sometimes takes 15 -seconds after loading the module to populate it with available networks. - -Configure with nmcli -~~~~~~~~~~~~~~~~~~~~ - -If you know which network you want to connect to, you can just use ``nmcli`` -directly:: - - nmcli device wifi rescan - nmcli device wifi list - nmcli device wifi connect SSID-Name password wireless-password - -.. _imx8_devkit_configure_bluetooth: - -Configure Bluetooth -------------------- - -Before attempting to use Bluetooth, ensure that the Wi-Fi/Bluetooth switch is -set to the ON position on the board. - -To enable Bluetooth you must first make sure the relevant module is loaded:: - - modprobe rsi_sdio - -It should then be possible to query the Bluetooth device:: - - hcitool dev - -This should produce output like this:: - - Devices: - hci0 88:DA:1A:9E:BA:95 - -The exact device address will be different for your board. See :ref:`devkit_howto_bluetooth` -for further ways to test and use the Bluetooth module. - -Printable Case --------------- - -.. _`on youmagine.com`: https://www.youmagine.com/designs/librem5-devkit-case +Next Steps +---------- -A printable case model has been designed by MrPickleGG and is available `on youmagine.com`_. +See the :ref:`devkit_howto` page for a collection of guides covering common +tasks and use cases for the board. .. include:: /links.txt -- GitLab From 7bf32074f74c5d498a0388d363e8db851b6ce49c Mon Sep 17 00:00:00 2001 From: David Boddie Date: Wed, 10 Apr 2019 18:09:42 +0200 Subject: [PATCH 03/13] Remove test run suggestion --- Development_Environment/Boards/imx8.rst | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/Development_Environment/Boards/imx8.rst b/Development_Environment/Boards/imx8.rst index 196de03..587bccd 100644 --- a/Development_Environment/Boards/imx8.rst +++ b/Development_Environment/Boards/imx8.rst @@ -80,9 +80,7 @@ Setting up the Board In its original factory state, the board is lacking some essential features. We recommend that you consider :ref:`imx8_devkit_flashing_emmc` before using the -board for development. However, you may want to consider performing an -:ref:`imx8_devkit_initial_test_run` to verify that the board can be powered on -and recognized by your workstation before reflashing the eMMC. +board for development. It may also be useful to consult the :ref:`imx8_devkit_known_issues` page and :ref:`imx8_devkit_troubleshooting` guide if problems occur. -- GitLab From 02d25a2de407ae773ed4dff5d75c2d32d7be421f Mon Sep 17 00:00:00 2001 From: David Boddie Date: Wed, 10 Apr 2019 18:13:30 +0200 Subject: [PATCH 04/13] Change uuu version and package advice --- Development_Environment/Boards/imx8.rst | 28 ++++--------------------- 1 file changed, 4 insertions(+), 24 deletions(-) diff --git a/Development_Environment/Boards/imx8.rst b/Development_Environment/Boards/imx8.rst index 587bccd..b3e766c 100644 --- a/Development_Environment/Boards/imx8.rst +++ b/Development_Environment/Boards/imx8.rst @@ -100,14 +100,14 @@ Install uuu The NXP mfgtool ``uuu`` is required to boot a board that has no bootloader or is otherwise "bricked". -You can obtain a package for Debian-based systems from `the Purism CI server`_ -or :ref:`build uuu from source `. +You can obtain a ``uuu`` package for Debian-based systems from `the Purism CI +server`_ or :ref:`build uuu from source `. To install the package, run the ``dpkg`` tool in the following way:: - sudo dpkg -i uuu_1.2.31-2~300.gbp6983a9_amd64.deb + sudo dpkg -i uuu_1.2.91_amd64.deb -The precise ``.deb`` package file name may differ from the one given above. +The precise ``.deb`` package file name may differ from the one given above. Version 1.2.91 or later is recommended. .. _`the Purism CI server`: https://arm01.puri.sm/job/debs/job/deb-mfgtools-buster-amd64/ @@ -189,26 +189,6 @@ As usual, don't hesitate to `get in touch`_ if you find yourself stuck. .. _imx8_devkit_lcd_display: -HDMI -~~~~ - -After flashing the latest image, connect to it using serial console in the same way as previously, and log in as ``root``. - -Copy the ``librem5-evk-hdmi.dtb`` file to the correct place:: - - root@pureos:~# cp /boot/dtbs/librem5-evk.dtb /boot/dtbs/librem5-evk.dtb.bak - root@pureos:~# cp /usr/lib/linux-image-`uname -r`/freescale/librem5-evk-hdmi.dtb /boot/dtbs/librem5-evk.dtb - -**Note:** The LCD panel is disabled when using this `dtb` file. - -Connect the HDMI monitor and reboot the system:: - - root@pureos:~# reboot - -After the system exits u-boot, a row of penguins will appear in the top-left -corner of the monitor. Afterwards, Phosh will occupy the display, showing a -login screen on a gray background. - Power on/off ------------ -- GitLab From f55671bb1c807cb2d8b5678e24d8427810e905ce Mon Sep 17 00:00:00 2001 From: David Boddie Date: Wed, 10 Apr 2019 18:14:17 +0200 Subject: [PATCH 05/13] Move HDMI instructions into a How To guide --- Development_Environment/Boards/HowTo.rst | 1 + Development_Environment/Boards/HowTo/HDMI.rst | 20 +++++++++++++++++++ 2 files changed, 21 insertions(+) create mode 100644 Development_Environment/Boards/HowTo/HDMI.rst diff --git a/Development_Environment/Boards/HowTo.rst b/Development_Environment/Boards/HowTo.rst index e6e582a..d7e94ce 100644 --- a/Development_Environment/Boards/HowTo.rst +++ b/Development_Environment/Boards/HowTo.rst @@ -14,6 +14,7 @@ how to perform routine tasks. HowTo/Data_Connections HowTo/Ethernet_over_USB HowTo/Flashing_eMMC + HowTo/HDMI HowTo/Initial_Test_Run HowTo/Install_Plasma_Mobile HowTo/Inertial_Module diff --git a/Development_Environment/Boards/HowTo/HDMI.rst b/Development_Environment/Boards/HowTo/HDMI.rst new file mode 100644 index 0000000..e079133 --- /dev/null +++ b/Development_Environment/Boards/HowTo/HDMI.rst @@ -0,0 +1,20 @@ +HDMI +==== + +After flashing the latest image, connect to it using serial console in the same way as previously, and log in as ``root``. + +Copy the ``librem5-evk-hdmi.dtb`` file to the correct place:: + + root@pureos:~# cp /boot/dtbs/librem5-evk.dtb /boot/dtbs/librem5-evk.dtb.bak + root@pureos:~# cp /usr/lib/linux-image-`uname -r`/freescale/librem5-evk-hdmi.dtb /boot/dtbs/librem5-evk.dtb + +**Note:** The LCD panel is disabled when using this `dtb` file. + +Connect the HDMI monitor and reboot the system:: + + root@pureos:~# reboot + +After the system exits u-boot, a row of penguins will appear in the top-left +corner of the monitor. Afterwards, Phosh will occupy the display, showing a +login screen on a gray background. + -- GitLab From 3cb2acfff7bc1aaa3c38e32ba9fc310da770e498 Mon Sep 17 00:00:00 2001 From: David Boddie Date: Thu, 11 Apr 2019 20:27:44 +0200 Subject: [PATCH 06/13] Fix wording caused by section reorganization --- .../Boards/HowTo/Bluetooth_Connections.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/Development_Environment/Boards/HowTo/Bluetooth_Connections.rst b/Development_Environment/Boards/HowTo/Bluetooth_Connections.rst index 9f0ceda..f4f3781 100644 --- a/Development_Environment/Boards/HowTo/Bluetooth_Connections.rst +++ b/Development_Environment/Boards/HowTo/Bluetooth_Connections.rst @@ -30,8 +30,9 @@ The exact device address will be different for your board. Finding Another Device ---------------------- -Once you have for the development board, you can check that it can be paired -with other devices and used for data transfer with the following instructions. +Once you have configured Bluetooth for the development board, you can check that +it can be paired with other devices and used for data transfer with the +following instructions. Ensure that the Wi-Fi/Bluetooth switch is set to the ON position on the board. -- GitLab From 88ac0b30a0751e44bfa54e7420858b77379d2686 Mon Sep 17 00:00:00 2001 From: David Boddie Date: Thu, 11 Apr 2019 23:16:46 +0200 Subject: [PATCH 07/13] Make two different USB console sections using similar text --- Development_Environment/Boards/HowTo.rst | 2 +- ...Test_Run.rst => Testing_Factory_Image.rst} | 52 ++++--------------- .../Boards/HowTo/USB_Access.rst | 12 ++++- .../Boards/HowTo/common/USB_Console.txt | 36 +++++++++++++ _extensions/include_par.py | 29 ++++++++++- 5 files changed, 86 insertions(+), 45 deletions(-) rename Development_Environment/Boards/HowTo/{Initial_Test_Run.rst => Testing_Factory_Image.rst} (58%) create mode 100644 Development_Environment/Boards/HowTo/common/USB_Console.txt diff --git a/Development_Environment/Boards/HowTo.rst b/Development_Environment/Boards/HowTo.rst index d7e94ce..6029226 100644 --- a/Development_Environment/Boards/HowTo.rst +++ b/Development_Environment/Boards/HowTo.rst @@ -15,7 +15,6 @@ how to perform routine tasks. HowTo/Ethernet_over_USB HowTo/Flashing_eMMC HowTo/HDMI - HowTo/Initial_Test_Run HowTo/Install_Plasma_Mobile HowTo/Inertial_Module HowTo/Location_Services @@ -24,6 +23,7 @@ how to perform routine tasks. HowTo/Rebuilding_the_Kernel HowTo/Simple_Input_Output HowTo/SSH_Access + HowTo/Testing_Factory_Image HowTo/Touchscreen HowTo/Updating_Software HowTo/USB_Access diff --git a/Development_Environment/Boards/HowTo/Initial_Test_Run.rst b/Development_Environment/Boards/HowTo/Testing_Factory_Image.rst similarity index 58% rename from Development_Environment/Boards/HowTo/Initial_Test_Run.rst rename to Development_Environment/Boards/HowTo/Testing_Factory_Image.rst index 49c501a..2ee6e1c 100644 --- a/Development_Environment/Boards/HowTo/Initial_Test_Run.rst +++ b/Development_Environment/Boards/HowTo/Testing_Factory_Image.rst @@ -1,11 +1,11 @@ -.. _imx8_devkit_initial_test_run: +.. _imx8_devkit_test_run: -Initial Test Run ----------------- +Testing the Board with the Factory Image +======================================== -There are two simple ways to verify that the development board is -functioning. It is useful to try both of these to ensure that you can access -the board via serial and Ethernet connections. +.. note:: This page is retained for reference purposes. It is more useful to follow the :ref:`imx8_devkit_flashing_emmc` instructions rather than use the software originally supplied with the development board. + +There are two simple ways to verify that the development board, **as initially shipped**, is functioning. It is useful to try both of these to ensure that you can access the board via serial and Ethernet connections. If neither of these procedures work for you, please `get in touch`_. @@ -24,47 +24,17 @@ labelled photo below. Button side, right to left: smart card socket, volume down button, volume up button, power button, micro SIM card socket. -.. _imx8_devkit_usb_console: - -USB Console -~~~~~~~~~~~ - -Connect the board to a workstation using the USB A to USB C cable provided. -The haptic motor will sound briefly and the board should appear shortly -after as a USB serial device to the workstation. - -:: - - Bus 003 Device 025: ID 0525:a4a7 Netchip Technology, Inc. Linux-USB Serial Gadget (CDC ACM mode) - -It will appear in the ``/dev/`` directory as a serial port, such as -``/dev/ttyACM0``, which you can use to access the board's serial console if -you have permission to read and write to that device:: - - picocom -b 115200 /dev/ttyACM0 - -This should produce the output like this:: - - Debian GNU/Linux buster/sid pureos-test ttyGS0 - - pureos-test login: - -It should be possible to log in using ``purism`` as the user name and ``123456`` -as the password. - -**Note:** You may have trouble accessing the serial device if your user is not -a member of the ``dialout`` group on your workstation. For example, you may get -an error like this:: +.. USB Console +.. ----------- - FATAL: cannot open /dev/ttyACM0: Permission denied +.. |lsusb-output| replace:: "Bus 003 Device 025: ID 0525:a4a7 Netchip Technology, Inc. Linux-USB Serial Gadget (CDC ACM mode)" -In this case, you can either add your user to the ``dialout`` group or, as a -workaround, run ``picocom`` using the ``sudo`` command. +.. include:: common/USB_Console.txt .. _imx8_devkit_ethernet: Ethernet Connection -~~~~~~~~~~~~~~~~~~~ +------------------- Connect the board to a network using the Ethernet socket and a suitable cable. Connect the board to the provided power supply using the provided diff --git a/Development_Environment/Boards/HowTo/USB_Access.rst b/Development_Environment/Boards/HowTo/USB_Access.rst index 977f8a8..3284725 100644 --- a/Development_Environment/Boards/HowTo/USB_Access.rst +++ b/Development_Environment/Boards/HowTo/USB_Access.rst @@ -4,8 +4,16 @@ USB Access In the default configuration, as shipped, USB in is peripheral mode and a "wall wart" AC adaptor can be used for power. In this mode, it is also possible to connect the development board to a workstation's USB **3.0+** port -(where VBUS can supply up to 900mA) and access a serial console, as described in -:ref:`imx8_devkit_initial_test_run`. +(where VBUS can supply up to 900mA) and access a serial console. + +In the latest software images, the development board acts as a multifunction +composite gadget which provides both serial and networking support. + +.. _imx8_devkit_usb_console: + +.. |lsusb-output| replace:: "Bus 001 Device 008: ID 1d6b:0104 Linux Foundation Multifunction Composite Gadget" + +.. include:: common/USB_Console.txt Alternate Configuration - USB C Host ------------------------------------ diff --git a/Development_Environment/Boards/HowTo/common/USB_Console.txt b/Development_Environment/Boards/HowTo/common/USB_Console.txt new file mode 100644 index 0000000..86d9d00 --- /dev/null +++ b/Development_Environment/Boards/HowTo/common/USB_Console.txt @@ -0,0 +1,36 @@ +USB Console +----------- + +Connect the board to a workstation using the USB A to USB C cable provided. +The haptic motor will sound briefly and the board should appear shortly +after as a USB serial device to the workstation: + +.. code-par:: + + |lsusb-output| + +The bus and device numbers may differ from those shown. + +The device will also appear in the ``/dev/`` directory as a serial port, such as +``/dev/ttyACM0``, which you can use to access the board's serial console if +you have permission to read and write to that device:: + + picocom -b 115200 /dev/ttyACM0 + +This should produce the output like this:: + + Debian GNU/Linux buster/sid pureos-test ttyGS0 + + pureos-test login: + +It should be possible to log in using ``purism`` as the user name and ``123456`` +as the password. + +**Note:** You may have trouble accessing the serial device if your user is not +a member of the ``dialout`` group on your workstation. For example, you may get +an error like this:: + + FATAL: cannot open /dev/ttyACM0: Permission denied + +In this case, you can either add your user to the ``dialout`` group or, as a +workaround, run ``picocom`` using the ``sudo`` command. diff --git a/_extensions/include_par.py b/_extensions/include_par.py index 1571d83..4008a93 100644 --- a/_extensions/include_par.py +++ b/_extensions/include_par.py @@ -101,7 +101,7 @@ class CodeParam(CodeBlock): # For each match, find the substitution(s) to use, starting from # the definition and reading all the arguments as plain text. node = document.substitution_defs[match].next_node() - subs = str(node.rawsource).split() + subs = self.parse_args(node.rawsource) # Substitute new text for the placeholders on each line. # If there are multiple substitutions for a placeholder then @@ -132,6 +132,33 @@ class CodeParam(CodeBlock): return CodeBlock.run(self) + def parse_args(self, text): + + # Parse the text, treating spaces as argument separators unless + # the spaces are part of a quoted string. + ### TODO: Add support for escaped quote characters if required. + in_quote = False + args = [""] + + for c in text: + if in_quote: + if c == '"': + args.append('') + in_quote = False + else: + args[-1] += c + elif c == '"': + in_quote = True + elif c == ' ': + args.append('') + else: + args[-1] += c + + if args[-1] == '': + args.pop() + + return args + def setup(app): -- GitLab From e3601668e19a01472feec84cbb8df37c184cb83b Mon Sep 17 00:00:00 2001 From: David Boddie Date: Thu, 11 Apr 2019 23:17:31 +0200 Subject: [PATCH 08/13] Rename Reboot section, remove Power on/off section --- .../Boards/HowTo/Ethernet_over_USB.rst | 2 ++ Development_Environment/Boards/imx8.rst | 21 +++---------------- 2 files changed, 5 insertions(+), 18 deletions(-) diff --git a/Development_Environment/Boards/HowTo/Ethernet_over_USB.rst b/Development_Environment/Boards/HowTo/Ethernet_over_USB.rst index 98a159b..9644433 100644 --- a/Development_Environment/Boards/HowTo/Ethernet_over_USB.rst +++ b/Development_Environment/Boards/HowTo/Ethernet_over_USB.rst @@ -1,3 +1,5 @@ +.. _devkit_ethernet_usb: + Ethernet over USB ================= diff --git a/Development_Environment/Boards/imx8.rst b/Development_Environment/Boards/imx8.rst index b3e766c..f3d75ac 100644 --- a/Development_Environment/Boards/imx8.rst +++ b/Development_Environment/Boards/imx8.rst @@ -175,35 +175,20 @@ directory and flash the eMMC, then re-flash it later as required. It can also be useful to use the ``--skip-flash`` if you only want to download the files without flashing the eMMC. -Reboot -~~~~~~ +Booting for the First Time +~~~~~~~~~~~~~~~~~~~~~~~~~~ Flip the boot switch back to eMMC position and press the reboot button. The output of the ``lsusb`` command should show a multifunction gadget, like this:: Bus 003 Device 068: ID 1d6b:0104 Linux Foundation Multifunction Composite Gadget -The serial console should appear at ``/dev/ttyACM0``, and a new newtwork interface will appear, confirming a successful reflash. +The serial console should appear at ``/dev/ttyACM0``. The board should also be available as a USB network device -- see the :ref:`devkit_ethernet_usb` guide for setup instructions. As usual, don't hesitate to `get in touch`_ if you find yourself stuck. .. _imx8_devkit_lcd_display: -Power on/off ------------- - -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. - -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. - Next Steps ---------- -- GitLab From f1b67f6697b1cda741377f63147787c0f9d789da Mon Sep 17 00:00:00 2001 From: David Boddie Date: Tue, 16 Apr 2019 23:15:35 +0200 Subject: [PATCH 09/13] Reword initial test run text to resolve issue #89 --- .../Boards/HowTo/Testing_Factory_Image.rst | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/Development_Environment/Boards/HowTo/Testing_Factory_Image.rst b/Development_Environment/Boards/HowTo/Testing_Factory_Image.rst index 2ee6e1c..1fa194d 100644 --- a/Development_Environment/Boards/HowTo/Testing_Factory_Image.rst +++ b/Development_Environment/Boards/HowTo/Testing_Factory_Image.rst @@ -5,12 +5,10 @@ Testing the Board with the Factory Image .. note:: This page is retained for reference purposes. It is more useful to follow the :ref:`imx8_devkit_flashing_emmc` instructions rather than use the software originally supplied with the development board. -There are two simple ways to verify that the development board, **as initially shipped**, is functioning. It is useful to try both of these to ensure that you can access the board via serial and Ethernet connections. - +You may find it useful to verify that the development board, **as initially shipped**, is functioning. The two methods described below can help to check that the serial and Ethernet connections to the board are working correctly. If neither of these procedures work for you, please `get in touch`_. -First of all, make sure that the boot mode switch is set to eMMC -- see the -labelled photo below. +**Before you begin:** make sure that the Boot Mode switch is set to eMMC -- see the labelled photo below. .. figure:: ../images/dev-board-sockets-buttons-switches.png :scale: 50% -- GitLab From 8a98bd642459573301822ded567e163f9b213ffd Mon Sep 17 00:00:00 2001 From: David Boddie Date: Mon, 13 May 2019 19:22:45 +0200 Subject: [PATCH 10/13] Add uuu build troubleshooting advice --- Development_Environment/Boards/HowTo/Building_uuu.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/Development_Environment/Boards/HowTo/Building_uuu.rst b/Development_Environment/Boards/HowTo/Building_uuu.rst index 9ee9369..a1ffdb8 100644 --- a/Development_Environment/Boards/HowTo/Building_uuu.rst +++ b/Development_Environment/Boards/HowTo/Building_uuu.rst @@ -17,7 +17,9 @@ Then you can proceed with the build:: cmake ../mfgtools make -The ``uuu`` binary will find itself in ``mfgtools-build/uuu/uuu``. +If the build is successful, the ``uuu`` binary can be found in ``mfgtools-build/uuu/uuu``. + +If you have problems building from the ``mfgtools-build`` directory, ensure that the ``mfgtools`` directory does not contain any files left over from a previous build. Udev Rules ---------- -- GitLab From 0d9c366aa1a9549d22c7858b65301d5f3573b62f Mon Sep 17 00:00:00 2001 From: David Boddie Date: Mon, 27 May 2019 23:20:24 +0200 Subject: [PATCH 11/13] Add serial console login details --- Development_Environment/Boards/imx8.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/Development_Environment/Boards/imx8.rst b/Development_Environment/Boards/imx8.rst index f3d75ac..0012d60 100644 --- a/Development_Environment/Boards/imx8.rst +++ b/Development_Environment/Boards/imx8.rst @@ -183,7 +183,9 @@ output of the ``lsusb`` command should show a multifunction gadget, like this:: Bus 003 Device 068: ID 1d6b:0104 Linux Foundation Multifunction Composite Gadget -The serial console should appear at ``/dev/ttyACM0``. The board should also be available as a USB network device -- see the :ref:`devkit_ethernet_usb` guide for setup instructions. +The serial console should appear at ``/dev/ttyACM0``. You should be able to log in as the user ``purism`` with the password ``123456``. + +The board should also be available as a USB network device -- see the :ref:`devkit_ethernet_usb` guide for setup instructions. As usual, don't hesitate to `get in touch`_ if you find yourself stuck. -- GitLab From 18a1d0bb866c270dcb748c4f525842187795a35a Mon Sep 17 00:00:00 2001 From: David Boddie Date: Thu, 30 May 2019 22:48:29 +0200 Subject: [PATCH 12/13] Update the HDMI section to use flash-kernel --- Development_Environment/Boards/HowTo/HDMI.rst | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/Development_Environment/Boards/HowTo/HDMI.rst b/Development_Environment/Boards/HowTo/HDMI.rst index e079133..d61f0c7 100644 --- a/Development_Environment/Boards/HowTo/HDMI.rst +++ b/Development_Environment/Boards/HowTo/HDMI.rst @@ -5,16 +5,18 @@ After flashing the latest image, connect to it using serial console in the same Copy the ``librem5-evk-hdmi.dtb`` file to the correct place:: - root@pureos:~# cp /boot/dtbs/librem5-evk.dtb /boot/dtbs/librem5-evk.dtb.bak - root@pureos:~# cp /usr/lib/linux-image-`uname -r`/freescale/librem5-evk-hdmi.dtb /boot/dtbs/librem5-evk.dtb + root@pureos:~# cp /usr/lib/linux-image-`uname -r`/freescale/librem5-evk-hdmi.dtb /etc/flash-kernel/dtbs/librem5-evk.dtb -**Note:** The LCD panel is disabled when using this `dtb` file. +Run the ``flash-kernel`` tool to install the new ``dtb`` file:: + + root@pureos:~# flash-kernel + +**Note:** The LCD panel is disabled when using this ``dtb`` file. Connect the HDMI monitor and reboot the system:: root@pureos:~# reboot -After the system exits u-boot, a row of penguins will appear in the top-left +After the system exits U-Boot, a row of penguins will appear in the top-left corner of the monitor. Afterwards, Phosh will occupy the display, showing a login screen on a gray background. - -- GitLab From 6691562e0c01693f67435df4c99f1b1ded40a407 Mon Sep 17 00:00:00 2001 From: David Boddie Date: Thu, 30 May 2019 22:48:41 +0200 Subject: [PATCH 13/13] Remove comments --- Development_Environment/Boards/imx8.rst | 3 --- 1 file changed, 3 deletions(-) diff --git a/Development_Environment/Boards/imx8.rst b/Development_Environment/Boards/imx8.rst index 0012d60..68c608c 100644 --- a/Development_Environment/Boards/imx8.rst +++ b/Development_Environment/Boards/imx8.rst @@ -5,9 +5,6 @@ Librem 5 Development Kit .. note:: If you experience problems with the development kit, you may find it useful to consult the :ref:`imx8_devkit_known_issues` page and :ref:`imx8_devkit_troubleshooting` guide. -.. Sections to add: - connecting HDMI, mouse, keyboard - .. contents:: :local: -- GitLab