diff --git a/Development_Environment/Boards/HowTo.rst b/Development_Environment/Boards/HowTo.rst index 6ccd79e543c1ea91b6646f26f2e38e74b524bca4..6029226e5039fb23173ddfe889fdfded31b925a6 100644 --- a/Development_Environment/Boards/HowTo.rst +++ b/Development_Environment/Boards/HowTo.rst @@ -10,15 +10,21 @@ how to perform routine tasks. :maxdepth: 1 HowTo/Bluetooth_Connections + HowTo/Building_uuu HowTo/Data_Connections HowTo/Ethernet_over_USB + HowTo/Flashing_eMMC + HowTo/HDMI 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/Testing_Factory_Image 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 d10a8fc4582d7d0c7c6bad55a65191d6223af301..f4f378192e7bdcbe845e497569ddbc03379bb0ed 100644 --- a/Development_Environment/Boards/HowTo/Bluetooth_Connections.rst +++ b/Development_Environment/Boards/HowTo/Bluetooth_Connections.rst @@ -3,16 +3,37 @@ 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 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. From a workstation, log in to the development board using either ``ssh`` or diff --git a/Development_Environment/Boards/HowTo/Building_uuu.rst b/Development_Environment/Boards/HowTo/Building_uuu.rst new file mode 100644 index 0000000000000000000000000000000000000000..a1ffdb8bcaa57a45828071f96e40337f605e6519 --- /dev/null +++ b/Development_Environment/Boards/HowTo/Building_uuu.rst @@ -0,0 +1,59 @@ +.. _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 + +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 +---------- + +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/Ethernet_over_USB.rst b/Development_Environment/Boards/HowTo/Ethernet_over_USB.rst index 98a159bf9b643ab95c3539bafa5a9309d4ca6bd3..9644433caf4b9bfb6f6c8a5e7dda0977a4dedbbe 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/HowTo/Flashing_eMMC.rst b/Development_Environment/Boards/HowTo/Flashing_eMMC.rst new file mode 100644 index 0000000000000000000000000000000000000000..e3831d5256bc64fa190882fcb3f77a2a09a66719 --- /dev/null +++ b/Development_Environment/Boards/HowTo/Flashing_eMMC.rst @@ -0,0 +1,23 @@ +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/HDMI.rst b/Development_Environment/Boards/HowTo/HDMI.rst new file mode 100644 index 0000000000000000000000000000000000000000..d61f0c734ea5bc8ad28598985aa941ff04cc48fa --- /dev/null +++ b/Development_Environment/Boards/HowTo/HDMI.rst @@ -0,0 +1,22 @@ +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 /usr/lib/linux-image-`uname -r`/freescale/librem5-evk-hdmi.dtb /etc/flash-kernel/dtbs/librem5-evk.dtb + +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 +corner of the monitor. Afterwards, Phosh will occupy the display, showing a +login screen on a gray background. diff --git a/Development_Environment/Boards/HowTo/Making_Cases.rst b/Development_Environment/Boards/HowTo/Making_Cases.rst new file mode 100644 index 0000000000000000000000000000000000000000..7c78f89dbf67162f83922068dff2b51f610cdc57 --- /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/Testing_Factory_Image.rst b/Development_Environment/Boards/HowTo/Testing_Factory_Image.rst new file mode 100644 index 0000000000000000000000000000000000000000..1fa194d366ab9301e14db0b37a5f58504fc72000 --- /dev/null +++ b/Development_Environment/Boards/HowTo/Testing_Factory_Image.rst @@ -0,0 +1,57 @@ +.. _imx8_devkit_test_run: + +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. + +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`_. + +**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% + :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. + +.. USB Console +.. ----------- + +.. |lsusb-output| replace:: "Bus 003 Device 025: ID 0525:a4a7 Netchip Technology, Inc. Linux-USB Serial Gadget (CDC ACM mode)" + +.. 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 +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 2d5660b904f74a2ac64063e7d10d560128a173ac..32847255f67720eac6f27b6501ad05cc3ee5bd23 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:`devkit_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/Updating_Software.rst b/Development_Environment/Boards/HowTo/Updating_Software.rst new file mode 100644 index 0000000000000000000000000000000000000000..0ef530e2447082cb6453beec842028bcb42e67a4 --- /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 1d5af8820812ac55724c73083beda452dc88d191..d59fdf4aede5cb6a87bb66fc60dc2b04f88781ab 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/HowTo/common/USB_Console.txt b/Development_Environment/Boards/HowTo/common/USB_Console.txt new file mode 100644 index 0000000000000000000000000000000000000000..86d9d0079d98e779a1f09f219b24392df2ae8fc0 --- /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/Development_Environment/Boards/imx8.rst b/Development_Environment/Boards/imx8.rst index 4ada2c9f0dfeff4dc16953eb0f3acc997ee7e9af..68c608cc1f9b3ca010a5359dd23d429731fe9c97 100644 --- a/Development_Environment/Boards/imx8.rst +++ b/Development_Environment/Boards/imx8.rst @@ -3,20 +3,13 @@ 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. - -.. Sections to add: - connecting HDMI, mouse, keyboard +.. 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. .. contents:: :local: -Dev kit package ---------------- +Development Kit Package +----------------------- The package contains: @@ -47,8 +40,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,113 +72,20 @@ 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: - -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 `_ above. - -.. _`get in touch`: https://developer.puri.sm/Librem5/Contact.html - -.. _imx8_devkit_usb_console: - -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:: - - 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:: +Setting up the Board +~~~~~~~~~~~~~~~~~~~~ - $ ssh purism@192.168.1.110 +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. -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. +It may also be useful to consult the :ref:`imx8_devkit_known_issues` page and +:ref:`imx8_devkit_troubleshooting` guide if problems occur. .. _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. @@ -198,63 +97,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. - -Build by Hand -^^^^^^^^^^^^^ - -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 +You can obtain a ``uuu`` package for Debian-based systems from `the Purism CI +server`_ or :ref:`build uuu from source `. -Then you can proceed with the build:: +To install the package, run the ``dpkg`` tool in the following way:: - 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 dpkg -i uuu_1.2.91_amd64.deb - sudo usermod -a -G plugdev $USER +The precise ``.deb`` package file name may differ from the one given above. Version 1.2.91 or later is recommended. -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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -277,7 +129,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 @@ -320,140 +172,26 @@ 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``. 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. .. _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 ------------- - -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. - -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 ---------------- - -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 diff --git a/_extensions/include_par.py b/_extensions/include_par.py index 1571d83c608ed926d03b08511943b631813bef2d..4008a93b7a43efcfde6738f963bae8284fd35a6d 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): diff --git a/links.txt b/links.txt index dce66213894c5d4154e119cbc1804223f6444504..bdb548cbf0a39e5ad8c8bc0f6e0636048cefb680 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