uplink

Uplink is a rust based utility for efficiently sending data and receiving commands from an IoT Backend. The primary backend for uplink is the Bytebeam platform, however uplink can also be used with any broker supporting MQTT 3.1.1.

Features

• Efficiently send data to cloud with robust handling of flaky network conditions.
• Persist data to disk in case of network issues.
• Receive commands from the cloud, execute them and update progress of execution.
• Can auto download updates from the cloud to perform OTA firmware updates.
• Provides remote shell access through Tunshell
• Supports TLS with easy cross-compilation.

Install Pre-built Binary

Pre-built binaries for select platform targets have been made available in the repo's releases page, download the binary specific to your system and add it's location to PATH.

Build and Install

Build and install with Cargo:

cargo install uplink # NOTE: This should work once crate is published

Build and run from source:

git clone https://github.com/bytebeamio/uplink.git
cd uplink
cargo run --bin uplink -- -a <device auth json file>

Build from source for ARM systems

In case you want to run uplink on an ARM system, follow instruction given below to create an ARM compatible binary.

1. Install cross, a Zero setup cross compilation crate.

cargo install cross

2. Build binary for the target armv7-unknown-linux-gnueabihf.

cross build --release --target armv7-unknown-linux-gnueabihf

3. Retreive executable from /target/armv7-unknown-linux-gnueabihf/release/uplink and execute it on target device.

See releases for other options.

Getting Started

Setup

You can start uplink with the following command, where you will need to provide an auth.json file:

uplink -a auth.json

The auth.json file must contain information such as the device's ID, the broker's URL, the port to connect to and the TLS certificates to be used while connecting as can be seen inside dummy.json. When connecting over non-TLS connections, authentication information is unncessary as illustrated by noauth.json.

NOTE: If you are using Bytebeam, you could download the file downloaded from the Bytebeam UI. If you are using your own broker instead, you could use uplink without TLS, but we recommend that you use TLS and provision your own certificates to do it. You can read more about securing uplink in the uplink Security document

Configuring uplink

One may configure certain features of uplink with the help of a config.toml file by using the commandline arguments -c or --config:

uplink -a auth.json -c config.toml

It must be noted that parts of, or the entirety of the config file is optional and a user may choose to omit it, letting uplink default to configuration values that are compiled into the binary. uplink only expects the config.toml to contain configuration details as given in the example config.toml file in the configs folder.

Writing Applications

uplink acts as an intermediary between the user's applications and the Bytebeam platform/MQTT 3.1.1 broker of choice. One can accept Actions from the cloud and push data(from applications such as sensing) or Action Responses back.

Receiving Actions: Actions are messages that uplink expects to receive from the broker and is executable on the user's device. The JSON format for Actions are as such:

{
    "action_id": "...",
    "kind": "...",
    "name": "...",
    "payload": "..."
}

NOTE: Some Actions are executed by built-in "collectors", e.g. Actions with kind: process and kind: collector. The tunshell action, i.e. Action with name: tunshell is used to initiate a remote connection over tunshell while the OTA action, i.e. Action with name: update_firmware can download OTA updates.

Streaming data: Data from the connected application is handled as payload within a stream. uplink expects the following JSON format for Streamed Payload:

{
    "stream": "...",
    "sequence": ...,
    "timestamp": ...,
    // ...payload: more JSON data
}

An example data packet on the stream "location", with the fields "city" being a string and "altitude" being a number would look like:

{
    "stream": "location",
    "sequence": 10000000,
    "timestamp": 1987654,
    "city": "Bengaluru",
    "altitude": 123456,
}

NOTE: uplink expects values for the stream, sequence and timestamp field to be properly set, the payload maybe as per the requirements of the IoT platform/application.

Responding with Action Responses: Applications can use Action Response messages to update uplink on the progress of an executing Action. They usually contain information such as a progress counter and error backtrace. Action Responses are handled as Streamed data payloads in the "action_status" stream and thus have to be enclosed as such. uplink expects Action Responses to have the following JSON format:

{
    "stream": "action_status",
    "sequence": ...,
    "timestamp": ...,
    "action_id": "...",
    "state": "...",
    "progress": ...,
    "errors": [...]
}

An example success response to an action with the id "123", would look like:

{
    "stream": "action_status",
    "sequence": 234,
    "timestamp": 192323,
    "action_id": "123",
    "state": "Completed",
    "progress": 100,
    "errors": []
}

Downloading OTA updates and other files

uplink has a built-in feature that enables it to download OTA firmware updates, this can be enabled by setting the following field in the config.toml and using the -c option while starting uplink:

[downloader]
actions = ["update_firmware"]
path = "/path/to/directory" # Where you want the update file to be downloaded

uplink -c config.toml -a auth.json

Once enabled, Actions with the following JSON will trigger uplink to download the file and hand-over the action to a connected application to perform the necessary firmware updation:

{
    "action_id": "...",
    "kind": "process",
    "name": "update_firmware",
    "payload": "{
        \"url\": \"https://example.com/file\",
        \"version\":\"1.0\"
    }"
}

Once downloded, the payload JSON is updated with the file's on device path, as such:

{
    "action_id": "...",
    "kind": "process",
    "name": "update_firmware",
    "payload": "{
        \"url\": \"https://example.com/file\",
        \"download_path\": \"/path/to/directory\",
        \"version\":\"1.0\"
    }"
}

Remote Shell Connection

With the help of tunshell, uplink allows you to remotely connect to a device shell. One can provide the necessary details for uplink to initiate such a connection by creating a tunshell action, with the following JSON format:

{
    "action_id": "...",
    "kind": "...",
    "name": "tunshell",
    "payload": "{
        \"session\": \"...\",
        \"encryption\": \"...\"
    }"
}

NOTE: Bytebeam has built-in support for tunshell, if you are using any other MQTT broker, you may have to manage your own tunshell server to use this feature.

Testing with netcat

You can test sending JSON data to Bytebeam over uplink with the following command while uplink is active

nc localhost 5555
{ "stream": "can", "sequence": 1, "timestamp": 12345, "data": 100 }
{ "stream": "can", "sequence": 1, "timestamp": 12345, "data": 100 }
{ "stream": "can", "sequence": 1, "timestamp": 12345, "data": 100 }

The complete API reference for the uplink library is available within the library documentation.

Android executable instructions

• install cargo-ndk v2.11.0 (cargo install cargo-ndk --version 2.11.0)
• export ANDROID_NDK_HOME=~/Android/Sdk/ndk/25.0.8775105
• cargo ndk --target x86_64-linux-android --platform 23 build --bin uplink
• move executable to /data/local/
• set port to something else
• set persistence path to /data/local/uplink
• chmod +x uplink_exe

Contributing

Please follow the code of conduct while opening issues to report bugs or before you contribute fixes, also do read our contributor guide to get a better idea of what we'd appreciate and what we won't.