Integration Guides

RosFit is designed to work with your existing infrastructure. These guides cover integrating with popular MQTT brokers, monitoring tools, notification services, and CI/CD pipelines.

AWS IoT Core setup

Use AWS IoT Core as your MQTT broker for global-scale device connectivity with built-in security and device management.

When to use: You need a fully managed broker with automatic scaling, global endpoints, and AWS ecosystem integration (Lambda, S3, CloudWatch).

Setup steps:

Create an IoT Thing for each RosFit device in the AWS Console or via the CLI:

aws iot create-thing --thing-name bot-01

Generate certificates and attach a policy:

aws iot create-keys-and-certificate --set-as-active \
  --certificate-pem-outfile bot-01.crt \
  --public-key-outfile bot-01.pub \
  --private-key-outfile bot-01.key

aws iot attach-policy --policy-name RosFitDevicePolicy --target <certificate-arn>
aws iot attach-thing-principal --thing-name bot-01 --principal <certificate-arn>

Configure environment variables:

ROSFIT_AWS_IOT_ENDPOINT=a1b2c3-ats.iot.us-east-1.amazonaws.com
ROSFIT_AWS_REGION=us-east-1

Update bridge config to use TLS with the AWS certificates:

connection:
  provider: rosfit-cloud
  host: a1b2c3-ats.iot.us-east-1.amazonaws.com
  port: 8883
  transport: tcp
  tls:
    enabled: true
    ca_cert: /etc/rosfit/certs/AmazonRootCA1.pem
    client_cert: /etc/rosfit/certs/bot-01.crt
    client_key: /etc/rosfit/certs/bot-01.key
  auth:
    method: certificate

IoT Core policy example:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["iot:Connect"],
      "Resource": "arn:aws:iot:us-east-1:123456789012:client/${iot:ClientId}"
    },
    {
      "Effect": "Allow",
      "Action": ["iot:Publish", "iot:Subscribe", "iot:Receive"],
      "Resource": "arn:aws:iot:us-east-1:123456789012:topicfilter/rosfit/${iot:ClientId}/*"
    }
  ]
}

EMQX broker setup

EMQX is the default broker bundled with RosFit. This guide covers production-hardening your EMQX deployment.

Production checklist:

Setting	Development	Production
Authentication	Token (plaintext)	X.509 mTLS + JWT
TLS	Disabled	Enabled on port 8883
ACLs	Allow all	Topic-level per device
Dashboard	Enabled (18083)	Disabled or firewalled
Clustering	Single node	3-node cluster
Persistence	In-memory	RocksDB backend

Enable TLS in emqx.conf:

listeners.ssl.default {
  bind = "0.0.0.0:8883"
  ssl_options {
    certfile = "/etc/emqx/certs/server.crt"
    keyfile = "/etc/emqx/certs/server.key"
    cacertfile = "/etc/emqx/certs/ca.crt"
    verify = verify_peer
    fail_if_no_peer_cert = true
  }
}

Configure ACLs so each device can only access its own topic namespace:

{allow, {username, "bot-01"}, publish, ["rosfit/bot-01/#"]}.
{allow, {username, "bot-01"}, subscribe, ["rosfit/bot-01/#"]}.
{deny, all}.

Mosquitto setup

Use Eclipse Mosquitto as a lightweight alternative broker for smaller deployments or edge installations.

When to use: Single-site deployments with fewer than 50 devices where resource footprint matters.

Install and configure:

sudo apt install mosquitto mosquitto-clients

/etc/mosquitto/conf.d/rosfit.conf:

listener 1883 0.0.0.0
allow_anonymous false
password_file /etc/mosquitto/passwd

listener 8883 0.0.0.0
certfile /etc/mosquitto/certs/server.crt
keyfile /etc/mosquitto/certs/server.key
cafile /etc/mosquitto/certs/ca.crt
require_certificate true

listener 8083 0.0.0.0
protocol websockets

Create device credentials:

sudo mosquitto_passwd -b /etc/mosquitto/passwd bot-01 <password>
sudo systemctl restart mosquitto

Update RosFit environment variables to point to your Mosquitto broker:

ROSFIT_MQTT_URL=mqtt://mosquitto:1883
ROSFIT_MQTT_USER=rosfit_service
ROSFIT_MQTT_PASS=<service_password>

Grafana dashboards

Connect Grafana to TimescaleDB for advanced telemetry visualization alongside the RosFit dashboard.

When to use: You want custom analytics dashboards, long-term trend analysis, or integration with existing Grafana infrastructure.

Setup steps:

Add TimescaleDB as a data source in Grafana (PostgreSQL driver):

Field	Value
Host	`timescaledb:5432`
Database	`rosfit`
User	`rosfit`
TLS	Require (production)

Import the RosFit dashboard template:

curl -O https://raw.githubusercontent.com/rosfit/rosfit/main/grafana/dashboards/fleet-overview.json

Example query for battery history:

SELECT
  time_bucket('5 minutes', timestamp) AS time,
  device_id,
  avg(data->>'battery_percent')::float AS battery
FROM telemetry
WHERE device_id = 'dev_k8m2n4'
  AND timestamp > now() - interval '24 hours'
GROUP BY time, device_id
ORDER BY time;

Included dashboard panels: fleet health heatmap, per-device battery timeline, command success rate, telemetry throughput, error rate by device type.

Slack and Discord alerts

Route RosFit alerts to Slack or Discord channels for team-wide visibility.

Slack

Create a Slack webhook at api.slack.com/messaging/webhooks
Configure in RosFit via Settings > Alerts > Notification Channels > Add Slack:

Field	Value
Webhook URL	`https://hooks.slack.com/services/T.../B.../xxx`
Channel	`#robot-alerts`
Severity filter	`warning`, `critical`

Alert messages include the device name, alert type, current value, threshold, and a direct link to the device detail page.

Discord

Create a Discord webhook in channel settings > Integrations > Webhooks
Configure in RosFit via Settings > Alerts > Notification Channels > Add Discord

The payload format is the same as Slack (RosFit automatically adapts the formatting).

Custom webhook

For PagerDuty, Opsgenie, or any HTTP endpoint:

{
  "url": "https://events.pagerduty.com/v2/enqueue",
  "method": "POST",
  "headers": {
    "Content-Type": "application/json"
  },
  "template": {
    "routing_key": "<your-integration-key>",
    "event_action": "trigger",
    "payload": {
      "summary": "{{alert.message}}",
      "severity": "{{alert.severity}}",
      "source": "rosfit/{{device.id}}"
    }
  }
}

GitHub Actions CI/CD

Automate firmware builds, integration tests, and deployments with GitHub Actions.

Example workflow (.github/workflows/deploy.yml):

name: Build and Deploy Firmware

on:
  push:
    tags:
      - 'v*'

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Build firmware
        run: |
          pip install platformio
          pio run -e esp32

      - name: Upload to RosFit
        env:
          ROSFIT_API_URL: ${{ secrets.ROSFIT_API_URL }}
          ROSFIT_API_KEY: ${{ secrets.ROSFIT_API_KEY }}
        run: |
          pip install rosfit-cli
          rosfit config set api_url $ROSFIT_API_URL
          rosfit config set api_key $ROSFIT_API_KEY
          rosfit deploy .pio/build/esp32/firmware.bin \
            --version ${{ github.ref_name }} \
            --target greenhouse-sensors \
            --strategy canary \
            --rollback-on-failure

  test:
    runs-on: ubuntu-latest
    services:
      emqx:
        image: emqx/emqx:5.4
        ports:
          - 1883:1883
    steps:
      - uses: actions/checkout@v4

      - name: Start RosFit stack
        run: docker compose -f docker-compose.test.yml up -d

      - name: Run integration tests
        run: |
          pip install pytest rosfit
          pytest tests/integration/ -v

Troubleshooting guide