reTerminal built-in devices#
Programmable interfaces#
This section is based on the official documentation for the reTerminal: Hardware and Interfaces Usage
All programmable data can be passed in file streams that can be read and/or written to.
For example, keyboard inputs and communication over web-sockets are all read as a file streams.
The reTerminal has 3 programmable LED’s and a light sensor that can be controlled like a regular file.
You can see, there are 3 programmable LEDs in the reTerminal:
STA light can be turned on as red or green.
USR light can only be turned on as green.
The lights can be controlled at the OS level by editing files in the
/sys/class/leds/ directory. Use ls -al to list the files in this directory:
username@hostname:/sys/class/leds/usr_led0 $ ls -al
total 0
drwxr-xr-x 3 root root 0 Jan 25 20:33 .
drwxr-xr-x 8 root root 0 Jan 25 20:33 ..
-rw-r--r-- 1 root root 4096 Jan 26 22:02 brightness
The brightness file inide the usr_led0 controls the brightness of LED0. But,
because only root has write permissions to this file, we will likely run into
permissions errors if we try to edit the value directly:
$ nano /sys/class/leds/usr_led0/brightness
Permission denied
$ echo 255 > /sys/class/leds/usr_led0/brightness
Permission denied
$ sudo echo 255 > /sys/class/leds/usr_led0/brightness
Permission denied
There are a few possible approaches to this problem:
Use sudo + text-editor#
You can open a text-editor with root permissions using sudo:
# nano text editor
sudo nano /sys/class/leds/usr_led0/brightness
# or, you can use vi/vim text editor
sudo vim /sys/class/leds/usr_led0/brightness
Edit the brightness file to a value between 0-255 using the editor. When you
save, you should see the change immediately.
Use sudo + su#
Using an editor is perfectly reasonable for a one-off change, but annoying if you want to make the change more often.
We can use the echo value > /path/to/file pattern, but only if we have
permissions to write to /path/to/file – we can obtain these permissions if we
run the entire command as the root user.
NOTE: Running commands as the root user can have unintended consequences, ranging from annoying/tedious to fix, to completely devastating/permanently ruinous for your machine. You should avoid being
rootwherever possible (see Use sudo + tee section below for how to avoid it for this problem).
You can enter a root shell instance using the command su (switch user), or
by using sudo -i or sudo -s:
user@hostname $ sudo su
root@hostname #
user@hostname $ sudo -i
root@hostname #
user@hostname $ sudo -s
root@hostname #
Your shell should now display root@hostname:~# .
Turn on the LED with maximum brightness
# echo 255 > brightness
Turn off the LED
# echo 0 > brightness
Similarly, you can control usr_led1 and usr_led2 and even the buzzer on
/sys/class/leds/usr_buzzer
When done working as root, you can exit the root shell and return to your user
shell using the exit command (or Ctrl-D as a hotkey):
root@hostname # exit
user@hostname $
Use sudo + tee#
If we want to avoid using a text editor, AND avoid logging into a root shell
instance, it would be great if something like this worked:
$ sudo echo 255 > /sys/class/leds/usr_led0/brightness
But it doesn’t! Can you understand why? Consider which part of the instruction
sudo applies to. Unfortunately, there is no way to sudo > or sudo filename
since sudo executes commands as the root user, NOT filenames/redirects.
What if there were a command that we could put after the redirect, and sudo
that command? What would that command need to do? It’s time to introduce a “new”
command: tee.
To be clear, tee is a 50 year
old program and an absolute classic – it is as ubiquitous/essential as the
other OG unix programs like ls, cat, echo. We will see why in the
following example.
Try running man tee in your reTerminal. You should see something like the
following:
TEE(1)
NAME
tee - read from standard input and write to standard output and files
SYNOPSIS
tee [OPTION]... [FILE]...
DESCRIPTION
Copy standard input to each FILE, and also to standard output.
We have here a command that will read from standard input, and write that same content from standard input into BOTH standard output AND files – the files we can specify as arguments.
$ echo 255 | /sys/class/leds/usr-led0/brightness
# this command is missing `tee` and `sudo`.... find where to put them, and you've learned a very important unix pattern!
Luminosity Sensor#
The digital light sensor can read the surrounding light levels.
Enter the following directory
cd /sys/bus/iio/devices/iio:device0
Read the following file to obtain the light intensity value in Lux
cat in_illuminance_input
Output:
pi@raspberrypi:/sys/bus/iio/devices/iio:device0 $ cat in_illuminance_input
2719
Note: We don’t need to be root to read this file. Its permissions are set to let all users read it, even-though it belongs to the root user:
rw-r--r-- 1 root root 4096 Jan 30 22:16 in_illuminance_input
Python Library for reTerminal#
Seeed Studio provided a python library to access most of the sensors and actuators of the reTerminal.
Install the library seeed-python-reterminal (see official
Github repo) using
pip:
# NOTE: run this with a venv activated!
pip install seeed-python-reterminal
# NOTE: you will also need this dependency
pip install RPi-GPIO
Now you can import it to a test script (eg. buzz.py)
import seeed_python_reterminal.core as rt
import time
print("BUZZER ON")
rt.buzzer = True
time.sleep(1)
print("BUZZER OFF")
rt.buzzer = False
This will sound the buzzer of the reTerminal for 1 second.
To run the script:
sudo $(which python) buzz.py
Alternatively, first elevate your shell, then execute the script normally:
user@hostname:~ $ sudo -i
root@hostname:~# python buzz.py
Note: this library is simply a wrapper to the OS operations we did in the previous section.
See the official seeed-python-reterminal
Github repo for API
reference on how to control:
LED’s
Accelerometer
Programmable Buttons
Light Sensor