Commit 7d33271f authored by Dorota Czaplejewicz's avatar Dorota Czaplejewicz
Browse files

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

Add phone development setup info

See merge request Librem5/developer.puri.sm!362
parents 1d7f930b 15d2c9b9
......@@ -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
......
.. |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
==========
......
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
......
......@@ -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.
.. _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
.. _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.
......@@ -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
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment