config.toml

# Collection of binaries which uplink can spawn as a process
# This ensures that user is protected against random actions
# triggered from cloud.
processes = [{ name = "echo", timeout = 10 }]

# Map of action names for re-routing on partial completion. An action is considered
# partially completed when progress is 100, but status is neither "Failed" nor "Completed".
action_redirections = { "firmware_update" = "install_update", "send_file" = "load_file", "send_script" = "run_script" }

# Script runner allows users to trigger an action that will run an already downloaded
# file as described by the download_path field of the JSON payload of a download action.
script_runner = [{ name = "run_script", timeout = 10 }]

# Location on disk for persisted streams to write backlogs into, also used to write
persistence_path = "/tmp/uplink/"

# Size of in-memory buffer for dynamically created streams. Used for backlog management.
default_buf_size = 1024 # 1KB

# Maximum number of data streams that can be accepted by uplink
max_stream_count = 10

# All streams will first push the latest packet before pushing historical data in
# FIFO order, defaults to false. This solves the problem of bad networks leading to
# data being pushed so slow that it is practically impossible to track the device.
default_live_data_first = true

# MQTT client configuration
#
# Required Parameters
# - max_packet_size: Maximum packet size acceptable for MQTT messages
# - max_inflight: Maximum number of outgoing QoS 1/2 messages that can be
#                 handled by uplink, at a time, requiring acknowledgedment.
# - keep_alive: Number of seconds after which the MQTT client should ping
#               the broker if there is no other data exchange.
# - network_timeout: Number of seconds after which the MQTT client can timeout
#                    while waiting for a network response.
[mqtt]
max_packet_size = 256000
max_inflight = 100
keep_alive = 30
network_timeout = 30

# TCP applications that detail applications which connect with uplink
# Required Parameters
# - port: TCP/IP Port on which application can connect to uplink over
# - actions: A list of actions that uplink can forward to the app,
#   with configurable timeouts
[tcpapps.1]
port = 5050
actions = [{ name = "install_update" }, { name = "load_file" }]

[tcpapps.2]
port = 6060
actions = []

# Metrics configurations are available for serializer and streams. By default
# they are disabled and no metrics will be forwarded to platform.
# Parameters
# - topic(optional): One can configure to push stats to a specific topic,
#   different from the default by configuring it with this field.
#
# Serializer module can publish associated metrics, to keep track of
# serializer performance.
[serializer_metrics]
enabled = true

# Serializer module can also publishe stream metrics, to keep track of latencies
# and batch sizes on a per-stream basis.
# NOTE: Leaving this configuration empty like the following tells uplink to enable
# sending metrics, but with default topic string.
[stream_metrics]
enabled = true
blacklist = ["cancollector_metrics", "candump_metrics", "pinger"]

# Table of pre-configured data streams, specifies streams of data elements that are to
# be collected, batched and forwarded to serializer to then be published onto platform.
#
# Required Parameters
# - batch-size: Number of data points that shall be included in each Publish
# - topic(optional): topic-filter to which data shall be published. If left
#   unconfigured, stream will be created dynamically.
# - flush-period(optional): Duration in seconds after a data point enters the stream
#   and WILL be flushed by collector. Defaults to 60s in case not configured.
# - compression(optional): an enum values to determine what compression the serializer
#   should perform on the data transiting through the stream. Currently supported
#   compression schemes are Lz4 and Disabled. Defaults to Disabled.
# - persistence(optional): helps persist relevant information for data recovery purposes,
#   used when there is a network/system failure.
# - priority(optional, u8): Higher prioirity streams get to push their data
#   onto the network first.
# - live_data_first(optional, bool): All streams will first push the latest packet
#   before pushing historical data in FIFO order, defaults to false. This solves the
#   problem of bad networks leading to data being pushed so slow that it is practically
#   impossible to track the device.
#
# In the following config for the device_shadow stream we set batch_size to 1 and mark
# it as non-persistent, also setting up live_data_first to enable quick delivery of stats.
# Streams are internally constructed as a map of Name -> Config
[streams.device_shadow]
topic = "/tenants/{tenant_id}/devices/{device_id}/events/device_shadow/jsonarray"
flush_period = 5
priority = 75
live_data_first = true

# Example using compression
[streams.imu]
topic = "/tenants/{tenant_id}/devices/{device_id}/events/imu/jsonarray/lz4"
batch_size = 100
compression = "Lz4"
priority = 50

# Configuration details associated with uplink's persistent storage module which writes publish
# packets to disk in case of slow or crashed network, for recovery purposes.
#
# Required Parameters
# - max_file_size(defaults to 100MB): Maximum size upto which single persistence file can grow.
#   This value alone can be changed to configure in-memory storage of packets during network recovery.
# - path(optional): Path to directory for storing backlog in files, shouldn't contain anything else.
#   Please ensure the location is unique for each stream to ensure there is no clash in files.
# - max_file_count(optional, defaults to 3): Maximum number of persistence files allowed on disk.
#
# NOTE: Persitence is an optional feature that is disabled by default, i.e. if not inlcuded in the
# configuration, we use transient(in-memory) storage to handle network downtime only.
[streams.gps]
topic = "/tenants/{tenant_id}/devices/{device_id}/events/gps/jsonarray"
batch_size = 10
persistence = { max_file_size = 1048576, max_file_count = 10 }

# NOTE: While it is possible to configure persistence to be disabled, including only max_file_count
# without path causes non-persistence. Configuring only the persistence path is allowed and the other
# config values will be default. Configuring only max_file_size is also allowed, without persistance.
[streams.motor]
topic = "/tenants/{tenant_id}/devices/{device_id}/events/motor/jsonarray/lz4"
batch_size = 50
compression = "Lz4"
persistence = { max_file_count = 3 }

# Built-in streams: action status is a special case of stream and should be configured separately,
# outside of the streams map. The action_status stream is used to push progress of Actions in
# execution. This configuration is required or will lead to fallback to default config.
#
# NOTE: Action statuses are expected on a specifc topic as configured in example below.
# This also means that we require a topic to be configured or uplink will error out.
# Given the importance of conveying action status at the earliest to platform,
# it has highest priority by default of 255.
[action_status]
topic = "/tenants/{tenant_id}/devices/{device_id}/action/status"
flush_period = 2
priority = 255

# Configurations for uplink's built-in file downloader, including the actions that can trigger
# a download, the location in file system where uplink will download and store files from the
# provided URL in the payload of download file actions, over HTTP(S).
# If left unconfigured, downloader will be disabled.
#
# Required Parameters
# - actions: List of actions names that can trigger the downloader, with configurable timeouts
# - path: Location in fs where the files are downloaded into
[downloader]
actions = [
    { name = "update_firmware" },
    { name = "send_file", timeout = 10 },
    { name = "send_script" },
]
path = "/var/tmp/ota-file"

# Configurations associated with the system stats module of uplink, if enabled
# system stats such as memory in use and CPU usage will be published onto special.
#
# Required Parameters
# - enabled: A boolean to determine if the feature must be enabled
# - process_names: List of process names that are to be tracked with system stats
# - update_period: Time in seconds between each collection/publish of system stats
[system_stats]
enabled = false
process_names = ["uplink"]
update_period = 30

# Define port to accept uplink control messages over HTTP.
[console]
enabled = true
port = 3333

# Configurations associated with running uplink in simulator mode, if enabled uplink
# will push simulated data for respond to actions listed with progress 0..=100.
#
# Required Parameters
# - actions: action routes on which uplink simulator can accept actions
# - gps_paths: path to directory containing files with gps paths to be used in simulation
# [simulator]
# actions = [{ name = "lock" }]
# gps_paths = "./paths/"

# Configuration of logger, journalctl in the case of linux. As configured, uplink will
# push log lines in batches of size
#
# Required Parameters
# - tags: syslog identifiers for the processes to be logged, e.g. systemd, sshd, kernel
# - units: names of the systemd units that are to be logged, e.g. collector.service, app.service
# - min_level: priority level by number(7 is Debug, 0 is Emergency)
# - stream_size: maximum number of log line before the log stream is flushed
#
# [logging]
# tags = ["systemd"]
# units = ["collector"]
# min_level = 7
# stream_size = 100

# Configurations associated with in-built device-shadow collector
#
# Required Parameters
# - interval: time in seconds after which device-shadow is pushed onto platform, default value is 60
[device_shadow]
interval = 30

# The on-device service bus exposes an MQTT interface for inter-process communication
# Required Parameters
# - port: the port on which the broker/server is listening for incoming service connections
# - joins: description of how uplink will join incoming data and push outgoing data streams
# - console_port: port on which the rumqttd console API is exposed
[bus]
port = 1883
console_port = 3030
joins = { output_streams = [
    { name = "location", construct_from = [
        { input_stream = "gps", select_fields = [
            "latitude",
            "longitude",
        ] },
        { input_stream = "altimeter", select_fields = [
            "altitude",
        ] },
    ], push_interval_s = 60, no_data_action = "null", publish_on_service_bus = true },
    { name = "device_shadow", construct_from = [
        { input_stream = "device_shadow", select_fields = "all" },
    ], push_interval_s = "on_new_data", no_data_action = "previous_value", publish_on_service_bus = true },
    { name = "example", construct_from = [
        { input_stream = "stream_one", select_fields = [
            "field_x",
            "field_y",
        ] },
        { input_stream = "stream_two", select_fields = [
            { "field_z" = "field_x" },
        ] },
    ], push_interval_s = 120, no_data_action = "previous_value", publish_on_service_bus = false },
] }