CoppelBox Help

Appearance

Examples ​

Sample payloads ​

Relay command (request) and its acknowledgment (response), both on /command:

json
// → /cbox/CBOX-00001/command
{
  "command": "relay",
  "relay_num": 0,
  "state": true
}

The state change itself is confirmed on /status, not /command — a rlyDelta message (or the next heartbeat) will show relays[0] flip to 1.

Command error response (e.g. the relay is configured pulse_only and doesn't accept direct on/off):

json
{
  "deviceId": "CBOX-00001",
  "type": "relay_error",
  "error": "Relay is pulse_only — use pulse_relay command",
  "relay_num": 0
}

Status packet (heartbeat) — see Telemetry → Status packets for the full annotated example and field reference.

Alert (fault and warning) — see Alerts → Alert payload structure for both examples.

Power history sample:

json
{
  "deviceId": "CBOX-00001",
  "type": "powerHistory",
  "ts": 1705329045,
  "int": { "V": 230.5, "I": 2.45, "PkW": 0.56 },
  "ext": { "V": 230.1, "I": 1.23, "PkW": 0.28 }
}

Example subscription flow ​

Option A — subscribing to MQTT directly ​

If you've been provisioned with direct broker credentials (see the note in Authentication & Access), a typical exploratory session with the Mosquitto CLI looks like this:

bash
# Subscribe to every topic for a device, to see the full traffic pattern
mosquitto_sub -h <broker> -t "/cbox/CBOX-00001/#" -v

# In a second terminal: request an immediate status packet
mosquitto_pub -h <broker> -t "/cbox/CBOX-00001/command" \
  -m '{"command":"request_status_packet"}'

# Turn relay 0 on and watch the rlyDelta message arrive on /status
mosquitto_pub -h <broker> -t "/cbox/CBOX-00001/command" \
  -m '{"command":"relay","relay_num":0,"state":true}'

The connection itself requires TLS with a valid client certificate — mosquitto_sub/mosquitto_pub need --cafile, --cert, and --key pointed at your issued certificate and the broker's CA, which are outside the scope of this reference.

This is the supported path for an application-level integration — see Authentication & Access for the credentials model. A minimal JavaScript example using AWS Amplify:

javascript
import { Amplify } from 'aws-amplify';
import { signIn } from 'aws-amplify/auth';
import { generateClient } from 'aws-amplify/api';

// 1. Configure once at startup, using your deployment's Cognito/AppSync values
Amplify.configure({
  Auth: {
    Cognito: {
      userPoolId: '<COGNITO_USER_POOL_ID>',
      userPoolClientId: '<COGNITO_CLIENT_ID>',
      identityPoolId: '<COGNITO_IDENTITY_POOL_ID>',
    }
  }
});

// 2. Sign in
await signIn({ username: 'you@example.com', password: '...' });

// 3. Subscribe to live status updates for a device
const client = generateClient();

const ON_STATUS_UPDATE = /* GraphQL */ `
  subscription OnDeviceStatusUpdate($deviceId: String!) {
    onDeviceStatusUpdate(deviceId: $deviceId) {
      deviceId
      lastSeenISO
      relayStates
      firmwareVersion
      dcPowerOk
      hasAlerts
      ota { received size }
    }
  }
`;

const subscription = client.graphql({
  query: ON_STATUS_UPDATE,
  variables: { deviceId: 'CBOX-F8B3B737B800' }
}).subscribe({
  next: ({ data }) => {
    console.log('Status update:', data.onDeviceStatusUpdate);
  },
  error: (err) => console.error('Subscription error:', err)
});

// When done: subscription.unsubscribe();

Note that relayStates here is an array of Int (1=ON, 0=OFF) — the API mirrors the numeric wire format described in Telemetry, rather than converting it to booleans, for this particular subscription type.