• Introduction
  • Examples
• API Access
  • HELLA API Server
  • Local Access
    • Address Resolution using mDNS
    • Local TLS Peer Verification
• Access Control
  • Access Control using the HELLA API Server
  • Access Control using Local API Access
  • Revoke API access
• API Description
  • General Concepts
    • API Versions
    • Base URL
    • Device Properties and Actions
      • Numeric Properties
      • Enumeration Properties
      • Actions
    • Property Animations
    • Device Commands and Command Priorities
      • Command Priority
      • Command Attributes
  • API Endpoints
    • Clock and Timezone Information
    • List all devices
    • List all groups
      • Device Details
      • Group Details
    • Device Command
    • Cancel Device Command
    • Send Group Command
    • Delete Group Command
    • Event Stream
• Device Properties and Actions
  • Motor Controllers
  • Lights
  • Weather Stations

ONYX is a specialized home automation system developed by HELLA Sonnen- und Wetterschutztechnik GmbH. It controls an array of shading products such as awnings, venetian blinds, raffstores and pergolas.

The system consists of the following main components:

• ONYX.CENTER is the central hub of the system
• ONYX.NODE, ONYX.CONNECTOR and ONYX.LED control the motors and lights in the shading products
• ONYX.MOTOR is a specialized motor for rollershutters with ONYX built-in
• ONYX.WEATHER provides environmental data such as wind speed, temperature and brightness
• ONYX.CLICK is a tiny handheld remote control for the system

ONYX provides a public API which can be used to query the state of the individual devices and to control them by sending control commands. This document describes the API and how to use it.

The examples in this document use the curl utility to call the API and the json_pp utility to format the returned output for better readability. All examples have been tested using the bash shell on Linux and macOS with curl version 7.x. If you are using a different shell or operating system you may need to adjust the syntax accordingly.

For simplicity the examples all use the HELLA API server. If you are using local API access, you need to replace the base URL of each request with the mDNS Hostname of your ONYX.CENTER in your local network.

The API can be invoked by sending JSON commands via HTTPS to a HELLA operated relay server or directly to an ONYX.CENTER in the local network.

To access the latest version of the API, make sure to install the most recent update on your ONYX.CENTER via the ONYX App which is available for Android and iOS.

If your ONYX.CENTER is connected to the internet, the recommended way to access the API is via the HELLA API server at https://api.hella.link. The server is operated by HELLA, located in the EU and only acts as a relay. All commands are forwarded directly to the individual ONYX.CENTERs and are not modified in transit.

HELLA provides the API service free of charge and without restrictions. We do not provide any uptime or performance guarantees.

Starting with ONYX.CENTER firmware version 2.4 and API version 3 we also support direct, local access to the API. Local API access is available even when ONYX.CENTER can't connect to the internet but has the drawback that TLS peer verification and address resolution is more complex.

ONYX uses mDNS/DNS-SD aka Bonjour to reliably connect to ONYX.CENTER even when the assigned IP address changes over time. Its important that you do not use fixed IP addresses when connecting to the local ONYX API and make sure that the host name is always resolved via mDNS.

In the following example we use avahi-browse on Debian Linux to search for an ONYX.CENTER on the local network and then use the discovered hostname to query its supported API versions with curl using nss-mdns:

> avahi-browse -d local _https._tcp. -t --resolve
+   eno1 IPv6 b381b2fc691ebbbce2a681b22d493e4ddcccaef58738f0caca4e9f61 Secure Web =   eno1 IPv4 b381b2fc691ebbbce2a681b22d493e4ddcccaef58738f0caca4e9f61 Secure Web Site      local
   hostname = [ONYX-CENTER-C0-00-01-5e.local]
   address = [192.168.32.16]
   port = [443]
   txt = ["hardware_version=1.0.0" "name=ONYX.CENTER"]

> curl -k https://ONYX-CENTER-C0-00-00-03.local./api/versions
{"versions":["v1","v2","v3"]}

For local API access its unfortunately not possible to verify the TLS certificate of ONYX.CENTER normally. For test purposes you can use the -k flag of curl to skip verification of the certificate completely.

If you are implementing a commercial product that integrates with ONYX we recommend that you make use of certificate pinning after the first successful connection to protect against man-in-the-middle attacks.

To use the API, client applications need the fingerprint of the ONYX.CENTER and an API access token. The steps to obtain the access token differ slightly between the HELLA API server and Local API Access:

1. Make sure your ONYX.CENTER is connected to the Internet and can access https://api.hella.link

2. Open the ONYX App and connect to your ONYX.CENTER

3. In the app, go to Settings/Access Control and tap on the "+" button to create a temporary access code. Enter a name for the API client and tap on the button to generate the code.

   This temporary code is only valid for 15 minutes and can be exchanged for a permanent API access token by sending it to the API endpoint at https://api.hella.link/authorize

   The server responds with status 200 - OK and returns the fingerprint and access token if the temporary code is valid. If it is not, the server responds with status 401 - Unauthorized.

   Note: You must use the returned API token to make at least one API request to make it permanent. Otherwise the token will be deleted after 15 minutes.

4. Once you have the fingerprint and API access token you can use them to call the API endpoints of your ONYX.CENTER.

   Important: The access token needs to be sent as an HTTP header with every request you make to the API in the following format: Authorization: Bearer {access token}

> curl -X POST  https://api.hella.link/authorize -H "Content-Type: application/json" -d '{"code" : "H99xV2yT"}'  | json_pp

{
    "fingerprint" : "b381b2fc691ebbbce2a681b22d493e4ddcccaef58738f0caca4e9f61",
    "token" : "6EcYUqFHQulXobR7Cui1Vvplk111LZTn0KcLKieStCfQ6xiDKOFO7ZyV43333UgyyTODsQpCFi1NXAK9Wd4zpC1HdWnKKS1FTH0oDzqz1L6zec5Ebqjx1Dfx303WMmm"
}

1. Open the ONYX App and connect to your ONYX.CENTER

2. In the app, go to Settings/Access Control and tap on the "+" button to create a temporary access code. Enter a name for the API client and tap on the button to generate the code.

   This temporary code is only valid for 15 minutes and can be exchanged for a permanent API access token by sending it to the local API endpoint at https://LOCAL_ONYX_CENTER_HOSTNAME/api/v3/authorize

   The server responds with status 200 - OK and returns the fingerprint and access token if the temporary code is valid. If it is not, the server responds with status 401 - Unauthorized.

   Note: You must use the returned API token to make at least one API request to make it permanent. Otherwise the token will be deleted after 15 minutes.

3. Once you have the fingerprint and API access token you can use them to call the local API endpoints of your ONYX.CENTER.

   Important: The access token needs to be sent as an HTTP header with every request you make to the API in the following format: Authorization: Bearer {access token}

> curl -k -X POST  https://ONYX-CENTER-C0-00-00-03.local./api/v3/authorize -H "Content-Type: application/json" -d '{"code" : "H99xV2yT"}' | json_pp

{
    "fingerprint" : "b381b2fc691ebbbce2a681b22d493e4ddcccaef58738f0caca4e9f61",
    "token" : "6EcYUqFHQulXobR7Cui1Vvplk111LZTn0KcLKieStCfQ6xiDKOFO7ZyV43333UgyyTODsQpCFi1NXAK9Wd4zpC1HdWnKKS1FTH0oDzqz1L6zec5Ebqjx1Dfx303WMmm"
}

You can revoke the API access for an application just like you would revoke access for any other device connected to your ONYX.CENTER. Just go to Settings/Access Control in the ONYX App, select the API access you want to revoke and delete it.

Whenever possible you should use the latest API version supported by your ONYX.CENTER. There are two API versions that are officially supported and documented: v1 and v3

API version 2 was never publicly documented because it has several implementation issues. If your API client application relies on undocumented features available in API v2 you should upgrade your client application to API v3 to ensure compatiblity going forward.

API Version 3 introduces the following new features in addition to everything in v1:

• Local API Access
• Property Animations to simplify client side property interpolation and to correctly track the variable drive speeds of newer devices like ONYX.MOTOR
• Command Attributes to control the way in which commands are executed by devices
• A streaming API conforming to the W3C Server-Sent Events specification

With the rollout of API v3, ONYX.CENTER now actively restricts API access to publicly documented device properties and actions. This applies to previous API versions as well.

All API endpoints are located at the following base URL when using the HELLA API server:

https://api.hella.link/box/{box_fingerprint}/api/{api_version}/

Your ONYX center may support multiple API versions. You can query the supported versions with a GET request to the API endpoint https://api.hella.link/box/{box_fingerprint}/api/versions

Querying the supported API versions does not require an API token.

When using local access you instead need to use the local mDNS hostname of your ONYX.CENTER to construct the base URL as follows:

https://{mDNS_hostname}/api/versions

https://{mDNS_hostname}/api/{api_version}/...

> curl https://api.hella.link/box/b381b2fc691ebbbce2a681b22d493e4ddcccaef58738f0caca4e9f61/api/versions
{"versions":["v1", "v2", "v3"]}

> curl https://ONYX-CENTER-C0-00-00-03.local./api/versions
{"versions":["v1", "v2", "v3"]}

Devices in ONYX have properties that describe their current state. To modify the state of a device you can send it a command to change the value of a property directly, or you can execute an action. Actions typically cause one or more property changes and are executed directly on the device.

Properties can be readonly or read/write and they can have one of two types: numeric and enumeration.

"temperature" : {
    "type" : "numeric",
    "readonly" : true,
    "minimum" : -400,
    "maximum" : 1500,
    "value" : 261
}

Numeric properties, such as the temperature of an ONYX.WEATHER weather station, always have a minimum and maximum attribute to define their value range. The precision of the accepted values is defined by the device. The temperature property in the example is marked as readonly and can not be changed by sending the device a command.

"device_type" : {
    "type" : "enumeration",
    "value" : "rollershutter",
    "values" : [
        "awning",
        "raffstore_180",
        "raffstore_90",
        "rollershutter"
    ]
}

Enumeration properties, such as the device_type property in the example above, only accept a certain set of values. The possible values are listed in the values attribute.

Actions are simpler to handle than properties but they don't offer the precise control of changing properties values directly. Most acions affect multiple property values at once and cause the device to enter a defined state. The stop action for example, changes the target_position and target_angle properties of a device to stop it from moving. The available actions for a device are defined as a simple list in the device details:

"actions" : [
    "stop"
    "open",
    "close"
]

ONYX tries its best to limit the amount of radio traffic that is generated to keep system performance high and command latency low and this applies to property updates as well. The last known property values of each device are always cached on ONYX.CENTER and are only updated every few minutes unless the device state changes unexpectedly or a new command is sent to a device. This means that by the time you query the device state via the API, the devices most likely have already moved from their actual_position, actual_angle, etc.

When you need more precise position information, like for a real time visualization, it's the responsibility of your API client to extrapolate the new property values from the available device state.

To make these calculations possible, the ONYX API includes keyframe animation objects for those properties that need to be extrapolated, such as the actual_position, actual_angle and actual_brightness. Animations describe which values a property will take on at specific times in the future and the interpolation method used between them.

Animations always include at least the following fields:

{
    "actual_position": {
        "animation": {
            "start": 1626706957.5299976,
            "current_value": 9,
            "keyframes": [
                {
                    "value": 11,
                    "duration": 2.132,
                    "interpolation": "linear"
                },
                {
                    "value": 82,
                    "duration": 31.416,
                    "interpolation": "linear"
                },
                {
                    "value": 100,
                    "duration": 19.47,
                    "interpolation": "linear"
                }
            ]
        }
    }
}

In the example above the animation for actual_position starts at 2021-07-19 15:02:37.5299976 UTC with the value 9. It then progresses to the value 11 over a duration of 2.132 seconds with a linear interpolation. After that, it progresses to the value 82 over a duration of 31.416 seconds, also with a linear interpolation and so forth.

Important: The available interpolation methods may expand for future devices, even for already published API versions. If the interpolation value for a keyframe is not yet supported by your API client implementation you should always fallback to linear.

You can only affect the state of a device via the API by sending a control command. A command can execute one action or change multiple property values at once. Each command has a priority, a start date (valid_from) and an expiration date (best_before). The valid_from date determines when a command becomes valid and can be used to schedule commands in the future. The best_before time defines when a command expires and should be deactivated for a device.

Commands can also specify optional attributes that modify the way in which the commands should be executed by the devices.

If a command is valid for a longer period or if packets are lost when communicating with a device, the commands may be sent multiple times by your ONYX.CENTER.

The priority of a command determines if it is sent to a device and if it suppresses other commands that may be present for a device. Currently, ONYX defines 3 command priority classes:

• Safety

  This caetgory includes the wind, rain and hale sensors and is the most important. It suppresses any commands from the other categories

• Interactive

  This category includes all user commands and commands sent via the API. This includes commands from wall switches, remote controls, Alexa and the ONYX Apps. Interactive commands suppress any commands from the convenience category.

  The interactive category is different from the other categories in two important ways. First, there can only be one interactive command per device. If a new command arrives from another source it cancels any other interactive command for that device. Second, if an interactive command can't be sent out immediately because it is suppressed by a safety command, the interactive command is discarded. This happens even if the interactive command has a later best_before date than the safety command.

• Convenience

  This category includes all other automatic programms that are configured on your ONYX.CENTER, such as sun sensors and timers. Commands from the convenience category are only active when there are no interactive or safety commands for a device.

As mentioned above, all API commands have the priority "interactive" and are handled like any other user input.

Command attributes convey additional information to the targeted device to specify how the command should be executed if possible. Devices can choose to ignore command attributes depending on the current operating conditions, if conflicting attributes are specified or if the device doesn't support them.

The following attributes are currently defined:

Currently only ONYX.MOTOR is able to support command attributes.

Your ONYX.CENTER might be located in a different timezone than your API client device or, if no NTP server can be contacted, the clock of your ONYX.CENTER might be out of sync. This endpoint gives you access to the system clock data to correct the start and end times for any commands you send and to offset the property timestamps of devices if needed.

> curl -s -H "Authorization: Bearer 6EcYUqFHQulXobR7Cui1Vvplk2111ZTn0KcLKieStCfQ6xiDKOFO7ZyV4o3333gyyTODsQpCFi1NXAK9Wd4zpC1HdWnKKS1FTH0oDzqz1L6zec5Ebqjx1Dfx303WMmm" https://api.hella.link/box/b381b2fc691ebbbce2a681b22d493e4ddcccaef58738f0caca4e9f61/api/v1/clock | json_pp
{
   "zone" : "Europe/Vienna",
   "time" : 1527456892.94839,
   "zone_offset" : 7200
}

> curl -s -H "Authorization: Bearer 6EcYUqFHQulXobR7Cui1Vvplk2111ZTn0KcLKieStCfQ6xiDKOFO7ZyV4o3333gyyTODsQpCFi1NXAK9Wd4zpC1HdWnKKS1FTH0oDzqz1L6zec5Ebqjx1Dfx303WMmm" https://api.hella.link/box/b381b2fc691ebbbce2a681b22d493e4ddcccaef58738f0caca4e9f61/api/v1/devices | json_pp
{
   "7d4e1ced-5ff3-4616-a1a8-4bb6c3ec00bf" : {
      "name" : "Awesome Weather Station",
      "type" : "weather"
   },
   "c0cabe90-764a-4f72-a820-cb3bf8e5c55e" : {
      "name" : "Bedroom Rollershutter 1",
      "type" : "rollershutter"
   },
   "32c4eea9-909a-49cb-a1f3-bf9141252f85" : {
      "name" : "Bedroom Rollershutter 2",
      "type" : "rollershutter"
   }
}

> curl -s -H "Authorization: Bearer 6EcYUqFHQulXobR7Cui1Vvplk2111ZTn0KcLKieStCfQ6xiDKOFO7ZyV4o3333gyyTODsQpCFi1NXAK9Wd4zpC1HdWnKKS1FTH0oDzqz1L6zec5Ebqjx1Dfx303WMmm" https://api.hella.link/box/b381b2fc691ebbbce2a681b22d493e4ddcccaef58738f0caca4e9f61/api/v1/groups | json_pp
{
   "36e956d3-b61d-410e-b248-73fcfc9c6494" : {
      "name" : "Secret Lair",
      "devices" : [
         "034a3ac8-8d62-4b41-95b5-d0f4e84420fa",
         "abdf224f-84e9-48a3-94d6-c2fda22f68aa",
         "3988d54d-b8c2-4a65-b45a-47725ef4964a"
      ]
   },
   "b964881b-02a2-44cd-bb56-ee6a6d74e9a8" : {
      "name" : "Bedroom",
      "devices" : [
         "034a3ac8-8d62-4b41-95b5-d0f4e84420fa",
         "3988d54d-b8c2-4a65-b45a-47725ef4964a"
      ]
   }
}

> curl -s -H "Authorization: Bearer 6EcYUqFHQulXobR7Cui1Vvplk2111ZTn0KcLKieStCfQ6xiDKOFO7ZyV4o3333gyyTODsQpCFi1NXAK9Wd4zpC1HdWnKKS1FTH0oDzqz1L6zec5Ebqjx1Dfx303WMmm" https://api.hella.link/box/b381b2fc691ebbbce2a681b22d493e4ddcccaef58738f0caca4e9f61/api/v1/devices/3988d54d-b8c2-4a65-b45a-47725ef4964a | json_pp
{
   "name" : "Bedroom Rollershutter 1",
   "type" : "rollershutter",
   "actions" : [
      "close",
      "open",
      "stop",
      "wink"
   ],
   "properties" : {
      "actual_angle" : {
         "maximum" : 360,
         "minimum" : 0,
         "readonly" : true,
         "type" : "numeric",
         "value" : 0
      },
      "target_angle" : {
         "maximum" : 360,
         "minimum" : 0,
         "readonly" : false,
         "type" : "numeric",
         "value" : 0
      },
      "actual_position" : {
         "maximum" : 100,
         "minimum" : 0,
         "readonly" : true,
         "type" : "numeric",
         "value" : 100
      },
      "target_position" : {
         "maximum" : 100,
         "minimum" : 0,
         "readonly" : false,
         "type" : "numeric",
         "value" : 100
      },
      "system_state" : {
         "readonly" : true,
         "type" : "enumeration",
         "value" : "ok",
         "values" : [
            "collision",
            "collision_not_calibrated",
            "not_calibrated",
            "ok"
         ]
      }
   }
}

> curl -s -H "Authorization: Bearer 6EcYUqFHQulXobR7Cui1Vvplk2111ZTn0KcLKieStCfQ6xiDKOFO7ZyV4o3333gyyTODsQpCFi1NXAK9Wd4zpC1HdWnKKS1FTH0oDzqz1L6zec5Ebqjx1Dfx303WMmm" https://api.hella.link/box/b381b2fc691ebbbce2a681b22d493e4ddcccaef58738f0caca4e9f61/api/v1/groups/36e956d3-b61d-410e-b248-73fcfc9c6494 | json_pp
{
   "name" : "Secret Lair",
   "devices" : [
      "abdf224f-84e9-48a3-94d6-c2fda22f68aa",
      "3988d54d-b8c2-4a65-b45a-47725ef4964a",
      "034a3ac8-8d62-4b41-95b5-d0f4e84420fa"
   ]
}

Read the section on device commands and priorities for more details. The valid_from and best_before attributes can be ommitted when creating a command. The default value for valid_from is "right now" and for best_before it is 15 minutes in the future.

Send a command with two properties and use the default start and end times:

> curl -s -H "Authorization: Bearer 6EcYUqFHQulXobR7Cui1Vvplk2111ZTn0KcLKieStCfQ6xiDKOFO7ZyV4o3333gyyTODsQpCFi1NXAK9Wd4zpC1HdWnKKS1FTH0oDzqz1L6zec5Ebqjx1Dfx303WMmm" https://api.hella.link/box/b381b2fc691ebbbce2a681b22d493e4ddcccaef58738f0caca4e9f61/api/v1/devices/034a3ac8-8d62-4b41-95b5-d0f4e84420fa/command -X POST -d  '{"properties" : {"target_position" : 20}}' | json_pp
{
   "valid_from" : 1527510327,
   "best_before" : 1527510337,
   "properties" : {
      "target_position" : 20,
      "target_angle" : 45,
   }
}

Send a command with an action to execute with a defined start and end time:

> curl -s -H "Authorization: Bearer 6EcYUqFHQulXobR7Cui1Vvplk2111ZTn0KcLKieStCfQ6xiDKOFO7ZyV4o3333gyyTODsQpCFi1NXAK9Wd4zpC1HdWnKKS1FTH0oDzqz1L6zec5Ebqjx1Dfx303WMmm" https://api.hella.link/box/b381b2fc691ebbbce2a681b22d493e4ddcccaef58738f0caca4e9f61/api/v1/devices/034a3ac8-8d62-4b41-95b5-d0f4e84420fa/command -X POST -d  '{"action" : "open"}, "valid_from" : 1527510702, "best_before": 1527510900}' | json_pp
{
   "valid_from" : 1527510727,
   "best_before" : 1527510737,
   "action" : "open"
}

Move devices quietly to a specified position:

> curl -s -H "Authorization: Bearer 6EcYUqFHQulXobR7Cui1Vvplk2111ZTn0KcLKieStCfQ6xiDKOFO7ZyV4o3333gyyTODsQpCFi1NXAK9Wd4zpC1HdWnKKS1FTH0oDzqz1L6zec5Ebqjx1Dfx303WMmm" https://api.hella.link/box/b381b2fc691ebbbce2a681b22d493e4ddcccaef58738f0caca4e9f61/api/v1/devices/034a3ac8-8d62-4b41-95b5-d0f4e84420fa/command -X POST -d  '{"properties" : {"target_position" : 20}, "attributes": ["silent"]}' | json_pp
{
   "valid_from" : 1527510327,
   "best_before" : 1527510337,
   "attributes" : [
      "silent"
   ],
   "properties" : {
      "target_position" : 20,
      "target_angle" : 45,
   }
}

With this API endpoint, clients can cancel commands they have previously sent. Note that only commands that have been created with the same authorization token can be cancelled in this way. Cancelling an interactive command allows the ONYX.CENTER to send other active commands from the convenience priority class.

> curl -s -H "Authorization: Bearer 6EcYUqFHQulXobR7Cui1Vvplk2111ZTn0KcLKieStCfQ6xiDKOFO7ZyV4o3333gyyTODsQpCFi1NXAK9Wd4zpC1HdWnKKS1FTH0oDzqz1L6zec5Ebqjx1Dfx303WMmm" https://api.hella.link/box/b381b2fc691ebbbce2a681b22d493e4ddcccaef58738f0caca4e9f61/api/v1/devices/2b5e5e60-a9ff-4dab-a910-c3a6d475c37d/command -X DELETE

Read the section on the Device Command Endpoint for more details.

Sending a command to a group creates a separate command for each device in the group. Thus, this function is only a performance optimization so only one request is needed to control multiple devices.

The JSON response for this API endpoint includes the generated command and the HTTP status codes that would have been returned, had the command been sent to each device individually.

curl -s -H "Authorization: Bearer 6EcYUqFHQulXobR7Cui1Vvplk2111ZTn0KcLKieStCfQ6xiDKOFO7ZyV4o3333gyyTODsQpCFi1NXAK9Wd4zpC1HdWnKKS1FTH0oDzqz1L6zec5Ebqjx1Dfx303WMmm" https://api.hella.link/box/b381b2fc691ebbbce2a681b22d493e4ddcccaef58738f0caca4e9f61/api/v1/groups/36e956d3-b61d-410e-b248-73fcfc9c6494/command -X POST -d  '{"action" : "close"}}' | json_pp
{
   "command" : {
      "best_before" : 1527541187,
      "action" : "close",
      "valid_from" : 1527541177
   },
   "results" : {
      "2b5e5e60-a9ff-4dab-a910-c3a6d475c37d" : {
         "status_code" : 200,
         "status_text" : "OK"
      },
      "0bbbbbcf-3713-4372-a224-81cd6b3a82ea" : {
         "status_code" : 200,
         "status_text" : "OK"
      },
      "40594f06-7f85-40e3-9877-e5c9f38a0dd2" : {
         "status_code" : 200,
         "status_text" : "OK"
      }
   }
}

Read the section on the Cancel Device Command endpoint for more information. This API endpoint behaves in the same way but cancels the commands for all devices in a group.

> curl -s -H "Authorization: Bearer 6EcYUqFHQulXobR7Cui1Vvplk2111ZTn0KcLKieStCfQ6xiDKOFO7ZyV4o3333gyyTODsQpCFi1NXAK9Wd4zpC1HdWnKKS1FTH0oDzqz1L6zec5Ebqjx1Dfx303WMmm" https://api.hella.link/box/b381b2fc691ebbbce2a681b22d493e4ddcccaef58738f0caca4e9f61/api/v1/groups/36e956d3-b61d-410e-b248-73fcfc9c6494/command -X DELETE

The /events endpoint allows API clients to observe the state of ONYX devices and groups in real time. To use this endpoint you keep the HTTPS connection to ONYX.CENTER open and continually read events from the response body as they are generated. There are two types of events that are emitted:

• snapshot: The initial snapshot is immediately emitted when you open the connection to the /events endpoint and contains the current state of all devices as available through the Device Details API endpoint.

• patch: After the initial snapshot, ONYX.CENTER emits patch events whenever the state of a device changes, new devices are added or existing devices are removed. Each patch is a JSON Merge Patch document that can be applied to the previous snapshot to update it to the current state of your ONYX system.

> curl -k -H "Authorization: Bearer 6EcYUqFHQulXobR7Cui1Vvplk2111ZTn0KcLKieStCfQ6xiDKOFO7ZyV4o3333gyyTODsQpCFi1NXAK9Wd4zpC1HdWnKKS1FTH0oDzqz1L6zec5Ebqjx1Dfx303WMmm" https://api.hella.link/box/b381b2fc691ebbbce2a681b22d493e4ddcccaef58738f0caca4e9f61/api/v3/events
event: snapshot
data: {"devices":{"53ab8f34-e3ea-449f-851f-c1a821bbd9aa":{"name":"LED 04-ff-00-28","type":"dimmable_light","actions":["light_off","light_on","stop","wink"],"properties":{"actual_brightness":{"type":"numeric","minimum":0,"maximum":65535,"value":0,"readonly":true},"dim_duration":{"type":"numeric","minimum":20,"maximum":3600000,"value":5000,"readonly":false},"target_brightness":{"type":"numeric","minimum":0,"maximum":65535,"value":0,"readonly":false}}},"667e3604-001b-4416-841f-647857c4fdb1":{"name":"NODE 00-00-02-f2","type":"pergola_slat_roof","actions":["close","open","stop","wink"],"properties":{"actual_angle":{"type":"numeric","minimum":0,"maximum":360,"value":0,"readonly":true},"actual_position":{"type":"numeric","minimum":0,"maximum":100,"value":0,"readonly":true},"system_state":{"type":"enumeration","value":"ok","values":["collision","collision_not_calibrated","not_calibrated","ok"],"readonly":true},"target_angle":{"type":"numeric","minimum":0,"maximum":360,"value":0,"readonly":false},"target_position":{"type":"numeric","minimum":0,"maximum":100,"value":0,"readonly":false}}},"ae8a1d92-97c0-4ad0-9810-69190e14585e":{"name":"CONNECTOR 02-00-09-2b","type":"raffstore_90","actions":["close","open","stop","wink"],"properties":{"actual_angle":{"type":"numeric","minimum":0,"maximum":360,"value":89,"readonly":true},"actual_position":{"type":"numeric","minimum":0,"maximum":100,"value":11,"readonly":true},"system_state":{"type":"enumeration","value":"ok","values":["collision","collision_not_calibrated","not_calibrated","ok"],"readonly":true},"target_angle":{"type":"numeric","minimum":0,"maximum":360,"value":89,"readonly":false},"target_position":{"type":"numeric","minimum":0,"maximum":100,"value":11,"readonly":false}}}},"groups":{}}

event: patch
data: {"devices":{"ae8a1d92-97c0-4ad0-9810-69190e14585e":{"properties":{"actual_angle":{"animation":{"current_value":89,"keyframes":[{"duration":-1,"interpolation":"linear","value":0}],"start":1627048004.7762835}},"actual_position":{"animation":{"current_value":11,"keyframes":[{"duration":5,"interpolation":"linear","value":100}],"start":1627048004.7762835}},"target_angle":{"value":0},"target_position":{"value":100}}}}}

event: patch
data: {"devices":{"53ab8f34-e3ea-449f-851f-c1a821bbd9aa":{"properties":{"actual_brightness":{"animation":{"current_value":0,"keyframes":[{"duration":6,"interpolation":"linear","value":65535}],"start":1627048014.1954331}},"dim_duration":{"value":6000},"target_brightness":{"value":65535}}}}}

event: patch
data: {"groups":{"5705b5d9-84dd-4541-b535-bf4391ee7140":{"devices":["ae8a1d92-97c0-4ad0-9810-69190e14585e","667e3604-001b-4416-841f-647857c4fdb1","53ab8f34-e3ea-449f-851f-c1a821bbd9aa"],"name":"Everything"}}}

ONYX currently supports three basic kinds of devices:

• Motor controllers

  These are the ONYX.NODE, ONYX.CONNECTOR and ONYX.MOTOR which can control raffstores, awnings and rollershutters and other types of shading products.

• Lights

  ONYX.NODE and ONYX.CONNECTOR can be configured to control normal light fixtures on one of their output relays. In addition we offer a specialized ONYX.LED controller that controls the LED lighting in some awnings and pergolas and supports dimming.

• Weather stations

  ONYX.WEATHER provides measurement data for brightness, wind speed, temperature, air pressure and humidity. Depending on the hardware revision, some measurements may be unavailable.

Depending on the device type and its settings, different properties and actions can be queried and controlled via the API. This section describes the supported properties and actions for each device type. API access to properties not in this document may be restricted in the future and should be avoided.

Note that the exposed properties and actions as well as their value ranges may differ from system to system and are also dependent on the firmware versions of the ONYX.CENTER and the individual devices. Your code should always check the value ranges of each property and should not use hardcoded values.

ONYX currently supports two types of lights via the same properties and actions:

• basic_light devices can only be turned on and off and ignore the dim_duration property. The brightness can only be 0% or 100%
• dimmable_light devices support variable brightness levels and can smoothly transition between them

Copyright 2021 HELLA Sonnen- und Wetterschutztechnik GmbH