NRuuviTag

A collection of .NET libraries to simplify interacting with RuuviTag IoT sensors from Ruuvi.

The repository contains a core library that defines common types, and listener implementations that observe the Bluetooth LE advertisements emitted by RuuviTag devices. Samples received from RuuviTags can be automatically published to an MQTT server or to an Azure Event Hub.

The repository contains the following listener implementations:

• Windows (using the Windows 10 SDK)
• Linux (using a modified version of DotNet-BlueZ to receive advertisements from BlueZ's D-Bus APIs)

The nruuvitag command-line tool can be used to as a turnkey solution to start receiving and publishing RuuviTag sensor data to an MQTT server or Azure Event Hub.

Example Usage

See the samples folder for more detailed examples of usage.

Usage is very straightforward. For example, to listen via the Windows 10 SDK using the NRuuviTag.Listener.Windows NuGet package (source):

IRuuviTagListener client = new WindowsSdkListener();

await foreach (var sample in client.ListenAsync(cancellationToken)) {
    // sample is a RuuviTagSample object.
}

To listen via BlueZ on Linux using the NRuuviTag.Listener.Linux NuGet package (source):

IRuuviTagListener client = new BlueZListener("hci0");

await foreach (var sample in client.ListenAsync(cancellationToken)) {
    // sample is a RuuviTagSample object.
}

To only observe specific RuuviTag devices using MAC address filtering:

bool CanProcessMessage(string macAddress) {
    return string.Equals(macAddress, "AB:CD:EF:01:23:45");
}

await foreach (var sample in client.ListenAsync(CanProcessMessage, cancellationToken)) {
    // sample is a RuuviTagSample object.
}

Publishing Samples to MQTT

The NRuuviTag.Mqtt.Agent NuGet package (source) can be used to observe RuuviTag broadcasts and forward the samples to an MQTT server:

public async Task RunMqttAgent(
  IRuuviTagListener listener,
  ILoggerFactory? loggerFactory = null,
  CancellationToken cancellationToken = default
) {
  var agentOptions = new MqttAgentOptions() {
    Hostname = "my-mqtt-service.local:1883",
    ClientId = "MY_CLIENT_ID"
  };
  var agent = new MqttAgent(listener, agentOptions, new MqttFactory(), loggerFactory?.CreateLogger<MqttAgent>());
  await agent.RunAsync(cancellationToken);
}

Publishing Samples to Azure Event Hubs

The NRuuviTag.AzureEventHubs.Agent NuGet package (source) can be used to observe RuuviTag broadcasts and forward the samples to an Azure Event Hub:

public async Task AzureEventHubAgent(
  IRuuviTagListener listener,
  ILoggerFactory? loggerFactory = null,
  CancellationToken cancellationToken = default
) {
  var agentOptions = new AzureEventHubAgentOptions() {
    ConnectionString = "Endpoint=sb://MY_NAMESPACE.servicebus.windows.net/;SharedAccessKeyName=MY_KEY_NAME;SharedAccessKey=MY_KEY",
    EventHubName = "MY_EVENT_HUB"
  };
  var agent = new AzureEventHubAgent(listener, agentOptions, loggerFactory?.CreateLogger<AzureEventHubAgent>());
  await agent.RunAsync(cancellationToken);
}

Command-Line Application

nruuvitag is a command-line tool for Windows and Linux that can scan for nearby RuuviTags, and publish device readings to the console, or to an MQTT server or Azure Event Hub.

Add --help to any command to view help.

Examples:

# Scan for nearby devices

nruuvitag devices scan

# Write sensor readings from all nearby devices to the console

nruuvitag publish console

# Add a device to the known devices list

nruuvitag devices add "AB:CD:EF:01:23:45" --id "bedroom-1" --name "Master Bedroom"

# Publish readings from known devices to an MQTT server

nruuvitag publish mqtt my-mqtt-service.local:1883 --client-id "MY_CLIENT_ID" --topic "{clientId}/my-ruuvi-tags/{deviceId}" --known-devices

# Publish readings from nearby devices to an Azure Event Hub in batches of up to 100 samples

nruuvitag publish az "MY_CONNECTION_STRING" "MY_EVENT_HUB" --batch-size-limit 100

Linux Service

The command-line application can be run as a Linux service using systemd. See here for details.

Linux Container Image

The command-line application can be run as a Linux container image. See here for details. Note that the container runs as the root user to allow BlueZ to access the Bluetooth adapter.

Building the Solution

The repository uses Cake for cross-platform build automation. The build script allows for metadata such as a build counter to be specified when called by a continuous integration system such as TeamCity.

A build can be run from the command line using the build.ps1 PowerShell script or the build.sh Bash script. For documentation about the available build script parameters, see build.cake.