The Bond V2 API allows control of Ceiling Fans, Fireplaces, and other Bond devices. It is intended for integration with offline control systems, for use by advanced users, hobbiests, integrators, and installers.

For the purposes of device control, it does not matter whether these devices are remote-controlled devices that Work with Bond (connected via a Bond Bridge) or smart devices that are Smart by Bond.

This documentation describes the Local HTTP API for Bond products running v2 firmware. This API does not require an internet connection, but does require that the API client be able to directly communicate with the Bond over HTTP. Typically this means being on the same Wi-Fi network. We are still working on a Cloud API, which will be very similar to the Local API.

We welcome your corrections and improvements to this documentation! You can find the source code for the documentation at the link below. Feel free to open a PR.

https://github.com/bondhome/api-v2

The Bond Local API uses unencrypted HTTP using a simple token-based authentication mechanism.

Why HTTP and not HTTPS?

After speaking with many users interested in Local API, we discovered that users were satisfied with the protection provided by their Wi-Fi network's password, and that it is more important to provide easy and low-latency control of Bond devices than to provide security against other devices and users on the Wi-Fi network.

Furthermore, it can be challenging for an API client to use HTTPS securely. In order to protect against malicious devices or users inside your Wi-Fi network, it would be necessary for an HTTPS API client to check the validity of the Bond's HTTPS certificate against an Olibra Certificate Authority. The web standard of using domain-based certificate chain-of-trust does not work when offline, because the Bond does not have a domain name, being a device on your local network rather than on the public internet. As a consequence, an HTTPS API would not work from many webbrowsers due to the certificate being untrusted.

That said, if you have untrusted users or devices on your Wi-Fi network, we recommend placing Bond on a seperate home automation network to which the untrusted users do not have the password.

Security on the Internet

Rest assured that when Bond products communicate with Bond Cloud (which is needed for integration and voice control support), we use industry-standard secure TLS connections, secured with per-unit public key cryptography. There is no unencrypted communication between Bond hardware and Bond Cloud.

Please be sure to always use Bond behind a firewall, and do not set up port-forwarding to the Bond Local API, to ensure that unsecured communications do not take place over the public internet.

To get the optimal match between this documentation and your Bond's exposed API, we recommend you update your Bond to the most recent firmware available. In situations where part of this API is only available on Beta firmware, we will try to make this clear. To use such a feature, you'll need to upgrade your firmware with a Beta app. You can sign up to receive Beta apps through one of the links in this post, and we will typically post about Beta features in the Beta category of the forums

First, power on a Bond device and connect it to your Wi-Fi network. Use the Bond app to confirm that the Bond's firmware is at least version v2.

The newest versions of the Bond Home app (starting in v2.15) have the Bond's IP address in the Bond's "Network Info" screen. Tapping it will copy it to your clipboard. If ping is more convenient for you, please refer to the instructions below.

From your PC connected to the same network, try pinging the Bond. For example, if your Bond ID is ZZBL12345, you can ping it by running the following command in a terminal:

ping BB18038.local

You should see the IP address printed, along with reply messages. Press Ctrl-C to exit the ping program:

PING bb18038.local (192.100.0.61): 56 data bytes
64 bytes from 192.100.0.61: icmp_seq=0 ttl=64 time=96.800 ms
64 bytes from 192.100.0.61: icmp_seq=1 ttl=64 time=34.902 ms
64 bytes from 192.100.0.61: icmp_seq=2 ttl=64 time=4.226 ms
^C
--- bb18038.local ping statistics ---
3 packets transmitted, 3 packets received, 0.0% packet loss
round-trip min/avg/max/stddev = 4.226/45.309/96.800/38.503 ms

You can see the IP address of this Bond is 192.100.0.61.

Note that the lookup from Bond ID to IP address is performed using mDNS. You will need to make sure that mDNS is installed and enabled on your system (this is the default for most Linux distros and on MacOS).

You can search for all Bonds on your local network. On Linux, do:

avahi-browse -a | grep bond

And on MacOS, do:

dns-sd -B _bond._tcp .

In both cases, you will see a list of Bonds on your Wi-Fi network and their IP addresses.

[Added in v2.18.2] If you want to check for firmware version and discoverability of the Bond without connecting to it, you may look into the text properties of the _bond._tcp mDNS service:

dns-sd -Z _bond._tcp .

You should see a line like this in the reply:

ZPEA77090._bond._tcp TXT "v=v2.18.0-2-gf4ddfba8-dirty-merck-discoverability" "d=0"

Next, let's check the Bond's firmware version. To do this, we will use a command-line utility called cURL. cURL is installed by default on MacOS and most Linux distributions.

To check the firmware version, run this command:

curl -i http://192.100.0.61/v2/sys/version

The flag -i means "display header information". You should see output similar to this:

HTTP/1.1 200 OK
Content-Length: 243
Content-Type: application/json; charset=utf-8

{"target":"snowbird","fw_ver":"v2.5.2","fw_date":"Fri Feb 22 14:13:25 -03 2019","make":"Olibra LLC","model":"model","branding_profile":"O_SNOWBIRD","uptime_s":380,"_":"c342ae74"}

Where, we see the firmware version is v2.5.2.

Note that no token is required for the version endpoint, but other endpoints will require token-based authentication.

The Bond Home app has the Bond's token in the Bond's "Settings" screen. Tapping it will copy it to your clipboard. If curl is more convenient for you, please refer to the instructions below.

To get the token, follow this procedure:

Power cycle the Bond, and then within 10 minutes, access the token endpoint as follows:

  curl -i http://192.100.0.61/v2/token

You should see a return body containing token such as this:

{locked":0,"pin_attempts_left":10,"token":"f074b61f628018fd","nonce":"0000000000000000","v1_nonce":"0000000000000000","account_code":"","v1_email":"","_":"c9bb9590"}

Copy the token and use it with a BOND-Token header in subsequent requests.

Alternatively, the token may be provided by setting the _token field within the request body. [Since v2.6.23]

To get a list of devices on the Bond, do:

curl -H "BOND-Token: f074b61f628018fd" -i http://192.100.0.61/v2/devices

Or, to use the embedded token technique:

curl -i http://192.100.0.61/v2/devices -X GET -d "{\"_token\": \"f074b61f628018fd\"}"

You will get a list of devices such as this:

{"_":"f7e407f1","79135791":{"_":"599b0fc5"}}

Here we see there is one device with id 79135791.

We can request the device details by doing:

curl -H "BOND-Token: f074b61f628018fd" -i http://192.100.0.61/v2/devices/79135791

And we can see the device name, location, and available Actions:

{"name":"Magic Fan","type":"CF","actions":["TurnOn","TurnOff","SetSpeed","IncreaseSpeed","DecreaseSpeed"],"location":"Dungeon","_":"599b0fc5","commands":{"_":"be8e1896"}}

Finally, let's try setting the fan's speed:

curl -H "BOND-Token: f074b61f628018fd" -i http://192.100.0.61/v2/devices/79135791/actions/SetSpeed -X PUT -d "{\"argument\": 3}"

As of v3.0.0 firmware, Bond products have moved to 64-bit keys as resource identifiers, instead of the previous 32-bit keys. So, rather than a device being identified by an 8-digit hex string, the ids for newly created devices will be 16-digit hex strings.

In an effort to minimize distruption to API clients, already created resources (devices, commands, skeds, etc.) will continue to be represented using the same exact string on the API. Additional leading zeros will not be added. So, for example, a device with id 01abcdef will continue to enumerate as 01abcdef in v2.22. The Bond API is however libral in what it accepts, removing leading zeros. So any of the following received ids will be understood to point to this device: 1abcdef, 01abcdef, 0000000001abcdef.

Internally, the Bond API uses this rule:

If the upper 32-bits of an ID are zero, then send as 8 hex digits (32-bit). Otherwise, send as 16 hex digits (64-bit).

The Bond API is organized as a tree of endpoints, starting at the root. Here's an incomplete example:

- v2
  - devices
    - 00000001
      - commands
      - state
    - 00000002
      - commands
      - state
    - 00000003
      - commands
      - state
  - sys
    - network

Clearly, if the entire tree were expanded on a request of the root, then the resulting request may be very large! This large response body would cause several problems, including taking a long time to transmit over slow networks, taking time to generate, and being too large to be effectively transmitted over the message-based protocol MQTT.

Therefore, Bond only returns a single level of the tree on every request.

Each node of the tree has a 32-bit "hash" value which is changed whenever that node, or any of the child nodes, are modified. This hash is provided in every reply body as the "_" object.

When a requested endpoint has children that are not expanded, the child values are replaced with just the child hashes.

For example, when requesting the devices endpoint, you may receive the following response:

{"_":"f7e407f1","79135791":{"_":"599b0fc5"}}

Let's break this down:

• "_":"f7e407f1" : This is the hash value of the devices object. If any devices are added, modified, or deleted, this hash will change.

• "79135791" : This is the device id of the one device on this Bond.

• {"_":"599b0fc5"} : This is the hash object representing device with id 79135791.

If the API client wants to get the name of the device, it is necessary to make a seperate request on the device itself: GET devices/79135791, which would return the name and location directly associated with the device, as well as hash objects for the child nodes of device: commands and state.

The _ hashes discussed above are designed to allow a client to quickly discover changes to a Bond's state. As we've shown, this requires the hash at a particular endpoint to incorporate not only that endpoint's state but also the state of all the children. However, it is sometimes desireable to have a hash of just the data local to that endpoint, that is, data not contained within a child.

[As of v3 firmware] we introduce a new __ (double underscore) field called a "local hash". This is intended to be used by the Bond Cloud and Bond Apps specifically for downwards synchronization as required for the Groups and Scenes features.

Most integrators can safely ignore the local hashes.

The purpose of the Request ID is to allow a client to retry a non-idempotent request (PUT, POST, PATCH, or DELETE) without risk of Bond taking the same action twice.

If you need to implement a retry mechanism in your integration, please contact the Bond Engineering Team via the Bond Forums https://forum.bondhome.io/

Each request may contain a number of request flags, which can be specified on HTTP via the Bond-Flags header (or via the f field for BPUP and MQTT transports). These flags are not needed in most integrations, but are used by Bond Home app and some partner integrations to facilitate debugging at scale.

Flags are:

• bit 0: (reserved)
• bit 1: DOWNSYNC: request is part of downward synchronization
• bit 2: UP: request is moving away from Bond
• bit 3: DUP: request is retransmitted or cached reply
• bit 4: UCAST: (internal use)
• bit 5: QUIET: (internal use)
• bit 6: BCAST: (internal use)
• bit 7: PASSTHRU: (internal use)

Certain endpoints may track their last modified time in a special __modified field. The modified time is an integer representing the time in seconds since the Unix epoch when the endpoint was last modified.

Currently the endpoints exposing __modified are:

groups/{}
groups/{}/skeds
groups/{}/skeds/{}
scenes/{}
scenes/{}/skeds
scenes/{}/skeds/{}

The modified times are set using the request time as specified in the BOND-Unixtime HTTP header (or u flag on BPUP and MQTT). Example:

BOND-Unixtime: 1643114517

{ ..., "u":"1643114517", ... }

Clients who may modify any shard endpoints should specify this header on all reqeusts. If this "unixtime" field is not provided, the Bond will use its internal real-time clock, if already set.

Conversely, if the Bond's internal clock is not yet set, it will use the timestamp specified in this field as the internal time. For this reason, only use the BOND-Unixtime header on systems with accurate clocks, such as smart phones. Incorrectly set times may result in shard synchronization issues and skeds running unexpectedly.

Bond Home V3 introduces Groups and Scenes as major new features. In designing these features, we needed to meet several requirements requested by the Bond community:

1. Groups and Scenes must work offline. A loss of internet connection must not interfere with control and feedback, and should not prevent creation and management, when the Bond Home app is on the same local network as the devices in question.
2. Smart by Bond devices can be grouped or added to a Scene with no Bond Bridge required as a hub.
3. Groups and Scenes must be resiliant to any individual Bond units going offline. That is, there must not be a central controller as a single point of failure. If only a subset of the Group or Scene devices are online, then they should still execute action requests.
4. Intuitive UI in the Bond Home app for creating, managing, and controling Groups and Scenes. The user should be blissfully unaware of any lower-level complexities.

In order to achieve the above, we chose a design where a Group or Scene object is distributed among the participating Bond units. The Group or Scene endpoint data that lives on a single Bond is called a shard. Each Bond unit acts as if it were the only participant in the Group or Scene, using only the data in its own shard, with no communication among Bond units.

The API client is responsible for managing the various shards. The most difficult aspects of this---involving correction of inconsistent data between Bonds---is handled by the Bond Home apps. However, some complexity does remain for integrators who need to send multiple requests to control a Group and must merge the data returned by those requests to present a sensible interface to the control system and ultimately the user.

We will here discuss:

• discovery, control, and feedback (for all API clients)
• management (for Bond Home app)

The following discussion is in terms of Groups but should be understood as also applying to Scenes unless otherwise specified.

To discover the Groups available on a Bond network, the client should first query the groups/ enumeration to get the group IDs in which each Bond participates. The union of the Group IDs gives the list of Groups on the network.

For example:

ZZBL12345:groups = {
  "0000000000000001":{...},
  "0000000000000002":{...},
  "0000000000000003":{...}
}

KSMJWCE12345:groups = {
  "0000000000000002":{...},
  "0000000000000004":{...}
}

There are a total of 4 groups on the network:

"0000000000000001"
"0000000000000002"
"0000000000000003"
"0000000000000004"

In this example, the Bond Bridge (ZZ...) participates in three groups with IDs 1, 2, and 3, while a Smart by Bond fan (K...) participates in groups 2 and 4.

Next, the client should query each of the group shard endpoints group/{}. The list of devices participating in the group is the union of the devices in the group shards.

For example, if the result of querying the groups/{} endpoint for the group with ID 2 is:

ZZBL12345:groups/0000000000000002 = {
  "__modified": 1642788966,
  "name": "Great Room Fans",
  "types": ["CF"],
  "locations": ["Great Room"],
  "devices": ["aabbccdd", "11223344"],
  "actions": ["TurnOn", "TurnOff"]
}

KSMJWCE12345:groups/0000000000000002 = {
  "__modified": 1642788968,
  "name": "Great Room Fans",
  "types": ["CF"],
  "locations": ["Great Room"],
  "devices": ["1"]
  "actions": ["TurnOn", "TurnOff", "TurnLightOn", "TurnLightOff"]
}

Then the API client concludes that the group named "Great Room Fans" contains three devices:

ZZBL12345:aabbccdd
ZZBL12345:11223344
KSMJWCE12345:1

In the case of a disagreement of the name between shards, the client should use the name from the group shard with the most recent modified time (__modified). If there is a tie for modified time, the client may choose arbitrarily among the shards.

The type of the group is indicated by the types array, which is typically only of length one. In this case we see it is CF for Ceiling Fan.

Determining Available Actions

The actions available on a group is the intersection of the actions available on the group shards. So, using the example from the previous section, although the group shard on the Smart by Bond fan (serial number K...) supports TurnLightOn and TurnLightOff actions, the shard on the Bond Bridge does not. So the intersection of the actions arrays is just:

["TurnOn", "TurnOff"]

Executing a Group Action

To execute an action on the group, the client should send PUT requests to the actions on each group shard. So, to turn on the Great Room Fans group, the client would send two requests using the same Group ID:

PUT http://ZZBL12345/v2/groups/0000000000000001/actions/TurnOn
PUT http://KSMJWCE12345/v2/groups/0000000000000001/actions/TurnOn

Preferably these requests should be run concurrently so that the time required to process the first request does not delay the execution of the action on the second shard.

Success, Error, and Timeout

If all requests complete successfully, then the group action can be considered a success. If any errors or timeouts occur, then an error should be reported to the user.

Whenever a group changes state, a state update is sent for the group shards and all member devices. Whenever a device state changes, a state update is sent for that devices plus an update for the state of any groups which contain that device.

Group shards report state under groups/{}/state. The schema of this endpoint is similar to that of devices/{}/state, except that state variables on a group can take the value null when the member devices disagree, as discussed below in the documentation for this endpoint. Although the Bond Bridge will combine the states of the member devices into a single state for the group shard, it is the responsibility of the API client to merge the states of each group shard to obtain an overall state for the group.

For example, suppose the client receives the following state updates:

ZZBL12345:groups/0000000000000001/state = {
  "power": 1,
}

KSMJWCE12345:groups/0000000000000001/state = {
  "power": 1,
  "light": 0
}

The client would intersect the state keys to remove any state variables not shared by all shards, and then set the values to either null if there is disagreement between shards, or to the common value. In this case the client would conclude the group state to be:

{"power": 1}

If now one of the member devices, say the Smart by Bond fan, is turned off, then the client would receive a state update for the device and group:

KSMJWCE12345:devices/1/state = {
  "power": 0,
  "light": 0
}

KSMJWCE12345:groups/0000000000000001/state = {
  "power": 0,
  "light": 0
}

The client would now combine the two group shard states to conclude:

{"power": null}

That is, that the power state of the group is indeterminate. On a UI with seperate ON/OFF buttons, this would usually be represented by highlighting neither button.

Group Creation

To create a new group, the client should send requests to each of the participating Bonds with the list of devices to include. Crucially, all shards must have the same group ID so that they will be understood as a single group by other clients. The preferred way to accomplish this is to allow the Bond to generate a random ID for the first shard, and then to specify that ID in the _post_id field during the subsequent POST requests to the other Bonds.

For example, suppose we want to add 3 Smart by Bond lights to a group called "Kitchen Lights". The requests and responses might go like this:

> POST http://TWCTBXX00001/v2/groups {"name": "Kitchen Lights", "devices": [1]}
< 201 OK {"_post_id": "0000000000000001"}

> POST http://TWCTBXX00002/v2/groups {"_post_id": "0000000000000001", "name": "Kitchen Lights", "devices": [1]}
< 201 OK {"_post_id": "0000000000000001"}

> POST http://TWCTBXX00003/v2/groups {"_post_id": "0000000000000001", "name": "Kitchen Lights", "devices": [1]}
< 201 OK {"_post_id": "0000000000000001"}

The last two requests could be parallelized.

Alternatively the client could pre-generate the ID and parallelize all three requests. However, the client MUST be sure to use a good random number generator and generate a 64-bit (16-nibble) hex string in lower-case with leading zeros.

Group Deletion

To delete a group, the client should send a DELETE request to each of the shards. If one of the Bonds is offline, then the group will only be partially deleted. The user must bring that Bond back online in order to finish deleting the group. In the meantime, the group will still exist containing just the devices on the offline Bond.

Removing Device from Group

Devices may be removed from the Group via DELETE groups/{}/devices/{}. When the last device is removed from a group, the shard containing that device will disappear (an implicit deletion).

Changing Group Name

To change the name of a group, the client should send a PATCH request to each of the shards. The name can be changed as long as there is at least one online Bond participating in the group. If any Bonds are offline, their group/{} endpoints will still have the old name. However, this does not pose a problem for API clients because the name should be taken from the group shard with the most recent __modified field.

The Bond Home app performs a special downward synchronization whereby out-of-date group shard names are updated with the latest. That is, when Bonds previously offline come back online, they are PATCHed with the name of the most recent shard in the group. Other API clients do not need to perform this downward sync function.

Schedules on groups and scenes need to be installed into each shard, and the Bond Home app performs downward synchronization on the skeds.

Sked Creation

Similar to group creation, Bond Home app creates the sked on each shard using the same 64-bit ID for that sked on each shard. The sked ID must be different than the group ID. Example:

> POST http://TWCTBXX00001/v2/groups/0000000000000001/skeds {"action":"SetBrightness", "argument":75, "mark":"sunrise", "seconds":0}
< 201 OK {"_post_id": "0000000000000007"}

> POST http://TWCTBXX00002/v2/groups/0000000000000001/skeds {"_post_id": "0000000000000007", "action":"SetBrightness", "argument":75, "mark":"sunrise", "seconds":0}
< 201 OK {"_post_id": "0000000000000007"}

> POST http://TWCTBXX00003/v2/groups/0000000000000001/skeds {"_post_id": "0000000000000007", "action":"SetBrightness", "argument":75, "mark":"sunrise", "seconds":0}
< 201 OK {"_post_id": "0000000000000007"}

The last two requests could be parallelized.

Sked Modification

Similar to changing the name of a group, the client can modify the sked settings by broadcasting a PATCH to the sked on each group shards.

Here, in the event that a Bond is offline, the sked will continue being executed with the outdated parameters until the Bond Home app performs downward synchronization to update that sked.

Sked Deletion

Deleting a group or scene sked is as simple as sending DELETE to the sked on each shard.

In the event of one or more Bonds being offline, they will continue to execute the sked until the Bond Home app syncs with them and removes the sked which was supposed to be deleted. The Bond Home app knows that a sked was deleted by checking the __modified timestamp on the group shard skeds enumeration groups/{}/skeds. If a sked is present on an older enumeration but absent on a newer one, it will be removed from the old enumeration. Similarly, if a sked is present on the newer enumeration but absent on the old one, then the Bond Home app will downwards-synchronize by POSTing the missing sked.

CAVEAT: BPUP is currently in Beta status. Breaking changes may occur to this API as we collect community feedback.

A common problem in writing drivers to support Bond devices is a need to update the client whenever device state changes. With the HTTP API, this implies inefficient polling. So we've added support for "Bond Push", a UDP-based API for low-latency control and feedback within the local network.

A client initiates a connection by opening a UDP socket to the Bond on port 30007 and sending a Keep-Alive datagram, which is just a single newline character. This subscribes the client to state updates from devices. Equivalent to the regex devices/.*/state.

The Bond will acknowledge the subscription by immediately replying with the Bond ID:

{"B":"ZZBL12345"}\n

The client should continue to send the Keep-Alive datagram on the same socket every 60 seconds to keep the connection active. If no Keep-Alive datagram is received after 125 seconds, Bond will stop sending feedback to the client.

A future update will allow subscribing to a different topic pattern.

The Bond will send to all active clients Update datagrams consisting of a JSON object terminated by a newline character. Here's an example Update datagram:

{"B":"ZZBL12345","d":0,"v":"v2.18.2","t":"devices/aabbccdd/state","i":"00112233bbeeeeff","s":200,"m":0,"f":255,"b":{"_":"ab9284ef","power":1,"speed":2}}\n

Breaking down the fields:

• B: the Bond ID
• d: discoverability (0=not discoverable, 1=setup mode, 2=sos mode) [new in v2.18.2]
• v: firmware version [new in v2.18.2]
• t: topic (the path from HTTP URL)
• i: request ID
• s: HTTP status code
• m: HTTP method (0=GET, 1=POST, 2=PUT, 3=DELETE, 4=PATCH)
• f: flags (Olibra-internal use)
• x: source transport (transport from which the request was received. Can be: "http", "mqtt", "bond" (gratuitous reply), "cli" (serial terminal), with other values reserved for future use) [Since v2.12.1]
• b: HTTP response body

There's also some client-specific error messages,

{"B":"ZZBL12345","err_id":631,"err_msg":"BPUP client timeout"}\n

For feature requests and concerns, please contact the Bond Engineering Team via the Bond Forums https://forum.bondhome.io/

IMPORTANT NOTE: MQTT redirection is implemented, but is currently untested. It may not work at all. If you have a use case for this API, please let us know on the forums so that we can better prioritize implementing and testing this API.

You can configure your Bond to communicate with a custom MQTT broker through the api/mqtt endpoint.

When the Bond connects to its configured MQTT broker, it subscribes to the topic v2/<Bond ID>/down/#, where # is a wildcard. It publishes messages to v2/<Bond ID>/up/<subtopic>, where the subtopic is that indicated in this documentation less the v2/ prefix.

A concrete example: requesting devices from the Bond.

The equivalent to HTTP GET v2/devices from a Bond with ID ZZBL12345 is publishing a message to v2/ZZBL12345/down/devices with the payload {"m": 0} (since the default for "m" (HTTP method) is 0 (GET), this payload could also just be {})

The Bond, if it had a single device with id 12345678, would then publish to v2/ZZBL12345/up/devices with the payload

{"B": "ZZBL12345", "d": 2, "v": "v2.18.2", "t": "devices", "m": 0, "i": <randomly-generated request ID>, "s": 200, "f": 255, "b" {"_": <devices hash>, "12345678": {"_": <12345678's hash>}}}

Breaking down the fields:

• B: the Bond ID
• d: discoverability (0=not discoverable, 1=setup mode, 2=sos mode) [new in v2.18.2]
• v: firmware version [new in v2.18.2]
• t: subtopic (the path from HTTP URL, without the v2/ prefix)
• i: request ID
• s: HTTP status code
• m: HTTP method (0=GET, 1=POST, 2=PUT, 3=DELETE, 4=PATCH)
• f: flags (Olibra-internal use)
• b: HTTP response body

(Note: the first two fields are redundant, they could be extracted from the MQTT topic)

The MQTT broker to which the Bond is connected is treated as trusted, so token authentication is not necessary. Make sure you check the server certificate using the appropriate fields in the api/mqtt endpoint to avoid man-in-the-middle attacks.

[Added in v3.5.1] The HomeKit integration is available on Bond Bridge Pro and support Shade devices. The integration is disabled by default, but you can enable/disable it through the Bond Home iOS app or the api/bhk endpoint.

The Setup Code is generated based on your Bond PIN (your Bond PIN two times). The Bond PIN is located on the product label. The Setup Code is also available on the Bond Home iOS app.

Setup Code example

For Bond PIN "1234", your HomeKit Setup Code is "12341234".

Added in v2.40.2, the HomeKit info is available in both the Bond Settings screen and the Manage Integrations screen.

In the Bond Settings screen, the HomeKit info is presented under the Advanced Settings section.

In the Manage Integrations screen you should see the HomeKit listed if at least one of your Bonds supports it. The HomeKit cell shows how many Bonds have the HomeKit integration enabled (not available) at the moment. Tapping on the cell will take you to the HomeKit List screen, showing the HomeKit info for every Bond that supports it.

The HomeKit info consists of a toggle switch to enable/disable the feature and shows its Setup Code.

Open the Home app on your iPhone/iPad and follow these steps:

• Tap on "Add Accessory"
• Choose the "I Don't Have a Code or Cannot Scan" option
• Tap on your Bond Bridge name in the list of Nearby Accessories
• Select the "Add Anyway" option for the "Uncertified Accessory" prompt
• Enter yours Bond Bridge Setup code and hit Continue
• Set the Location and Name for your Bridge
• Set the location and Name for your Bridge's devices, if any

Bonds may be discovered via either mDNS or BPUP. A Bond on the network will reply to queries regardless of its discoverability. However, clients (especially the Bond Home app) need to know if the device should be shown in the list of devices available for setup, or whether it is functioning normally and should be ignored. (This is a usability rather than a security consideration.)

To this end, we have added [in v2.18.2] a discoverability flag in the mDNS, BPUP, and even MQTT replies, with the following possible values:

• 0 = not discoverable: Bond is on an account and functioning normally. Should not appear in any list of Bonds ready to set up.

• 1 = setup mode: Bond is not on an account. This is either a new unit, or a unit that has had a GREEN or WHITE reset performed. The unit's light ring will be either Solid Green (ready on Ethernet) or Flashing Green (ready on Wi-Fi).

• 2 = SOS mode: the Bond is on an account, however there is either a cloud connection problem, or for Smart by Bond devices where the user has held down the Power button to re-enable discoverability. In this case, the light ring (if present) will indicate an error, and the Config AP will be opened. SOS mode is automatically exited if the cloud connection is restored.

The Bond Bridge, also referred to simply as "Bond", connects RF- and IR-controlled devices to Wi-Fi. Learn more at https://bondhome.io/product/.

A "Smart by Bond" appliance is a smart appliance that uses the API described here, other than those parts designated as "Bridge Only".

Within the Bond ecosystem, the term "device" always refers to a home appliance connected to Bond. A Bond Bridge is not itself a device.

Bond devices support one or more "features", such as Speed or Brightness, which come with a set of Actions, State Variables, and Properties that define and control some aspect of the device.

For example, a device which supports the Light feature will always have actions for TurnLightOn, TurnLightOff, and ToggleLight. Furthermore, it will always have the light state variable.

See the Features section below for detail on all supported features.

Devices are controlled by calling "actions" such as SetSpeed or TurnOff.

Some actions require an "argument" to be included. For example, SetSpeed requires an integer argument with the speed number to set.

Actions represent a user's intent, but do not nessisarly map one-to-one onto the commands that are sent to a device. Actions abstract away the complexity of the underlying commands needed to achieve the desired change in state of a device.

Bond Bridges operate by translating actions into "commands". While actions are in a user's language, commands are in the device's remote control's language. Often there is a one-to-one mapping from actions to commands, for example, most ceiling fans have distinct RF commands for each speed. So the action "SetSpeed(3)" is always translated into the same RF signal that tells the device to go to the third speed.

However, sometimes a device does not have a single command which always accomplishes a specific action. For example, most ceiling fans do not have a specific command corresponding to the TurnOn action, but rather, Bond remembers the previous speed that the fan was set to, and uses a particular SetSpeed command to accompish the TurnOn action. On the other hand, certain ceiling fans do have a specific TurnOn command. In that case the TurnOn action will always map to the TurnOn command. This results in the correct speed being restored even if the factory remote control was used.

The term "signal" refers to the actual RF or IR transmission sent to the remote-controlled device to accomplish a particular command.

Every command should have exactly one corresponding signal. However, the Bond Bridge supports a number of signal endpoints which allow manipulation of signals directly, such as signal/scan to receive signals, or signal/tx to transmit a signal without association to a device.

The Bond Bridge makes an effort to track the state of devices, and this state is represented by a set of "state variables", such as speed and brightness.

Speed variables cannot be set directly, but rather are manipulated indirectly through actions. For example, the SetSpeed action with an argument of 3 has the side-effect of setting the speed state variable to 3 and the power variable to 1.

Some device Features have a "Property" which parameterizes the devices capabilities. For example, multi-speed ceiling fans supporting the Speed feature will always have a max_speed property which gives the maximum speed which the speed state variable may take.

Some properties are read-only, others are PATCH-able.

Feature Toggles

Properties starting with feature_ are called feature toggles, and always default to true. When a feature toggle is set to false, the corresponding feature is disabled along with all dependent features, leaving only the top-level feature toggle.

For example, on a device with Light, UpDownLight, Brightness, and UpDownLightBrightness features, setting feature_light to false will cause all properties, state variables, and actions for all four of these features to be removed from the API, including the feature toggles feature_brightness and feature_up_down_light. Only feature_light will remain.

The intended use of feature toggles is in the Bond Home application's device settings screen, wherein the currently visible feature toggles should correspond exactly to toggle switches. Furthermore, the client need not have any feature-specific code for this: the order of feature toggles in the properties JSON object may be used as the UI display order, and the display names may be programmatically derived from the property names, e.g. feature_up_down_light displayed as "Up Down Light".

Feature toggles are only available for some features, and are currently only available for Smart by Bond devices.

Devices have a combination of actions, state variables, and fixed properties. In order to understand how these relate to each other, it is helpful to organize actions into features and study one feature at a time.

The Power feature controls the basic on/off state of a device.

For Ceiling Fans, it refers to the state of the fan motor. Note that most ceiling fans have lights which are not governed by the Power feature.

For Fireplaces, it refers to the state of the flame. Note that many fireplaces have separate light or fan functions, which are not governed by the Power feature.

Properties

(none)

State Variables

• power: (integer) 1 = on, 0 = off

Actions

• TurnOn(): Turn device power on.
• TurnOff(): Turn device power off.
• TogglePower(): Change device power from on to off, or off to on.

The Timer feature allows turning off a device after a specified delay, similar to the dial timer interface on toaster ovens.

The Timer feature requires the Power feature.

Properties

(none)

State Variables

• timer: (integer) seconds remaining on timer, or 0 meaning no timer running

Actions

• SetTimer(s): Start timer for s seconds. If power if off, device is implicitly turned on. If argument is zero, the timer is canceled without turning off the device.

NOTE: The timer is canceled implicitly by any action on the Power, Speed, or Breeze features, other than TurnOn. For example, if a timer is running, and the user turns off the device and then turns it back on, the timer will be canceled and therefore the device will not turn off again unexpectedly. The intention that a timer is designed to help reduce energy consumption, but should never surprise the user who forgot that they enabled the timer function earlier. When the timer reaches zero it runs TurnOff, so it will turn off the device whether it is set at a specific speed or it is set to breeze.

The Speed feature is used by multiple-speed Ceiling Fans to track the motor speed.

The Speed feature requires the Power feature.

Note that while many Fireplaces have a built-in fan, they do not use the Speed feature. See FpFan feature.

Properties

• max_speed: (integer, read-only) highest speed available

State Variables

• speed: (integer) value from 1 to max_speed. If power=0, speed represents the last speed setting and the speed to which the device resumes when user asks to turn on.

Actions

• SetSpeed(speed): Set speed and turn on. If speed>max_speed, max_speed is assumed. If the fan is off, implicitly turn on the power. Setting speed to zero or a negative value is ignored.
• IncreaseSpeed(speeds): Increase speed of fan by specified number of speeds. If the fan is off, implicitly turn on the power.
• DecreaseSpeed(speeds): Decrease fan speed by specified number of speeds. If attempting to decrease fan speed below 1, the fan will remain at speed 1. That is, power will not be implicitly turned off. If the power is already off, DecreaseSpeed is ignored.

NOTE: When the device is turned off, the previous speed is remembered. When the fan is then turned back on, it will resume at the previous speed.

The Breeze feature of many multi-speed Ceiling Fans provides a randomized breeze.

Breeze works by pseudorandomly changing the power and speed of the fan over time to create a natural breeze effect. There are two parameters of the breeze which may be adjusted to provide the desired breeze effect.

The Breeze feature requires the Speed feature.

Properties

(none)

State Variables

• breeze: (array) array of the form [ <mode>, <mean>, <var> ]:
  • mode: (integer) 0 = breeze mode disabled, 1 = breeze mode enabled
  • mean: (integer) sets the average speed. 0 = minimum average speed (calm), 100 = maximum average speed (storm)
  • var: (integer) sets the variability of the speed. 0 = minimum variation (steady), 100 = maximum variation (gusty)

Actions

• BreezeOn(): Enable breeze with remembered parameters. Defaults to [50,50].
• BreezeOff(): Stop breeze. Fan remains on at current speed.
• SetBreeze(breeze): Enable breeze with specified parameters (same as breeze state variable). Example SetBreeze([1, 20, 90]).

NOTE: If breeze is enabled when the fan is powered off, then breeze will be restored at power on.

NOTE: Calling SetBreeze with first parameter equal to 0 will disable breeze, but still set the specified mean and var parameters.

NOTE: SetSpeed implicitly disables breeze mode.

The Direction feature is used by reversible Ceiling Fans to track the direction of the fan motor.

The Direction feature requires the Power feature.

Properties

(none)

State Variables

• direction: (integer) 1 = forward, -1 = reverse.

The forward and reverse modes are sometimes called Summer and Winter, respectively.

Actions

• SetDirection(direction): Control forward and reverse.
• ToggleDirection(): Reverse the direction of the fan.

The Light feature governs the basic on/off status of a device's main light.

This is a very common feature of Ceiling Fans, and present on many Fireplaces.

See the UpDownLight feature for the behavior of devices with dual lights.

Properties

• feature_light: (boolean, PATCH-able) true = Light feature enabled (default), false = Light feature disabled

State Variables

• light: (integer) 1 = light on, 0 = light off

Actions

• TurnLightOn(): Turn light on.
• TurnLightOff(): Turn off light.
• ToggleLight(): Change light from on to off, or off to on.

The UpDownLight feature governs the on/off status of a device's upwards- and downards-facing lights, such as the ceiling-wash "up light" and direct "down light" found on some high-end ceiling fans.

The corresponding physical remote often has seperate buttons for the UpLight and DownLight, but no button for just "Light". However, Bond always makes the Light feature available along with UpDownLight to make these devices easy to integrate. For example, saying "Alexa, Turn on the Light" corresponds to the TurnLightOn action, which will have a reasonable result for devices with UpDownLight.

UpDownLight depends on Light feature.

Properties

• feature_up_down_light: (boolean, PATCH-able) true = Up Down Light feature enabled (default), false = Up Down Light feature disabled, both physical light circuits will operate as one Light.

State Variables

• up_light: (integer) 1 = up light enabled, 0 = up light disabled
• down_light: (integer) 1 = down light enabled, 0 = down light disabled

If both up_light and light are 1, then the up light will be on, and similar for down light.

Note that both up_light and down_light may not be simultaneously zero, so that the device is always ready to respond to a TurnLightOn request.

Actions

• TurnUpLightOn(): Turn up light on.
• TurnDownLightOn(): Turn down light on.
• TurnUpLightOff(): Turn off up light.
• TurnDownLightOff(): Turn off down light.
• ToggleUpLight(): Change up light from on to off, or off to on.
• ToggleDownLight(): Change down light from on to off, or off to on.

Note that TurnLightOff/TurnLightOn honor the up_light and down_light enable variables. That is, the user is able to use the factory remote to select a prefered combination of up and down light, and that combination is restored when TurnLightOn is called, perhaps through a voice integration.

The Brightness feature governs lights which can be dimmed to specified brightness level.

This feature is common on classic Ceiling Fans whose remotes have displays. Note, however, that classic Ceiling Fans whose remotes do not have displays typically only support HoldToDim or HoldToDimUpDown feature.

Properties

• feature_brightness: (boolean, PATCH-able) true = Brightness feature enabled (default), false = Brightness feature disabled. When PATCH-ing to false, brightness is set to 100 prior to disabling the feature.

State Variables

• brightness: (integer) percentage value of brightness, 1-100. If light=0, brightness represents the last brightness setting and the brightness to resume when user turns on light. If fan has no dimmer or a non-stateful dimmer, brightness is always 100.

Actions

• SetBrightness(brightness): Set the brightness of the light to specified percentage. Value of 0 is ignored, use TurnLightOff instead.
• IncreaseBrightness(amount): Increase brightness of light by specified percentage. If light is off, it will be turned on at (0 + amount).
• DecreaseBrightness(amount): Decrease light brightness by specified percentage. If attempting to decrease brightness below 1%, light will remain at 1%. Use TurnLightOff to turn off the light. If the light is off, the light will remain off but the remembered brightness will be decreased.
• CycleBrightness(amount): Cycle brightness up/down. Implicitly turns on light. NOTE: This action is for the sake of remote controls with a hold-to-dim button. Please do not use in integrations because it tends to be a frustrating experience. SetBrightness is strongly preferred for its predictability.

NOTE: The brightness level is remembered on TurnLightOff and restored on TurnLightOn.

The LowEndTrim feature allows a remapping of the brightness levels to increase the minimum physical brightness sent to the lights. This is useful with landscape lighting dimmers where the installer has a choice of luminaires which may have different minimum duty-cycle requirements.

When a value of X% brightness is requested via the API (or, of course, via the app), the value will be remapped to Y% before being sent to the lights, accoring to the formula:

Y = (X - 1)*(100 - low_end_trim)/99 + low_end_trim

In plain English: low_end_trim sets the minimum brightness of the lights.

Availability: Currently on SBB low-voltage dimmers only.

Properties

• low_end_trim: (integer) percentage value of minimum physical brightness to send to lights. Set to 1% for full brightness range. Allowed range: 1 to 90, inclusive. PATCH to null to restore factory default.

State Variables

(none)

Actions

(none)

The UpDownBrightness feature extends the Brightness feature to cover the ability of ceiling fans with separately dimmable up and down lights.

This feature is almost only found on Smart by Bond Ceiling Fans.

Properties

(none)

State Variables

• up_light_brightness: (integer) percentage value of up light brightness, 1-100.
• down_light_brightness: (integer) percentage value of down light brightness, 1-100.

Actions

• SetUpLightBrightness(brightness): Similar to SetBrightness but only for the up light.
• SetDownLightBrightness(brightness): Similar to SetBrightness but only for the down light.
• IncreaseUpLightBrightness(amount): Similar to IncreaseBrightness but only for the up light.
• IncreaseDownLightBrightness(amount): Similar to IncreaseBrightness but only for the down light.
• DecreaseUpLightBrightness(amount): Similar to DecreaseBrightness but only for the up light.
• DecreaseDownLightBrightness(amount): Similar to DecreaseBrightness but only for the down light.

NOTE: The brightness level of each light is remembered on TurnLightOff, TurnUpLightOff, TurnDownLightOff and restored on TurnLightOn, etc.

NOTE: IncreaseBrightness and DecreaseBrightness operate on whichever of the up and down lights are enabled, but will never enable or disable one or the other light.

The ColorTemp feature is used to control the correlated color temperature (CCT) of a light.

The ColorTemp feature requires the Light and Brightness features, and there are currently no products with both ColorTemp and UpDownLight. In other words, all CCT-adjustable products have exactly one dimmable light, and if the Brightness option is disabled via feature toggles, the ColorTemp feature will also be disabled.

Note that the color temperature is works in 100 Kelvin (K) steps. Attempts to set non-multiples of 100 K will result in undefined rounding behavior.

Properties

• max_color_temp: (integer) maximum color temperature in Kelvin
• min_color_temp: (integer) minimum color temperature in Kelvin

State Variables

• color_temp: (integer) color temperature in Kelvin. Resolution: 100 K

Actions

• SetColorTemp(int): Set color temperature. Implicitly turns Light on.
• IncreaseColorTemp(int): Increase color temperature a specified number of degrees K. Implicitly turn Light on.
• DecreaseColorTemp(int): Increase color temperature a specified number of degrees K. Implicitly turns Light on.
• CycleColorTemp(int): Change color temperature in cyclical fashion, similar to CycleBrightness. Implicitly turns on Light. NOTE: This exists for the sake of remote controls, it is generally not useful for integrations, please use SetColorTemp instead.
• CycleColorTempPreset(): Jump to next preset CCT value from an internal list of presets. Number and value of presets undefined and may vary by model. Useful for very basic integrations where you have just a single push button.

The Flame feature is used by fireplaces to indicate flame level.

The Flame feature requires the Power feature.

Properties

State Variables

• flame: (integer) value from 1 to 100. If power=0, flame represents the last flame setting and the flame to which the device resumes when user asks to turn on.

Actions

• SetFlame(flame): Set flame and turn on. If flame>100, 100 is assumed. If the fireplace is off, implicitly turn on the power. Setting flame to zero or a negative value is ignored.
• IncreaseFlame(flame): Increase flame level of fireplace by specified number of flames. If the fireplace is off, implicitly turn on the power.
• DecreaseFlame(flame): Decrease flame level by specified number of flames. If attempting to decrease fireplace flame below 1, the fireplace will remain at fflame 1. That is, power will not be implicitly turned off. If the power is already off, DecreaseFlame is ignored.

The Open feature is used to describe a device that can be opened and closed. Common use cases are motorized shades and garage doors.

Properties

(none)

State Variables

• open: (integer) 1 = open, 0 = closed

Actions

• Open(): Open the device.
• Close(): Close the device.
• ToggleOpen(): Close the device if it's open, open it if it's closed

Notes

If your remote has a discrete stopping command, consider using the Hold() action to stop the motion of the device.

The Position feature is used to describe a device that can be opened to a specific position as a percentage. The common use case is motorized shades.

The Position feature requires the Open feature.

Properties

(none)

State Variables

• position: (integer) value from 0 to 100: 0 = open, 100 = closed.

Actions

• SetPosition(position): Set device to specified position percentage.
• IncreasePosition(amount): Close the device by the specified percentage of the full range.
• DecreasePosition(amount): Open the device by the specified percentage of the full range.

Notes

[March 2021] At this time, the Position feature is available only for certain Motorized Shades on the Bond Bridge Pro.

The feature may be enabled or disabled via the feature toggle property feature_position, analogous to the other feature toggles. However, if course_time is present, it will need to also be set to a non-negative value before the actions and state variables will be exposed, so as to avoid integrations from showing a slider interface without the Bridge having the capability of setting position.

The CourseTime feature is used for shades whose RF protocols do not natively support Position. Bond Bridge Pro emulates a Position feature using a custom dead reckoning algorithm. This requires the client to specify the time required for the shade to open or close.

The CourseTime feature requires the Position feature.

Properties

• course_time: (integer) specifies the amount of time, in milliseconds, required for the device to fully open or close. Depending on the device template, this property may or may not be present. Defaults to -1, meaning unconfigured.

State Variables

(none)

Actions

(none)

The FpFan feature controls a fireplace fan. The FpFan feature is independent of the power feature, which for fireplaces indicates whether the flame is on or off.

Properties

(none)

State Variables

• fpfan_power: (integer) 1 = on, 0 = off
• fpfan_speed: (integer) from 1-100

Actions

• TurnFpFanOff(): Turn the fireplace fan off
• TurnFpFanOn(): Turn the fireplace fan on, restoring the previous speed
• SetFpFan(speed): Sets the speed of the fireplace fan

Collected here are some actions that may be used with other features, but have no state-change behavior on the Bond.

Actions

• Stop(): This action tells the Bond to stop any in-progress transmission and empty its transmission queue.
• Hold(): Can be used when a signal is required to tell a device to stop moving or the like, since Stop is a special "stop transmitting" action
• Pair(): Used in devices that need to be paired with a receiver.
• StartDimmer(): Start dimming. The Bond should time out its transmission after 30 seconds, or when the Stop action is called.
• StartUpLightDimmer(): Use this and the StartDownLightDimmer instead of StartDimmer if your device has two dimmable lights.
• StartDownLightDimmer(): The counterpart to StartUpLightDimmer
• StartIncreasingBrightness(): Similar to StartDimmer, but doesn't cycle and only increases brightness.
• StartDecreasingBrightness(): Similar to StartDimmer, but doesn't cycle and only decreases brightness.