Sonata REST API Documentation

---

Base URL

The base URL for the REST API is: https://sonata.twist-innovation.com

---

Board identification

Every board has a unique installation_id and device_id.

Each installation has one gateway, which is identified by the installation_id. The device_id identifies the device within the installation. These 2 identifiers are required for controlling the matrix.

These IDs are assigned by the manufacturer and are to be found on the device.

Installation ID	Device ID
4 bytes	2 bytes

---

Endpoints

Subscribe

Subscribe to receive context and alive message events. An alive event occures when a device boots up and gets connected with the gateway. A context message event occures when it's state changes.

Request:

Endpoint: /subscribe
Method: POST
Headers: Content-Type: application/json
Body:

{
"url": "https://example.com/receive"
}

Response:

Success Response:
- Code: 200 OK
- Content:

{
  "message": "Subscribed to https://example.com/receive"
}

Error Response:
- Code: 400 Bad Request
- Content:

{
  "error": "URL is required"
}

Example

$> curl -X POST https://sonata.twist-innovation.com/subscribe \
    -H "Content-Type: application/json" \
    -d "{\"url\": \"http://172.19.0.3:5001/receive\"}"
{"message":"Subscribed to http://172.19.0.3:5001/receive"}

---

Unsubscribe

Unsubscribe to receive context and alive message events. An alive event occures when a device boots up and gets connected with the gateway. A context message event occures when it's state changes.

Request:

Endpoint: /unsubscribe
Method: GET

Response:

Success Response:
- Code: 200 OK
- Content:

{
  "message": "Unsubscribed"
}

Example

$> curl -X GET https://sonata.twist-innovation.com/unsubscribe
{"message":"Unsubscribed"}

---

Set Pattern

Set a pattern on LED matrix. The pattern is a list of 100 integers, where each integer represents the brightness of an LED. The brightness value ranges from 0 to 15.

The corner LEDs are not physically present on the hardware, but to ease the pattern creation, they are included in the pattern list. These values will be ignored.

A pattern is not stored int non-volatile memory, so it will be lost when the device is powered off.

Request:

Endpoint: /pattern
Method: POST
Headers: Content-Type: application/json
Body:

{
"installation_id": 123,
"device_id": 456,
"values": [
  1, 1, 1, 1, 1, 1, 1, 1, 1, 1,
  1, 3, 3, 3, 3, 3, 3, 3, 3, 3,
  1, 3, 7, 7, 7, 7, 7, 7, 7, 3,
  1, 3, 7,10,10,10,10,10, 7, 3,
  1, 3, 7,10,15,15,15,10, 7, 3,
  1, 3, 7,10,15,15,15,10, 7, 3,
  1, 3, 7,10,10,10,10,10, 7, 3,
  1, 3, 7, 7, 7, 7, 7, 7, 7, 3,
  1, 3, 3, 3, 3, 3, 3, 3, 3, 3,
  1, 1, 1, 1, 1, 1, 1, 1, 1, 1
]
}

Response:

Success Response:
- Code: 200 OK
- Content:

{
  "message": "Success"
}

Error Responses:
- Code: 400 Bad Request
- Content:

{
  "error": "Values must be an array of 100 integers"
}

• Code: 400 Bad Request
  
• Content:
  

{
  "error": "Missing key: 'key_name'"
}

• Code: 500 Internal Server Error
  
• Content:
  

{
  "error": "Error message"
}

Example

$> curl -X POST https://sonata.twist-innovation.com/pattern \
    -H "Content-Type: application/json" \
    -d "{
          \"installation_id\": 123,
          \"device_id\": 456,
          \"pattern\": [
            0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
            0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
            0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
            0,15, 0, 0, 0, 0, 0, 0, 0, 0,
            0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
            0, 0, 0, 0, 0,15, 0, 0, 0, 0,
            0, 0, 0, 0, 0,15, 0, 0, 0, 0,
            0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
            0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
            0, 0, 0, 0, 0, 0, 0, 0, 0, 0
          ]
        }"
{"message":"Success"}

---

Toggle

Toggle between off state and last on state.

Request

Endpoint: /toggle
Method: POST
Headers: Content-Type: application/json
Body:

{
  \"installation_id\": 123,
  \"device_id\": 456
}

Response:

Success Response:
- Code: 200 OK
- Content:

{
  "message": "Success"
}

Error Responses:
- Code: 400 Bad Request
- Content:

{
  "error": "Missing key: 'key_name'"
}

• Code: 500 Internal Server Error
  
• Content:
  

{
  "error": "Error message"
}

Example

&> curl -X POST https://sonata.twist-innovation.com/toggle \
    -H "Content-Type: application/json" \
    -d "{
          \"installation_id\": 123,
          \"device_id\": 456
        }"
{"message":"Success"}

---

Off

Turn off the matrix. All LEDs in the matrix will be turned off.

Request

Endpoint: /off
Method: POST
Headers: Content-Type: application/json
Body:

{
  "installation_id": 123,
  "device_id": 456
}

Response

Success Response:
- Code: 200 OK
- Content:

{
  "message": "Success"
}

Error Responses
- Code: 400 Bad Request
- Content:

{
  "error": "Missing key: 'key_name'"
}

• Code: 500 Internal Server Error
  
• Content:
  

  {
    "error": "Error message"
  }

Example

  &> curl -X POST https://sonata.twist-innovation.com/off \
      -H "Content-Type: application/json" \
      -d "{
      \"installation_id\": 123,
      \"device_id\": 456
    }"
  {"message":"Success"}

---

Events

Via the /subscribe endpoint, an external URL can subscribe to receive context and alive message events.

Alive is an event that is triggered when a device boots up and connects to the gateway. Context is an event that is triggered when the state of the device changes.

The format of the events is as follows:

{
  "installation_id": <installation_id>,
  "device_id": <device_id>,
  "message_type": "context" | "alive",
  "payload": <original_payload>
}

• Example: Context

"{'type': 'context', 'installation_id': '16', 'device_id': '456', 'payload': {'key': 0, 'cl': [{'i': 0, 'v': 0}, {'i': 1, 'v': 0}, {'i': 2, 'v': 0}, {'i': 3, 'v': 0}, {'i': 4, 'v': [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 15, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 15, 0, 0, 0, 0, 0, 0, 0, 0, 0, 15, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]}]}}"

Index 4 in the cl array contains the matrix pattern.

• Example: Alive

The key information of an alive event are the installation_id and device_id. These identify the device that has just booted up and connected to the gateway.

---

MQTT Configuration

MQTT Broker: sonata.twist-innovation.com The REST API is subscribed to MQTT Topics: 1. v2/+/rx/+/context/+ 2. v2/+/rx/+/alive

REST API Configuration

mqtt:
  broker: sonata.twist-innovation.com
  keepalive: 60
  password: <password>
  port: 1883
  username: <user>
subscription_url: <configurable subscription URL>