Bond Bridge
The Bond Bridge (Olibra / Bond Home) is an RF-and-IR-to-Wi-Fi hub. You pair your ceiling fans, gas fireplaces, motorized shades, and RF lights with the Bridge in the Bond mobile app, and the Bridge relays their original remote-control signals over the network. GEM talks to the Bridge over its local network API, so one Bridge becomes one GEM device, and every paired accessory on that Bridge becomes its own GEM zone that GEM creates for you automatically.
Because Bond reproduces the accessory's own RF/IR remote, control is one-way for most devices: GEM can send commands, but it can only report state back as well as the Bridge can, which for one-way RF gear means the reported state can drift if someone uses a physical wall remote.
What's controlled
GEM sorts each paired Bond device by its type and gives it the matching controls:
- Ceiling fans — on / off, fan speed, fan direction (forward / reverse), and — on fans with an integrated light — the light on / off and its brightness.
- Fireplaces — on / off, plus flame height (0–100 %) on fireplaces whose Bond pairing exposes flame control.
- Motorized shades — open, close, stop (hold), and set to a position (0–100 %).
- RF lights — on / off and brightness (0–100 %).
Any Bond device whose type isn't one of these four is skipped — no zone is created for it.
Prerequisites
- A Bond Bridge on the same LAN as GEM, reachable by IP. Give it a DHCP reservation so its address never moves — a moved address means GEM can no longer reach the Bridge.
- Bridge Pro: use its Ethernet address. A Bridge Pro keeps its Wi-Fi station connected even once it is plugged in, and takes a DHCP lease on each interface. Polling over the Wi-Fi lease adds roughly twenty times the latency and jitter of the wired one. Reserve the Ethernet lease and enter that address as the Bridge IP. GEM logs a warning on connect when the configured address turns out to be the Wi-Fi one.
- Pair your fans, fireplaces, shades, and lights in the Bond mobile app first. GEM only discovers accessories the Bridge already knows about; it does not pair new RF/IR remotes.
- The Bridge's local API token. You get it one of two ways:
- Copy it from the Bond app under Settings → Local API, or
- Leave it blank and let GEM fetch it automatically during the short pairing window right after the Bridge is power-cycled (see the next section).
Setup — adding the Bridge
- Open Devices, add a device, and choose the Bond Bridge driver.
- Set the Bridge IP Address field to the Bridge's LAN IP. Leave HTTP Port at
80unless you have remapped it. - Provide the token one of two ways:
- Manual token — paste the value from the Bond app's Settings → Local API into the Local API Token field. This is the reliable path and is recommended for a permanent install.
- Auto-fetch — leave Local API Token blank, power-cycle the Bridge, and enable the GEM device within about 10 minutes of power-up. During that window the Bridge hands out its token without authentication; GEM fetches it, saves it (encrypted), and uses it from then on. If you miss the window the token request fails and the device stays disconnected — power-cycle and try again, or just paste the token manually.
- Save and enable the device. On connect GEM reads the Bridge's device list, looks up each paired accessory, and auto-creates a zone for every supported device (see below). It then begins polling state.
The manual token never expires under normal use, so for a commissioned site paste it in rather than relying on the post-power-cycle auto-fetch window. The auto-fetch path is handy on the bench but easy to miss on a job site.
How zones are created
When the device connects (and whenever you run the sync_devices command), GEM creates one
zone per supported Bond accessory:
| Bond device type | Zone goes in subsystem | On-screen control |
|---|---|---|
| Ceiling fan | Fans | Fan control (speed + direction) |
| Fireplace | Fireplace | Fireplace control |
| Motorized shade | Shades | Shade control (position slider) |
| RF light | Lights | Dimmer control |
Each created zone is named <bridge-name>_<bond-device-name> (lowercased, with underscores),
its on-screen label is the device's Bond name, and its address is the Bond device ID — the
same ID the Bridge uses internally. You don't type any of this; GEM fills it in. If two
accessories share a name (or the name is already used elsewhere in GEM), the Bond device ID is
appended to the zone name — the label is unaffected. See
auto-created zones.
GEM places ceiling fans in the standard Fans subsystem, shades in the standard Shades subsystem and RF lights in the standard Lights subsystem. Fireplaces, however, land in a subsystem named Fireplace, which GEM creates if it doesn't already exist — this is separate from the default Fire subsystem. So a Bond fireplace lives under Fireplace, not Fire. You can move a zone to a different subsystem afterward in Zones if you prefer to consolidate them. (Earlier builds filed Bond lights under a separate Lighting subsystem; zones created back then stay where they are until you move them.)
If new accessories are paired in the Bond app later, run the sync_devices command (from
the device's Commands tab, or on a schedule) to discover them and create their zones.
Existing zones are left in place; only missing ones are added.
The device's Setup tab shows the same picture at a glance: Discover lists every accessory
the Bridge knows, with the zone each one is mapped to, and Sync from device runs
sync_devices. An accessory whose zone you disabled shows as disabled rather than being
recreated; one whose zone you deleted can be recreated from the list.
Keeping state current
GEM re-reads every Bond zone's state on a loop, set by the Status Poll Interval (ms) device attribute (default 5000 ms). Polling runs through the zones one at a time with a short throttle between each, so a Bridge with many accessories takes proportionally longer to cycle through them all — the effective refresh interval grows with the device count. Raising the interval reduces network chatter; lowering it makes the on-screen state track faster.
After GEM sends a command it also re-reads that one device's state immediately, so a control you operate from GEM updates without waiting for the next poll.
Each state read is one short-lived HTTP connection — the Bridge closes every connection after answering — bounded by Request Timeout (ms) (default 5000). The Bridge's TCP stack keeps each closed connection on its books for about two minutes, and when GEM's next poll happens to be handed the same client port in that window the Bridge stalls the new connection instead of accepting it. That hits roughly one poll in a few hundred, on Ethernet and Wi-Fi alike. GEM abandons a handshake that has not completed within TCP Connect Timeout (ms) (default 2000) and retries the poll once on a fresh socket; the Bridge never received the stalled request, so the retry is safe for commands as well as reads.
A request that fails outright even so does not on its own mark the Bridge offline: connected
only drops after Failures Before Offline (default 3) consecutive failures, roughly 30 s at
the default interval, and comes back on the first answered request. One lost poll therefore
costs one stale reading rather than an offline/online event, an alarm, and a history entry. Set
the threshold to 1 if you want the Bridge reported offline on the first missed request.
While the Bridge is not answering at all, GEM stops a polling pass at the first unanswered read
rather than waiting out the timeout on every zone, and after three such passes it polls less
often — doubling up to once a minute — until the Bridge answers again, when the normal interval
resumes. A blank, 0 or unreadable Status Poll Interval means the 5000 ms default.
If the Bridge can't be reached when the device connects — for example GEM starts up before the Bridge does after a power cut — GEM tries again after 30 seconds, doubling to every 5 minutes, until the Bridge answers. You don't need to reload the device. A Bridge that answers but turns GEM away (wrong token, or the token window has closed) is not retried; fix the token and reload.
If one accessory's details couldn't be read when the device connected, GEM reads them again on a later poll (at most once a minute) rather than leaving that zone unusable until a reload.
Attributes
Device — required
| Attribute | Type | Description |
|---|---|---|
ip | string | The Bond Bridge's LAN IP address. |
Device — optional
| Attribute | Type | Default | Description |
|---|---|---|---|
token | string | (auto) | The Bridge's local API token. Paste it from the Bond app, or leave blank to let GEM fetch it during the post-power-cycle window. Stored encrypted. |
port | int | 80 | HTTP port of the Bridge's local API. |
status_interval | int | 5000 | How often (ms) GEM re-reads each accessory's state. |
request_timeout | int | 5000 | How long one request to the Bridge may take before it counts as a failure. |
connection_failure_threshold | int | 3 | Consecutive failed requests before the Bridge is marked disconnected. It comes back on the first answered request. |
connect_timeout | int | 2000 | How long to wait for the Bridge to complete the TCP handshake before abandoning the socket and retrying once on a fresh one. |
last_sync | int | — | Read-only. Timestamp of the last successful sync_devices. |
Zone
GEM populates these on each zone when it discovers the device — you don't set them by hand:
| Attribute | Type | Description |
|---|---|---|
device_id | string | The Bond device ID (mirrors the zone address). Read-only. |
device_type | string | CF (ceiling fan), FP (fireplace), MS (motorized shade), or LT (light). Read-only. |
GEM also reports live state onto each zone as it polls — state (on/off, or open/partial/closed
for shades), level (fan speed, light brightness, or shade position), direction
(forward/reverse for fans), light_state and brightness (a fan's integrated light), and
flame (a fireplace). These names are cataloged, so they autocomplete in the Attribute editor
and can drive attribute triggers — for example, fire a macro when a fan's state becomes on.
Commands
Driver-declared commands appear on the device's Commands tab and can be used in macros, triggers, and on UI buttons. The commands that apply depend on the zone's Bond device type; sending a command to the wrong type returns an "unknown command" error. Every command takes the target zone's address (the Bond device ID), which GEM fills in from the zone you pick.
Ceiling fans
| Command | Action |
|---|---|
on / off | Turn the fan on or off. |
level (arg level) | Set fan speed. 0 turns the fan off; a value of 1–100 sets the speed. The built-in Fan control's Low / Medium / High buttons send 33 / 66 / 100. |
toggle_direction | Reverse the fan direction (summer ⇄ winter). |
light_on / light_off | Turn the fan's integrated light on or off. |
set_brightness (arg brightness) | Set the integrated light's brightness, 0–100. |
Fireplaces
| Command | Action |
|---|---|
on / off | Turn the fireplace on or off. |
level (arg level) | Set flame height, 0–100. Only works on fireplaces whose Bond pairing exposes flame control — the Bridge returns an error otherwise. |
Motorized shades
| Command | Action |
|---|---|
open / close | Fully open or close the shade. |
stop | Stop (hold) a shade in motion. |
level (arg level) | Move the shade to a position, 0 (closed) to 100 (open). |
RF lights
| Command | Action |
|---|---|
on / off | Turn the light on or off. |
level (arg level) | Set brightness, 0–100. 0 turns the light off. |
Hub maintenance
| Command | Action |
|---|---|
sync_devices | Re-read the Bridge's device list and create zones for any newly paired accessories. Takes no arguments and works even before any zones exist. |
get_devices | List the accessories the Bridge knows from the last sync as {devices: [{id, name, type}]}. Creates nothing and sends no request. |
Known limitations
- Fireplace damper and fan-speed buttons have no effect. Flame height is adjustable via the
levelcommand (where the Bond pairing exposes it), but the built-in fireplace control's damper and fan-speed buttons do nothing on a Bond fireplace, since the Bridge doesn't expose those for this gear. - State can drift on one-way RF devices. Many Bond-controlled fans, fireplaces, and shades are one-way: the Bridge transmits the remote signal but can't tell whether the accessory acted on it, and it never learns that someone pressed a physical wall remote. GEM reports the last state the Bridge knows, which may not match reality after manual remote use. Polling more often narrows the gap but can't close it for genuinely one-way gear.
- Speed and position are best-effort feedback. A fan's speed and a shade's position are read back from the Bridge as a 0–100 level; on one-way devices that figure reflects GEM's last command rather than a measured position.
- The auto-fetch token window is brief. The Bridge only hands out its token without authentication for a short period after a power cycle. Outside that window, GEM can't fetch a token — paste it from the Bond app instead.
Troubleshooting
| Symptom | Check |
|---|---|
| Device won't connect; log notes it couldn't fetch a token | The auto-fetch window has closed. Power-cycle the Bridge and enable the device within ~10 minutes, or paste the token from the Bond app (Settings → Local API) into Local API Token. |
sync_devices finds zero devices | No accessories are paired in the Bond app yet. Pair your fans / fireplaces / shades / lights in the app first; sync_devices only discovers what the Bridge already knows. |
| A command returns "device not found in cache" | The accessory was added after GEM last synced. Run sync_devices, or reload the device, to refresh GEM's view of the Bridge. |
| A Bond fireplace isn't under the subsystem I expected | Bond fireplaces are placed in Fireplace — separate from the default Fire subsystem. Lights go in the standard Lights subsystem (a zone created by an earlier build may still sit under Lighting). Look there, or move the zone in Zones. |
| Zone state lags behind the physical remote | The accessory is likely one-way RF — the Bridge can't see wall-remote presses. Shorten the Status Poll Interval, or accept that physical-remote state drifts. |
| Commands do nothing after a while | Confirm the Bridge's IP hasn't changed (use a DHCP reservation) and that the device is still enabled. |
Commands return http 401 and the log notes the Bridge refused the local API token | The token is wrong or the Bridge was reset. Paste the current token from the Bond app (Settings → Local API) into Local API Token and reload the device. While the token is refused, GEM leaves zone state alone rather than reporting accessories as off. |
connected flaps every 20–40 minutes, the log shows timeout of …ms exceeded on a state read, and the Bridge never rebooted | A poll landed on a client port the Bridge still holds from a connection closed within the last two minutes, and the Bridge stalled the handshake (see Keeping state current). Current builds retry that poll on a fresh socket and only mark the Bridge offline after Failures Before Offline consecutive failures. On a Bridge Pro also make sure the Bridge IP Address is the Ethernet one: on connect GEM logs bond bridge reports a wired address when it is not (or query http://<ip>/v2/sys/eth with the BOND-Token header), and the Wi-Fi path adds latency of its own. |
See also
- Devices — adding and configuring devices.
- Zones — how zones map accessories to controls and subsystems.
- Subsystems — what the Fans, Shades, Lights, and Fireplace subsystems are.
- Commands — running and scripting device commands.
- Macros and Triggers — automating Bond devices and reacting to their state.