SPAN

SPAN eBus MQTT API

Publish/subscribe streaming API hosted on SPAN Panel using the Electrification Bus (eBus) integration framework and the Homie Convention. SPAN Panel hosts an MQTT broker accessible over MQTTS (8883), WS, and WSS. Clients subscribe to `ebus/5//...` topics to receive real-time panel state, per-circuit telemetry, energy storage state, and SPAN Drive integration data, and publish to `/set` topics to operate relays and control panel state. The broker enforces topic-level ACLs — full read access on `ebus/#`, write access limited to Homie `/set` control topics and to non-panel device subtrees under `ebus/5/`. Credentials are obtained via the REST authentication endpoint.

SPAN eBus MQTT API is one of 2 APIs that SPAN publishes on the APIs.io network, described by an AsyncAPI event-driven specification.

This API exposes 1 machine-runnable capability that can be deployed as REST, MCP, or Agent Skill surfaces via Naftiko and 1 JSON Schema definition.

Tagged areas include MQTT, Homie, Electrification Bus, eBus, and Pub/Sub. The published artifact set on APIs.io includes API documentation, an AsyncAPI specification, 1 Naftiko capability spec, and 1 JSON Schema.

Documentation GitHub

AsyncAPI Specification

asyncapi: 2.6.0
info:
  title: SPAN eBus MQTT API
  version: r202615
  description: |
    Publish/subscribe streaming API hosted directly on SPAN Panel using the
    Electrification Bus (eBus) integration framework and the Homie Convention
    for MQTT topic and payload structure. SPAN Panel hosts an MQTT broker
    available over MQTTS (TLS), WS, and WSS exclusively on the home LAN.

    Topic structure follows the Homie pattern `ebus/5/<device-id>/<node-id>/<property-id>`
    where device-id is the SPAN Panel serial number. Clients can read all
    `ebus/#` topics and publish to Homie `/set` topics to control panel state.
  license:
    name: MIT-0
    url: https://github.com/spanio/SPAN-API-Client-Docs/blob/main/LICENSE
  contact:
    name: SPAN API GitHub Discussions
    url: https://github.com/spanio/SPAN-API-Client-Docs/discussions
servers:
  panel-mqtts:
    url: span-{serialNumber}.local:8883
    protocol: mqtts
    description: SPAN Panel MQTT broker over TLS (preferred for native MQTT clients).
    variables:
      serialNumber:
        description: The SPAN Panel serial number (e.g. ab-1234-c5d67).
        default: ab-1234-c5d67
    security:
      - userPassword: []
  panel-wss:
    url: span-{serialNumber}.local:8884
    protocol: wss
    description: SPAN Panel MQTT broker over Secure WebSockets (for browser-based clients).
    variables:
      serialNumber:
        description: The SPAN Panel serial number.
        default: ab-1234-c5d67
    security:
      - userPassword: []
defaultContentType: application/json
channels:
  ebus/5/{serial}/$state:
    description: Homie device lifecycle state for the SPAN Panel.
    parameters:
      serial:
        $ref: '#/components/parameters/serial'
    subscribe:
      operationId: subscribePanelState
      summary: Subscribe to SPAN Panel Homie lifecycle state.
      message:
        $ref: '#/components/messages/HomieState'
  ebus/5/{serial}/$description:
    description: Homie device description (full panel + node + property schema).
    parameters:
      serial:
        $ref: '#/components/parameters/serial'
    subscribe:
      operationId: subscribePanelDescription
      summary: Subscribe to the panel's Homie $description schema.
      message:
        $ref: '#/components/messages/HomieDescription'
  ebus/5/{serial}/panel/power:
    description: Real-time whole-home power telemetry from the panel.
    parameters:
      serial:
        $ref: '#/components/parameters/serial'
    subscribe:
      operationId: subscribePanelPower
      summary: Stream real-time whole-home power values.
      message:
        $ref: '#/components/messages/PanelPower'
  ebus/5/{serial}/panel/meter:
    description: Real-time main meter energy register values.
    parameters:
      serial:
        $ref: '#/components/parameters/serial'
    subscribe:
      operationId: subscribePanelMeter
      summary: Stream main meter cumulative energy registers.
      message:
        $ref: '#/components/messages/PanelMeter'
  ebus/5/{serial}/panel/grid:
    description: Main grid relay state.
    parameters:
      serial:
        $ref: '#/components/parameters/serial'
    subscribe:
      operationId: subscribeGridState
      summary: Stream grid / main relay state changes.
      message:
        $ref: '#/components/messages/RelayState'
  ebus/5/{serial}/panel/grid/set:
    description: Control topic to set the main grid relay state (open or closed).
    parameters:
      serial:
        $ref: '#/components/parameters/serial'
    publish:
      operationId: setGridState
      summary: Publish a desired grid relay state.
      message:
        $ref: '#/components/messages/RelayStateSet'
  ebus/5/{serial}/panel/islanding-state:
    description: Whole-home islanding state — grid-tied vs islanded operation.
    parameters:
      serial:
        $ref: '#/components/parameters/serial'
    subscribe:
      operationId: subscribeIslandingState
      summary: Stream islanding state transitions.
      message:
        $ref: '#/components/messages/IslandingState'
  ebus/5/{serial}/circuits/{circuitId}/power:
    description: Per-circuit real-time power telemetry.
    parameters:
      serial:
        $ref: '#/components/parameters/serial'
      circuitId:
        description: Opaque circuit identifier.
        schema:
          type: string
    subscribe:
      operationId: subscribeCircuitPower
      summary: Stream per-circuit real-time power.
      message:
        $ref: '#/components/messages/CircuitPower'
  ebus/5/{serial}/circuits/{circuitId}/relay-state:
    description: Per-circuit relay state.
    parameters:
      serial:
        $ref: '#/components/parameters/serial'
      circuitId:
        schema:
          type: string
    subscribe:
      operationId: subscribeCircuitRelayState
      summary: Stream per-circuit relay state changes.
      message:
        $ref: '#/components/messages/RelayState'
  ebus/5/{serial}/circuits/{circuitId}/relay-state/set:
    description: Control topic to set a per-circuit relay state.
    parameters:
      serial:
        $ref: '#/components/parameters/serial'
      circuitId:
        schema:
          type: string
    publish:
      operationId: setCircuitRelayState
      summary: Publish a desired per-circuit relay state.
      message:
        $ref: '#/components/messages/RelayStateSet'
  ebus/5/{serial}/storage/soe:
    description: Energy storage state-of-energy (battery percentage).
    parameters:
      serial:
        $ref: '#/components/parameters/serial'
    subscribe:
      operationId: subscribeStorageSoe
      summary: Stream energy storage state-of-energy updates.
      message:
        $ref: '#/components/messages/StateOfEnergy'
components:
  parameters:
    serial:
      description: The SPAN Panel serial number (Homie device-id).
      schema:
        type: string
        pattern: '^[a-z0-9-]+$'
  messages:
    HomieState:
      name: HomieState
      title: Homie Device Lifecycle State
      contentType: text/plain
      payload:
        type: string
        enum: [init, ready, disconnected, sleeping, lost, alert]
    HomieDescription:
      name: HomieDescription
      title: Homie $description schema for the device
      payload:
        $ref: 'https://homieiot.github.io/specification/#device-attributes'
    PanelPower:
      name: PanelPower
      title: Panel Power
      payload:
        type: object
        properties:
          instantGridPowerW:
            type: number
          feedthroughPowerW:
            type: number
    PanelMeter:
      name: PanelMeter
      title: Panel Meter Energy Registers
      payload:
        type: object
        properties:
          producedEnergyWh:
            type: number
          consumedEnergyWh:
            type: number
    RelayState:
      name: RelayState
      title: Relay State
      payload:
        type: string
        enum: [OPEN, CLOSED, UNKNOWN]
    RelayStateSet:
      name: RelayStateSet
      title: Relay State (set)
      payload:
        type: string
        enum: [OPEN, CLOSED]
    IslandingState:
      name: IslandingState
      title: Islanding State
      payload:
        type: string
        enum: [GRID_TIED, ISLANDED, TRANSITIONING, UNKNOWN]
    CircuitPower:
      name: CircuitPower
      title: Circuit Power
      payload:
        type: object
        properties:
          instantPowerW:
            type: number
          producedEnergyWh:
            type: number
          consumedEnergyWh:
            type: number
    StateOfEnergy:
      name: StateOfEnergy
      title: State of Energy
      payload:
        type: object
        properties:
          percentage:
            type: number
            minimum: 0
            maximum: 100
  securitySchemes:
    userPassword:
      type: userPassword
      description: >-
        MQTT broker authentication. Username is the SPAN Panel serial number,
        password is the broker passphrase returned by the REST authentication
        endpoint `POST /api/v1/auth/register`.

SPAN eBus MQTT API

Documentation

Specifications

Schemas & Data

Other Resources

AsyncAPI Specification