Merge branch 'add-phone-development-setup-info' into 'master'

Add phone development setup info

See merge request Librem5/developer.puri.sm!362

Development_Environment/Boards/HowTo/Testing_Factory_Image.rst

@@ -25,7 +25,10 @@ If neither of these procedures work for you, please `get in touch`_.
 .. USB Console
 .. -----------
 
+.. |device| replace:: board
+.. |power-up| replace:: The haptic motor will sound briefly and the board should appear shortly after as a USB serial device to the workstation.
 .. |lsusb-output| replace:: "Bus 003 Device 025: ID 0525:a4a7 Netchip Technology, Inc. Linux-USB Serial Gadget (CDC ACM mode)"
+.. |login| replace:: "pureos-test login:"
 
 .. include:: common/USB_Console.txt
 

Development_Environment/Boards/HowTo/USB_Access.rst

+.. |device| replace:: board
+.. |power-up| replace:: The haptic motor will sound briefly and the board should appear shortly after as a USB serial device to the workstation.
 .. |lsusb-output| replace:: "Bus 001 Device 008: ID 1d6b:0104 Linux Foundation Multifunction Composite Gadget"
+.. |login| replace:: "pureos-test login:"
 
 USB Access
 ==========

Development_Environment/Boards/HowTo/common/USB_Console.txt

-USB Console
------------
+USB Serial 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:
+Connect the |device| to a workstation using a USB-A to USB-C cable.
+|power-up|
+
+Check to see that the following appears in the output of the ``lsusb`` command:
 
 .. code-par::
 
@@ -12,18 +13,20 @@ after as a USB serial device to the workstation:
 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
+``/dev/ttyACM0``, which you can use to access the |device|'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::
+This should produce the output like this:
+
+.. code-par::
+
+   |login|
 
-   Debian GNU/Linux buster/sid pureos-test ttyGS0
-   
-   pureos-test login:
+You may need to press Return to see the prompt.
 
-It should be possible to log in using ``purism`` as the user name and ``123456``
+You should be able 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

Development_Environment/Phone.rst

@@ -3,23 +3,22 @@
 Setting up the Phone
 ====================
 
-.. note:: This section is subject to updates and revisions.
+.. note:: This guide is subject to updates and revisions.
 
-This section describes the steps needed to set up the Librem 5 phone for application development. For troubleshooting advice, see the :ref:`librem_5_troubleshooting` section.
+This guide describes the steps needed to set up the Librem 5 phone for application development.
 
 .. toctree::
    :maxdepth: 1
-   :hidden:
 
-   Phone/Troubleshooting.rst
+   Phone/Connecting_via_USB
+   Phone/Development_Tools
+   Phone/Troubleshooting
 
-Software
+Overview
 --------
 
-A package is available that is designed to help set up a development environment on the phone itself. This can be installed from a terminal, either using the built-in **Terminal** application or via an ``ssh`` connection into the phone, with the following command:
+We begin by connecting the phone to a workstation and setting up a network connection before installing tools that assist with software development on the phone itself.
 
-.. code:: bash
+Once development tools are installed, you can develop software on the phone itself. Alternatively, you can use the network connection to conveniently copy software built on a workstation to the phone for testing and installation.
 
-   apt install librem5-dev-tools
-
-Installing this package should cause additional packages to be installed, containing tools and resources for application development.
+For troubleshooting advice, see the :ref:`librem_5_troubleshooting` section.

Development_Environment/Phone/Connecting_via_USB.rst

+.. _librem_5_connecting_usb:
+
+Connecting via USB
+==================
+
+A convenient way to connect the phone to a workstation is via a USB-A to USB-C cable. This guide describes how to configure the phone and a connected workstation to allow serial and network communication between the two devices.
+
+.. contents::
+   :local:
+
+This guide assumes that the phone is switched on and running the system software. Ensure that the phone is already in this state before trying to connect to it.
+
+Notes about Cables
+------------------
+
+Some USB-A to USB-C cables may need to be plugged into the phone with a particular orientation. If the instructions above do not appear to work, try flipping the USB-C end of the cable over and replugging it into the phone.
+
+.. USB Serial Console
+.. ------------------
+
+.. |device| replace:: phone
+.. |power-up| replace:: The phone should appear shortly after as a USB serial device to the workstation.
+.. |lsusb-output| replace:: "Bus 001 Device 010: ID 1d6b:0104 Linux Foundation Multifunction Composite Gadget"
+.. |login| replace:: "pureos login:"
+
+.. _librem_5_usb_serial:
+
+.. include:: ../Boards/HowTo/common/USB_Console.txt
+
+Enabling Networking
+-------------------
+
+In this section, we briefly describe how to get a simple IPv4 interface set up and enable network routing from the phone via the workstation to the Internet. The procedure is similar to that described in the :ref:`devkit_ethernet_usb` guide for the Librem 5 development board, which provides much more detail.
+
+Workstation
+~~~~~~~~~~~
+
+On your workstation, check the output of the ``ip link`` command to see which network interfaces are available:
+
+.. code:: bash
+
+   ip link
+
+Connect the workstation and the phone using the USB cable, then run ``ip link`` again to see which new ones have appeared. You should see a new entry like this one in the output from the command::
+
+   7: enp0s18f2u1: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UNKNOWN mode DEFAULT group default qlen 1000
+       link/ether 2a:71:82:e2:63:84 brd ff:ff:ff:ff:ff:ff
+
+The interface on your workstation may be different to this.
+
+Obtain the ``librem5-usbnet`` script from the `librem5-devkit-tools`_ repository. It can be found in the ``scripts`` directory.
+
+This script accepts an IPv4 address and the new network interface. Make sure that it is executable and on the run path, then run it in the following way, substituting the new interface on your workstation for the one given:
+
+.. code:: bash
+
+   sudo start-net.sh 192.168.42.1 enp0s18f2u1
+
+You should be able to run ``ip addr`` and ``ip route`` to see that the interface has an address and route associated with it.
+
+Phone
+~~~~~
+
+Use the USB serial console :ref:`described above <librem_5_usb_serial>` to log in to the phone.
+
+Obtain the ``usbnet`` script from the `librem5-devkit-tools`_ repository. It can be found in the ``test_scripts`` directory.
+
+Running ``sudo usbnet`` should set up an IPv4 address for the phone and a default route for network traffic that goes via the workstation.
+
+Next Steps
+----------
+
+Once USB networking is enabled, it becomes possible to access the network via the workstation and install development tools. This is also possible via a cellular network or Wi-Fi.
+
+.. include:: /links.txt

Development_Environment/Phone/Development_Tools.rst

+.. _phone_setup_development_tools:
+
+Development Tools
+=================
+
+A package is available that is designed to help set up a development environment on the phone itself. This can be installed from a terminal, either using the built-in **Terminal** application or via a serial connection into the phone, with the following command:
+
+.. code:: bash
+
+   sudo apt install librem5-dev-tools
+
+Installing this package should cause additional packages to be installed, containing tools and resources for application development.
+
+This should also enable an SSH server, allowing you to log in to the phone and develop software natively using an SSH session. The availability of an SSH server also makes it convenient to copy software built on a workstation to the phone for testing and installation.

Development_Environment/Phone/Troubleshooting.rst

@@ -3,7 +3,7 @@
 Troubleshooting
 ===============
 
-This section provides information for developers who need to investigate a problem with a Librem 5 phone and want to diagnose it. It contains some useful starting points for investigation and instructions for performing tasks that may be needed to help with testing.
+The following sections provide information for developers who need to investigate and diagnose problems with their Librem 5 phones. It contains some useful starting points for investigation and instructions for performing tasks that may be needed to help with testing.
 
 .. toctree::
    :maxdepth: 1