Skip to content

Adding a New Device

Warning

VERY IMPORTANT: For some stupid reason (to keep it cheap it turns out), the Armbian/Rock Pi S combination always assigns the same ethernet MAC address to the eth0 network interface. This will WREAK HAVOC with DHCP as ALL the RockPis will get the same IP address if you plug in a network cable. This is very bad. To fix this, after booting up and getting into the linux OS either via SSH or directly with a serial console, you need to edit the /etc/udev/rules.d/05-fixMACaddress.rules file and add this line at the bottom:

    KERNEL=="eth0", ACTION=="add" RUN+="fixEtherAddr %k 06"

Start Up The RockPi

To use a new FIDO Sampler, you will need to install a version of OS on your RockPi device which will serve as the controller for the device.

Note

If you need to build a new SD card image, see the instructions here

  1. Download the latest .img file from the mbari-readinet-images S3 bucket. Note that you will have to have an AWS login account with access to the account with this S3 bucket. If you don't, check with the ESP team for help or they can get you the image directly.

  2. This SD card image can be run directly as is, but it's better to run a script to change the image so you can set the device's ID and the uplink WiFi settings before installing it in the RockPi. To do this, check out the readinet code repository onto a Linux machine (Ubuntu has been tested). Download the SD image somewhere on your Linux machine and then open a terminal and change into the readinet repository, then into the os directory. There is a script called set-device-vars.sh and you can run it like this:

    sudo set-device-vars.sh --id <DEVICE_ID> --ssid <SSID> --psk <PSK> --path </path/to/image.img>

  3. Now that the SD card image is ready, insert your SD into machine and copy the .img to the SD card.

    • For a graphical experience, use Balena Etcher
    • For a text-based experience, use the dd command
  4. Insert the SD Card into the RockPi and power the device on
    • The device can take up to 3 minutes to complete its initialization routine
  5. After initialization completes, there will be a wifi network that appears starting with readinet-<device-id>. (Each device will have a different uuid for this wifi address)
  6. Connect to the readinet-<device-id> WiFi network with a default password of readinet
  7. You can then access the web interface of the device at https://10.42.0.1 and you will see something similar below.

Note

The SSL certificate may not be valid and your browser may complain, just accept the 'risk' to move to the web application.

Device UI Step 1

Note

If the uplink connection was not successful, the map does not show up in the application. That is to be expected.

Connect to the Internet

If the uplink was not specified ahead of time using the steps above, you will need to tell the device what WiFi network to connect to so that it can reach the READinet servers that are hosted in the cloud.

  1. Click on Management on the left menu of the device web page and then update the Uplink Internet with the WiFi network and password and then click on Save Changes (you will have to click outside of the boxes you edit to make the Save Changes button appear). Device Management 1

Note

When you save changes, it will likely drop your connection to the readinet-<device-id> WiFi so you will have to reconnect to continue.

  1. That will connect to the device to the internet so it can talk to the wider world. (The map should then appear on subsequent page navigation).

Connect Device to Cloud VPN

In order to connect your device to the remote cloud management service, you will need to place the device inside the server Virtual Private Network (VPN). FIDO uses headscale/tailscale to enable this VPN so you first need to tell the tailscale instance running on the device what VPN you want to join.

  1. If not already connected, connect to the readinet-<device-id> wifi using the steps above.
  2. Next, SSH into the device with root@10.42.0.1. The password is readinet.

  3. Initiate a vpn connection by issuing tailscale up --login-server https://vpn.prod.readinet.org (or tailscale up --login-server https://vpn.dev.readinet.org for the development server) Tailscale Command

  4. The command should respond with a URL that you can copy and paste into your browser which will then give you further instructions on how to command the server to accept the device into the VPN. Headscale Instructions

  5. You can then ssh into the cloud server using ssh admin@prod.readinet.org or ssh admin@dev.readinet.org

  6. Once you have ssh'd into the server, copy and paste the command that was in the web browser from a couple of steps ago. Headscale Command

Note

You need to change the USERNAME to readinet in the command before running it

  1. You can verify the device was added by running headscale nodes list Headscale List

  2. Back on the device (connected via SSH), restart readinet-web with systemctl restart readinet-web.

Note

Any time you change the VPN configuration, you must restart readinet-web, otherwise sync events won't work.

  1. On the device via ssh, VPN connectivity can be verified by issuing tailscale status or by pinging the server through the VPN with ping server.readinet.local

Warning

There are two separate VPNs: Dev (vpn.dev.readinet.org) and Prod (vpn.prod.readinet.org). You can only be connected to one at a time.

Add Device to the Organization

The last step in bringing a new device online is you need to add the device to an Organization. The server is aware of the device now that it is part of the VPN, but it doesn't know which organization owns the device.

  1. If not already connected, connect to the readinet-uuid wifi using the steps above.

  2. On the cloud web application, select the organization you want to add the device to and make sure you have selected Devices on the left navigation menu. You may see some devices already, but you won't see the device you are trying to bring up yet. Cloud Organization Page

  3. Under the Add New Devices section of the page, select and copy the Organization Secret.

  4. Next, go the local device web application at https://10.42.0.1 Device Management Page

  5. Click on Adopt and paste in the Organization Secret you copied and click on Save (or something like that). You should then see a notice that it was added to the organization. Device Adopted

  6. Back on the cloud web application, if you refresh the Devices page, you should now see the new device and it should show that it is online. New Device Visible

Configure the device

While not common, there may be times you need to change the configuration on the device itself. Here are some instructions on how you would do that.

  1. If not already connected, connect to the readinet-uuid wifi using the steps above.
  2. SSH into the device using ssh root@10.42.0.1. The default password is readinet
  3. The main configuration for the web interface is found in /opt/web/.env. You can edit the file by issuing vim /opt/web/.env or nano /opt/web/.env
  4. After making changes, you must reboot the interface by issuing systemctl restart readinet-web

The configuration options are as follows:

  • SAMPLER_TTY: The device location of the sampler on the linux box. Should start with /dev
  • SAMPLER_BAUD: Baud rate for the sampler serial connection. Should be a positive integer.
  • SAMPLER_TIMEOUT_SECONDS: The number of seconds before a sampler operation would be cancelled. Note: this value can be overridden in code for some sampler operations
  • SAMPLER_SELF_CHECK_SECONDS: The number of seconds between running self checks for the sampler. This will temporarily lock the sampler.
  • CONNECTIVITY_PING_CHECK_SECONDS: The number of seconds between sending heartbeat pings to tell the server that the RockPi is online.
  • THIS_DEVICE_ID: The unique identifier for the device. This should match /etc/machine-id. Changing this value is not recommended.
  • APP_VERSION: The version of the application displayed in the lower left hand corner of the interface. Generated through the OS build process.
  • MQTT_BROKER_URL: The location of the MQTT Broker. In normal scenarios, it should be server.readinet.local.
  • ROLE: The role of the system. Must be either device or server. There should only be one server in the deployment.
  • SECRET_KEY: This is a web-server specific item to deal with cross site forgery. Do not change this value
  • FLASK_ENV: This is signifier for what environment the application is running in. It should be prod unless otherwise specified.
  • SQLALCHEMY_DATABASE_URI: A sqlite URI that points to the database in use
  • REMEMBER_COOKIE_HTTPONLY: A web-server specific item
  • SESSION_COOKIE_SAMESITE: A web-server specific item
  • RUN_BACKGROUND_THREADS: Background threads provide MQTT-syncing and device status reporting. This should be true unless debugging.
  • APP_VERSION: A text string that will get displayed as the current version. This should be automatically templated from the OS build.