SmartClaws Producer

Publish IoT sensor data to the SKALE blockchain using the SmartClaws protocol. This skill handles the full producer pipeline: installing the CLI, initializing a wallet, registering devices, writing sensor-reading scripts, and publishing data on-chain.

Real Hardware Rule

When the user asks to set up a sensor or publish real-world measurements, assume they mean a real hardware device unless they explicitly say they want a simulation, mock, or pipeline test.

Before writing any publisher script, first determine:

• the exact sensor model / part number
• how it connects to the host (BLE, USB serial, Wi-Fi, MQTT, GPIO/I2C/SPI, etc.)
• whether pairing or driver setup is required
• what library, CLI, or protocol is needed to read the sensor

If the exact sensor model or connection method is unknown, ask the user before proceeding.

Do not generate fake/mock sensor data for a real setup request.

Only use a mock publisher when the user explicitly requests testing, simulation, or pipeline validation without real hardware.

Installation

Check if the CLI is available:

smartclaws --version

If not installed, download the binary for the current platform:

PLATFORM="$(uname -s | tr '[:upper:]' '[:lower:]')-$(uname -m | sed 's/aarch64/arm64/')"
curl -fL -o /usr/local/bin/smartclaws \
  "https://github.com/skalenetwork/smartclaws/releases/latest/download/smartclaws-${PLATFORM}"
chmod +x /usr/local/bin/smartclaws

If /usr/local/bin requires root, use ~/.local/bin/smartclaws instead and ensure it's on PATH.

Verify: smartclaws --version should print the version number.

Setup

1. Initialize

smartclaws init

This creates ~/.smartclaws/ with config and a wallet. Expected output:

Config created at ~/.smartclaws/config.json
  Network:   SKALE Sandbox
  RPC URL:   https://base-sepolia-testnet.skalenodes.com/v1/vigilant-snappy-arcturus
  Chain ID:  196243392
  Contract:  0x18B62f70ddaA2666FA5933a7b6Ff3943e69ca690
  Wallet:    0xAbC123... (generated)

If config already exists, it prints the current config without overwriting.

2. Show wallet address and fund it

After init, show the wallet address to the user:

smartclaws wallet info

Expected output:

Address: 0xAbC123...
Balance: 0 sFUEL

Important: The user must fund this wallet with sFUEL before proceeding. Show the wallet address to the user and ask them to fund it (e.g., via the SKALE faucet or by transferring sFUEL from another wallet). Registration and publishing will fail without sFUEL.

Wait for the user to confirm the wallet is funded, then verify:

smartclaws wallet info

The balance should now be greater than 0.

3. Register device group

smartclaws register

Creates a device group on-chain (one per machine). Requires a funded wallet. Expected output:

Registering device group 'swift-falcon'...
Device group registered:
  Name:     swift-falcon
  Address:  0xDEF456...
  Tx:       0x789...

This only needs to run once. Subsequent calls fail with: Device group already registered: 0x...

3. Check wallet

smartclaws wallet info

Shows wallet address and sFUEL balance. SKALE testnet transactions are zero-gas, but a small sFUEL balance is needed.

Device Registration

Register a device to get dedicated on-chain channels:

smartclaws device register --name <device-name>

Choose a descriptive name (e.g., temp-sensor, humidity-monitor). Expected output:

Registering device 'temp-sensor'...
Device registered:
  Name:      temp-sensor
  Contract:  0x111...
  Outgoing:  0x222...
  Incoming:  0x333...
  Tx:        0x444...

Important: Save the Outgoing channel address. The reader on another machine will need it to access this device's data.

List registered devices: smartclaws device list

Writing Sensor Scripts

Before writing a publisher script:

1. Identify the exact sensor model and connection type.
2. If the model or protocol is missing, ask the user.
3. Look up the sensor's pairing / reading instructions.
4. Determine the required Python package, system dependency, permissions, and read method.
5. Only then write a hardware-specific publisher script.

Never substitute mock data unless the user explicitly asks for a simulation or test publisher.

When the user has provided their sensor details, write a Python script that:

1. Imports the appropriate sensor library (install with pip if needed)
2. Reads sensor data in a function
3. Calls smartclaws publish via subprocess in a loop
4. Handles errors with retry logic

Save scripts to ~/.smartclaws/scripts/-publisher.py.

Script Structure

Every publisher script follows this pattern:

#!/usr/bin/env python3
"""Publish <sensor-type> readings to SmartClaws."""

import json
import subprocess
import sys
import time

SMARTCLAWS = "smartclaws"
DEVICE = "<device-name>"
TOPIC = "<topic>"
INTERVAL = 30  # seconds


def read_sensor():
    """Read sensor and return payload dict."""
    # --- sensor-specific code here ---
    return {"temp": 22.5, "humidity": 55}


def publish(payload):
    result = subprocess.run(
        [SMARTCLAWS, "publish", "--device", DEVICE, "--topic", TOPIC,
         "--data", json.dumps(payload)],
        capture_output=True, text=True,
    )
    if result.returncode != 0:
        print(f"publish error: {result.stderr.strip()}", file=sys.stderr)
        return False
    return True


def main():
    print(f"Publishing {TOPIC} every {INTERVAL}s for device '{DEVICE}'")
    while True:
        try:
            payload = read_sensor()
            publish(payload)
            print(f"  {payload}")
        except Exception as e:
            print(f"read error: {e}", file=sys.stderr)
        time.sleep(INTERVAL)


if __name__ == "__main__":
    main()

Example: BLE Temperature Sensor (Xiaomi LYWSD03MMC)

Requires: pip install bleak

The read\_sensor function uses BLE GATT characteristic ebe0ccc1-7a0a-4b0c-8a1a-6ff2997da3a6. The data bytes decode as:

• bytes 0-1: temperature (little-endian signed int16, divide by 100)
• byte 2: humidity (uint8, percentage)
• bytes 3-4: voltage (little-endian uint16, divide by 1000)

See the full working example at examples/ble-publisher.py bundled with this skill.

If the User Says "Set Up a Temperature Sensor"

Do not assume a mock sensor. Ask a short clarifying question such as:

• "What's the exact sensor model?"
• "How does it connect to this machine: BLE, USB, Wi-Fi, or GPIO/I2C?"

Only after receiving the hardware details should you write the publisher script.

If the user explicitly says they want a mock/test/simulated sensor, then use the mock publisher above.

Common Mistake to Avoid

Wrong: User asks to set up a real sensor, and the agent immediately creates a fake/mock publisher with simulated data.

Right: Ask for the sensor model and connection method first, then write a hardware-specific publisher.

Publishing Data

Single publish command:

smartclaws publish --device <name> --topic <topic> --data '{"temp": 22.5}'

Expected output:

Published to temp-sensor/temperature
  Tx:     0x555...
  Status: success

Every message is wrapped in a SmartClaws envelope:

{
  "v": 1,
  "ts": 1711324800,
  "dev": "temp-sensor",
  "topic": "temperature",
  "p": {"temp": 22.5}
}

The CLI handles envelope encoding, wallet signing, and on-chain submission automatically.

Running as a Service

For persistent publishing, create a systemd user service:

mkdir -p ~/.config/systemd/user

cat > ~/.config/systemd/user/smartclaws-<device-name>.service << 'EOF'
[Unit]
Description=SmartClaws publisher for <device-name>

[Service]
ExecStart=/usr/bin/python3 %h/.smartclaws/scripts/<device-name>-publisher.py
Restart=on-failure
RestartSec=10

[Install]
WantedBy=default.target
EOF

systemctl --user daemon-reload
systemctl --user enable --now smartclaws-<device-name>

Check status: systemctl --user status smartclaws-

View logs: journalctl --user -u smartclaws- -f

Stop: systemctl --user stop smartclaws-

Common Errors