Skip to content

Latest commit

 

History

History
126 lines (89 loc) · 6.05 KB

quickstart.md

File metadata and controls

126 lines (89 loc) · 6.05 KB

Uplink quick start

This page is intended to get you up and running with uplink and bytebeam platform.

Initial setup

Create a free account on https://cloud.bytebeam.io if you haven't already. After registering you will be prompted to create a project. Select linux as the device type when creating the project. A project is where all your data will live. This page goes into the details of all the features. You can read it at your leisure but this page will also provide brief overview of features needed to follow along.

The device management page has a create device button. Click on it, your browser will download a device_1.json file. Your devices are supposed to use this file to connect to our platform. Each device you create on the dashboard is supposed to map to a unique physical device. This file contains device private keys and the ca certificates, everything needed to securely connect to our backend.

Download the uplink executable for your platform from the releases page and start it by providing the device.json file as an argument:

./uplink -a device_1.json -v

Uplink will start and connect to our backend. You will notice a few changes in your device management page:

  • The last heartbeat of the created device will change to a few seconds ago. This means that the device is live.
  • You will see a value in the uplink version field in the overview of this device. Uplink is pushing its version along with the device shadow.
  • You will be able to login to your device remotely using the Remote shell button.

The uplink program is supposed to run as a background daemon on your device.

You can also configure the behavior of uplink using a toml configuration file like this:

./uplink -a device_1.json -c config.toml -v

Monitoring

You have already seen some primitive form of monitoring during the setup described above (last heartbeat and uplink version). Here are some more ways you can monitor your devices using our platform:

Linux system stats

Uplink can automatically collect system info like disk, network, cpu usage, memory usage, etc and upload it to our cloud. You can visualize this info remotely using our dashboard, like a remote system monitor. Create a new dashboard and add two line chart panels to it, select stream uplink_system_stats and field used_memory in the first panel and stream uplink_processor_stats and field usage in the second one. You should see something like this:

System stats

Line chart is one of several panel types. See our documentation for detailed description of all available panels.

Logging

Uplink can also automatically collect journalctl (gnu linux) and logcat (android) logs and upload them to cloud for visualization using our logs panel. To enable log collection, add this to your config.toml file:

[logging]
tags = ["tag1", "tag2"]
min_level = 4 # must be between 0 (FATAL) and 6 (VERBOSE), 4 is info

Logs

Monitoring domain specific data

Till now we have shown you how to monitor generic system information (logs, system stats). Let's say you have an application which is generating some data specific to your use case, that you want to be able to monitor remotely. Examples could be:

  • Battery level of a wireless component
  • Data being read from sensors
  • GPS location of your device
  • Number of connected users
  • Firmware version of an IOT component

You can monitor and visualize this information remotely using our dashboards and panels. To do this you will need to create a stream. A stream is like a table in our backend, ordered by timestamp, to which you can push data remotely from your devices, and then visualize using our portal. You've already seen examples of some streams that are created by default for you (device_shadow, uplink_system_stats for RAM, uplink_processor_stats for CPU usage). You can also create streams and push data to them manually using uplink.

To do this, you will have to create something called a tcpapp in your uplink configuration. Add this to your config.toml:

[tcpapps.custom_application]
port = 8049

custom_application is just an identifier. port is the tcp port on which you want uplink to listen for incoming connections. One of your programs running on the same device can connect to this tcp port and write data to it, and it will be uploaded to our backend by uplink.

Say you created a stream called motor_info with these fields:

  • temperature : Float32
  • rpm : UInt32
  • vibrations : Float32

You can connect to uplink over the declared tcp port and push data to it, one message per line, as json objects. This is how a message is supposed to look like:

{"stream": "motor_info", "sequence": 5, "timestamp": 1738581618576, "temperature": 74, "rpm": 650, "vibrations": 0.31}

Individual messages should be written to the port separated by ascii newlines (\n). Uplink repository has a utility program that you can use to generate some mock data using this command:

cargo run --bin push_data -- --interval 1 --stream motor_info --format temperature:float,rpm:int,vibrations:float --uplink-port localhost:8049 -v

Uplink will buffer and upload data to our cloud and then you can visualize it using our dashboards. You should see the dashboards after around a minute or so, because 60s is the default buffering interval for streams in uplink. You can configure how the data for a stream should be handled in the toml file like this:

[streams.motor_info]
# flush data after 50 messages have collected, or after 10s, whichever is earlier
batch_size = 50
flush_period = 10
compression = "Lz4" # add this if you want uplink to compress your data before uploading it, if you want to save on network bandwidth.