Ubuntu-based Distribution — Getting Started


Installing Tibbo's Ubuntu-based distribution on your LTPP3(G2) is easy and straightforward. Before starting, you'll need to prepare:

  • A USB flash drive with at least 1.5GB of free space
  • A jumper
  • A USB Type-C-to-A cable
  • A PC with serial terminal software (such as IO Ninja) — to monitor the installation progress

The install will take around 10-15 minutes. The steps:

  1. Download the binary and save it to the USB flash drive. This file must be named ISPBOOOT.BIN.
  2. With the LTPP3(G2) powered off, insert the USB flash drive into one of the board's USB Type-A ports.
  3. Place the jumper on CN11 (next to the buttons), perpendicular to the nearest edge of the board.
  4. Connect the USB Type-C-to-A cable between the board's console USB port and your PC.
  5. Power on the board and open the corresponding serial port in your terminal software.
  6. The actual installation process is fully automated. You will know it's complete when you see:
ISP all: Done
  1. Remove the USB flash drive and the jumper, and reboot the device (press the RST button).

The system is now ready for use. The default username and password are ubuntu/ubuntu.

If you would prefer to use SSH instead of the serial terminal, log in to the system and acquire its IP address:

ip addr show

Installing and updating packages

You can use apt-get to install and update packages on your system just as you would on most other Ubuntu-derived distributions. Performing an update is as easy as executing the following:

sudo apt-get update && sudo apt-get upgrade

After performing an upgrade of our PPA, a reboot is required. You can do so by running:

sudo reboot

We recommend that you update your system on the first boot and on a regular basis. Included in the updates is Tibbo's Personal Package Archive (PPA) containing useful resources for the LTPP3(G2).

Out-of-Box Experience (OOBE)

Included in our base image and the PPA are a variety of OOBE scripts designed to help you quickly and easily configure important parts of your system. We highly recommend updating and upgrading installed packages (as explained in the previous section) before using these scripts to ensure you always have the latest version.

Installing the Wi-Fi driver and associating with an access point

If you have the Wi-Fi/Bluetooth add-on module installed on your LTPP3(G2), you can use our interactive Wi-Fi configuration script. To do so, just run:

sudo tb_wlan_mainmenu

This script automates installing and uninstalling the system's Wi-Fi driver. In addition, the script also makes it easy to scan for and associate with Wi-Fi networks, as well as see the status of the current connection.

Note: After associating with a wireless network, the system will always automatically try to connect to it when in range.

Installing the Bluetooth driver

If you have the Wi-Fi/Bluetooth add-on module installed on your LTPP3(G2), you can use our interactive Bluetooth configuration script. To do so, just run:

sudo tb_bt_mainmenu

This script automates installing and uninstalling the system's Bluetooth driver. In addition, the script also makes it easy to pair and connect the system with a Bluetooth device.

Selecting Ethernet port mode

The LTPP3(G2) is equipped with two 10/100BaseT Ethernet ports, which can be daisy-chained or configured as two independent ports. We have created a script to facilitate selecting the Ethernet port mode. To run it, just enter:

sudo tb_daisy_chain_onoff

Setting up Visual Studio Code (VSC)

VSC can be used to remotely develop, debug, and deploy your applications in Python.

Here is how to set up VSC to work with your LTPP3(G2) board. In VSC:

  1. Click Extensions. Search and install the Remote - SSH extension if you don't have it installed already.
  1. Click Remote Explorer. Click Add New (the plus symbol).
  1. In the prompt, enter ssh <user>@<your LTPP3(G2)'s IP address>. You will be prompted to select an SSH configuration file to update/create.
  1. In the list of SSH targets, right-click on your device and click Connect to Host in New Window.
  2. You will be prompted to pick the platform; select Linux.
  3. A prompt will display the fingerprint for the system and ask if you want to continue. Click Continue.
  4. Enter your password when prompted. This will happen several times. When the connection and setup process are complete, you'll see "SSH: <IP address>" in a green box in the bottom-left corner.
  1. Click on Explorer. Click on Open Folder. Enter a local folder on the LTPP3(G2); for example, /home/ubuntu. Click OK. You will be prompted to select the platform and for your password, and then VSC will connect and open the folder.
  1. Create a new file. In it, write some code in Python and save it with the .py extension.
  1. Click on Extensions. Search for and select Python. Click on the blue Install in SSH: <IP address> button. When the installation is complete, the button will be replaced with Installed.
  1. Go back to your Python file. Click Run and Debug, then Python File in the prompt.

An embedded terminal window will open. After a few moments, it'll run your Python code.

Congratulations, you're developing and debugging on your LTPP3(G2) directly from VSC!

Python Wrapper for PinMux

PinMux is a truly unique feature of the LTPP3(G2)'s Plus1 CPU. It works as a "switchboard" that dynamically connects peripherals to GPIO lines. This on-the-fly reconfiguration is fully transparent to the OS and doesn't require a reboot — much less a kernel rebuild.

We have developed a Python wrapper to facilitate using this "switchboard" functionality that allows your code to map and remap peripherals on demand. The Python wrapper for PinMux has been included in Tibbo's PPA for this distribution since May 2021. If you have an older version of the PPA, update and upgrade your system to ensure you have the latest version and then reboot:

sudo apt-get update && sudo apt-get upgrade
sudo reboot

Example — Serial Echo

We've created a sample application (click here to download) that uses the Python wrapper to map the lines of a serial port, which echoes any received data back to the sender. This application demonstrates the straightforward process of mapping and implementing a serial port on the LTPP3(G2) running our Ubuntu-based distribution.

Before running this application, you first need to install pyserial, a serial port extension for Python. To do so, just run:

pip3 install pyserial

Once pyserial is installed, you can run the application from a terminal or through VSC. Before doing so, however, make sure that it maps the board's lines to the pins corresponding to your desired serial port.

Using this sample application is simple: Connect your desired serial port on the LTPP3(G2) to a computer running serial terminal software, such as IO Ninja. You can send strings of text, which will be printed on the device's console and echoed back to the serial terminal.

Example — I²C Communications

For our second example, we've created a sample application (click here to download) that uses a Python wrapper to map the board's I/O lines to an I²C sensor. This application polls Tibbit #36 — a three-axis accelerometer (this Tibbit requires Tibbit #00-3, it will provide the I/O and power lines). The download includes the Python library for Tibbit #36.

If you don't have Tibbit #36 or want to use a different I²C peripheral, you will need to modify this application accordingly. Tibbit #36 was chosen because it is a more complicated I²C sensor, which means that your code will probably be simpler than this sample code.

Before running this application, you will need to install smbus2, which provides Python bindings for Linux SMBus access through i2c-dev. To do so, just run:

pip3 install smbus2

Now you can run the test_tbt36.py application from a terminal or via VSC by executing the following command:

python3 test_tbt36.py

Either way, you will see the sensor output printed in the terminal (VSC shown below):

Example — RS485 Communications

V0.5.0 (released in July 2022) of our Ubuntu-based distribution added PinMux support for RS485 communications. To demonstrate this capability, we've created a sample application (click here to download) that continuously polls a Bus Probe. For this example, you'll need a BP#03, a Tibbit #05 placed in socket S1, and a Tibbit #21 in socket S2.

To run this sample, you'll need the pyserial and pymodbus packages. If you don't already have them installed, enter the following in a terminal on the LTPP3(G2):

pip3 install pyserial pymodbus

After you've installed pyserial and pymodbus, you can run the sample application from a terminal connected to the LTPP3(G2). We recommend IO Ninja, which can connect to an LTPP3(G2) via the serial debugging port or SSH, as well as so much more.

python3 poll_bp.py

Of course, you can always use a different tile or Bus Probe — you'll just need to modify the application accordingly.

Example — Interrupts

Also added in V0.5.0 is support for user-defined interrupts: You can dynamically map any PinMuxable line as an interrupt. Currently, the functionality is limited to only edge interrupts (rising and falling exclusively).

For example, we can set I/O line 32 (the first pin of socket S3) to be a falling edge interrupt with the following command:

gpiomon -f 0 $PL_IO_NUM_32

To test that it has been configured correctly, just trigger a state change on the pin. The easiest way to do so is plugging a Tibbit #00-3 into socket S3 and Tibbit #38 (pushbutton) into socket S4. Now, pressing the pushbutton will trigger the interrupt, which is reflected in the terminal.

While you can only have eight interrupts at one time, the magic of PinMux means that you can dynamically remap them to different lines to meet the needs of your project. If you're writing modules, just remember to release an unused interrupt before assigning a new one.

Example — Reading One-Time Programmable (OTP) Memory

Also included in V0.5.0 is the driver for reading the Plus1 CPU's OTP memory. For detailed instructions on writing to the OTP memory, please refer to our documentation.

For a raw dump of the entire OTP memory section in hexadecimal format, just enter:

hexdump /sys/bus/nvmem/devices/sp-ocotp0/nvmem

Note: Any blocks of the OTP memory that haven't been written to will show up as zeroes.

Alternatively, if you only want to see the value written to the serial number section of the OTP memory, just run:

cat /proc/cpuinfo

Note: If you haven't written a serial number to the OTP memory, the Serial field will be populated with zeroes.