Quickstart

Welcome to Fostrom! This guide will take you through connecting your first device, sending datapoints and messages, and writing actions to supercharge your IoT projects.

We’ll demonstrate how the platform works by setting up a fleet for a small weather station. We’ll add a few packet schemas to monitor and control various aspects of the weather station, and then we’ll connect a few devices. We’ll also write Actions to execute real-world effects.

We’ll monitor the air quality using an air quality sensor which can give us PM2.5 readings, along with a temperature and humidity sensor.

On the device, we’ll write a little bit of code to send a message to Fostrom if the PM2.5 reading exceeds 50, which will trigger an Action. The Action will send a mail to our air purifier to start. We’ll also write some logic to do the reverse (stopping the air purifier). We need to do this for now, as Actions can only be triggered by incoming messages. We’re going to add support for aggregated datapoint triggers soon. After that, you won’t need to write any extra logic code on the device.

We hope this tutorial will give you an idea of how you can incorporate Fostrom into your own projects. If you have any questions or just want to chat with us, feel free to join us on Discord or send us an email.

Let’s get started!

First Steps

To get started, go to the Fostrom Console and login with either email or GitHub. If you choose to login with email, you should receive a 6-digit authentication code on your email shortly.

After signing up or logging in, you’ll see that you need to create an organization. Organization names are globally unique, so avoid names like home or farm. Instead, prefer descriptive names like acme-farms or home-of-the-smiths. You should also add a description to the organization. Organization names can be changed later, so don’t worry about it too much.

You can invite collaborators to the organization to work alongside you. They’ll have access to all the fleets, making it easy to setup and work on IoT projects together. For now, we’ll just continue with the quickstart on our own.

Go ahead and create a new fleet and name it whatever you want. We’ll call ours clean-climate.

Let’s add packet schemas next.

Adding Packet Schemas

We’ll add three packet schemas:

a datapoint for collecting the temperature, humiditiy and PM2.5 readings
an in-bound message for the metrics device to notify when PM2.5 is too high or low enough
an out-bound message for setting the state of the air purifier (on/off).

So go ahead and create the three packet schemas with the following fields:

climate-metrics: Datapoint

temperature: decimal
humidity: u8
pm25: u16

air-quality-alert: Inbound Message
```
dirty: boolean
```
air-purifier-set-state: Outbound Message
```
state: boolean
```

Next, let’s add the two devices.

Adding Devices

Create two devices in the Devices tab in the Fostrom Console:

climate-monitor
air-purifier

You can add a description and tags to devices too.

When you open a device in the Console, you’ll see a Connection button. Clicking that button will show you the credentials to connect the device to Fostrom. We’ll use that in the step below when we setup the physical devices.

Before we connect and deploy the physical devices, let’s write the Action.

Writing an Action

Head over to the Actions tab and create a new Action.

We’ll name the action control-air-purifier. Choose the air-quality-alert packet schema (the inbound message you created in the previous step) as the trigger and create the Action.

On the action’s page, you can write JavaScript code, and simulate the behaviour of the Action by selecting a device, and either using a randomized payload or setting your own payload. You can then test the code, and if it succeeds, you can deploy it.

We’ll put the following code in the Action:

// Set the correct state for the air purifier
let state = false
if (pl.dirty) { state = true }

// Send Mail
fostrom.sendMail(<air-purifier>, <air-purifier-set-state>, {
  state: state
})

As you write this action, you’ll see auto-complete suggestions appear for the device and packet schema. You need to choose from the list to ensure the code is valid.

You can even create a webhook in the Settings tab of your Fleet, and then add a line to the above code to send a webhook when the alert triggers using the fostrom.triggerWebhook() function.

Before you can deploy the action, you need to select a Device on the right hand panel, and test the action. Choose the climate-monitor device and click on Test Action. Once it succeeds, you can then deploy it by clicking Deploy Action.

Now that our action is setup, we can go ahead and get real devices to connect to Fostrom, and start sending the datapoint and the alert message from the climate-monitor device, and receive mail to control the state of the air-purifier device.

Connecting to Fostrom

Up until this step, everything we did was on the Fostrom Console. Now, we’ll need to write some code and deploy to real-world devices.

You can use any device that runs either Linux or macOS. On macOS, we support both Intel-based and Apple Silicon Macs. For Linux, we support ARM64, AMD64, ARMv6, and RISCV64. That means you can use nearly any single-board computer manufactured in the past few years, from the still widely used Raspberry Pi Zero to RISC-V based devices such as the MilkV Duo, including Raspberry Pis and Intel/AMD based computers or servers.

We’ll use two Raspberry Pis for this example. Get your Pis setup according to their official documentation and get them connected to the internet. Once you can SSH into them, we can continue by writing a program which will connect to Fostrom and send our hypothetical data.

We’ll write a Python program on the climate-monitor device and a Node.js program on the air-purifier device. You can also instead use our robust Elixir SDK if you wish.

Code for the `air-purifier`

Let’s setup the air-purifier first.

Create a new directory on your Pi and install the Fostrom Device SDK for JavaScript:

# Create the directory
mkdir air-purifier && cd air-purifier

# Install the node module
npm install fostrom

In the code below, you need to replace the fleet_id, device_id, and device_secret from the air-purifier device’s Connection Credentials. Once you do that, you can write this code to a file on your Pi, and save it as index.js in the same directory.

import Fostrom from 'fostrom';

const fostrom = new Fostrom({
  fleet_id: "<fleet-id>",
  device_id: "<device-id>",
  device_secret: "<device-secret>",
})

// Setup the onMail handler, to process incoming mail.
fostrom.onMail = async (mail) => {
  if (mail.name === 'air-purifier-set-state') {
    if (mail.payload.state === true) {
      startAirPurifier()
    } else {
      stopAirPurifier()
    }
  }

  await mail.ack()
}

function startAirPurifier() {
  // implement starting the air purifier
  // perhaps using the GPIO pins to signal
  console.log('starting the air purifier...')
}

function stopAirPurifier() {
  // implement stopping the air purifier
  // perhaps using the GPIO pins to signal
  console.log('stopping the air purifier...')
}

// Start the async event loop and connect to Fostrom
(async function() { await fostrom.connect() })()

Now we can start the program:

node index.js

The program should start, and connect to Fostrom. If everything worked correctly, you’ll be able to see that the air-purifier device is now online in your Fleet’s Devices tab.

You can also use Bun instead of Node.js too.

To keep the code running across restarts you can use a process manager or systemd service definitions.

Code for the `climate-monitor`

Finally, we can write the code for the climate-monitor and complete the chain.

Create a new directory on your other Pi and install the Fostrom Device SDK for Python. We’ll use uv here as uv makes it very straightforward to manage Python environments and dependencies.

# Create the directory
mkdir climate-monitor && cd climate-monitor

# Initialize uv
uv venv
source .venv/bin/activate

# Install the Python package
uv pip install fostrom

In the code below, you need to replace the fleet_id, device_id, and device_secret from the climate-monitor device’s Connection Credentials. Once you do that, you can write this code to a file on your Pi, and save it as main.py in the same directory.

from fostrom import Fostrom
import time

# Create SDK instance
fostrom = Fostrom({
    "fleet_id": "<fleet-id>",
    "device_id": "<device-id>",
    "device_secret": "<device-secret>",
})

# Connect to Fostrom
fostrom.connect()

# Let's assume there's a function to read the climate metrics
def read_sensors():
    # Read values for real sensors here...
    return {'temperature': 25.3, 'humidity': 70, 'pm25': 35}

while True:
    readings = read_sensors()

    fostrom.send_datapoint("climate-metrics", readings)

    if readings.pm25 > 50:
        # Send a message to start the air-purifier
        fostrom.send_msg("air-quality-alert", {'dirty': True})

    if readings.pm25 < 25:
        # Send a message to stop the air-purifier
        fostrom.send_msg("air-quality-alert", {'dirty': False})

    # Sleep for 60 seconds and loop
    time.sleep(60000)

Now we can start the program:

uv run main.py

The program should start, and connect to Fostrom. If everything worked correctly, you’ll be able to see that the climate-control device is now online in your Fleet’s Devices tab.

As before, to keep the code running across restarts you can use a process manager or systemd service definitions.

Conclusion

Now that both the devices are connected and working, the weather station is complete. You are now able to send datapoints to continously track the climate, along with sending messages when the air gets too dirty or becomes clean enough once again from the climate-monitor device, along with starting and stopping the air purifier using code running on the air-purifier device.

This tutorial was a small example of Fostrom’s capabilities, but you can build much more complex fleets with structured packet schemas and powerful actions, and rest easy that incoming and outgoing data is conforming to pre-defined structures and values.

We want to make Fostrom the best developer experience when it comes to IoT devices. We’re already working on a few ways to make it even easier for you, including adding action triggers on aggregates, removing the need to send messages from the climate-monitor device, for such simple use-cases, along with automatic monitoring of the host device’s telemetry such as its CPU and memory consumption. Please share your feedback with us. We’re happy to help you setup your IoT projects too, just contact us.