Skip to content

Instantly share code, notes, and snippets.

@andersevenrud

andersevenrud/0_NEXA_BRIDGE_X.md

Last active January 13, 2024 19:17
Show Gist options
  • Star 1 You must be signed in to star a gist
  • Fork 1 You must be signed in to fork a gist
  • Save andersevenrud/e4637c0cbde665f72f864032e540aa5d to your computer and use it in GitHub Desktop.
Save andersevenrud/e4637c0cbde665f72f864032e540aa5d to your computer and use it in GitHub Desktop.
Download ZIP
Nexa Bridge X Documentation
Raw
0_NEXA_BRIDGE_X.md

Nexa Bridge X Documentation

The "Nexa Bridge X" is a Smart Home bridge device. The internal name is "Bridge2".

It can be attached to a home network and monitor / control devices via an App/Cloud or Local Web UI. Supports assigning devices to rooms and various automations via the provided firmware.

Since this devices comes with a (semi) open API and Websocket it's custom to create custom integrations.

The purpose of this gist is to collect and archive information because there's not much out there and not easily accessible/discoverable, and mostly written in Swedish. Most of this is just from personal notes after writing a Home Assistant Integration.

These documents contains links to the way back machine archives with fresh captures to keep the dates relevant to this gist.

See this gist for information about NEXA Z-Wave devices.

Product Links

Apps

Integrations

Raw
1_DEVICE_SUPPORT.md

Nexa Bridge X Device Support

Supported protocols

  • Z-Wave / Z-Wave+ (Gen5)
  • System Nexa / NXT (433MHz)
  • Fire & Safety (FS-558)

Supported gateways

  • Sonos
  • Philips Hue
  • IKEA Trådfri
  • Twinkly
  • Sensibo ?

Supported devices

Probably any device matching in protocols or gateways above.

Tested devices

See this github issue where I've started a thread for reporting compatability.

This gist will be updated alongside this issue thread.

System Nexa / NXT (433MHz)

Manufacturer Model Description
❔ Nexa NBA-002 Temperature & Humidity Sensor (Battery) 1
❔ Nexa MYCR-250 Dimmer (Plug-in) 1
❔ Nexa NEYCT-705 Remote (Battery) 1

Z-wave

Manufacturer Model Description
✔️ Nexa AD-147 Dimmer (Plug-in)
✔️ Nexa ZPR-111 Switch w/energy meter (Plug-in)
✔️ Nexa ZDS-102 Door/Window Sensor (Battery)
✔️ Fibaro FGWPE/F-102 Switch w/energy meter (Plug-in)
✔️ Aeotec aërQ Temperature & Humidity Sensor (Battery)
✔️ Namron ? 1 Channel switch / dimmer (Battery) 2

Gateways

TODO

...

Footnotes

  1. Firmware 2.4.1 has Nexa protocols disabled ?! (@andersevenrud) ↩ ↩2 ↩3

  2. Buggy inclusion. Required multiple tries (@andersevenrud) ↩

Raw
2_FIRMWARE.md

Nexa Bridge X Firmware

https://nexa.se/nexa-bridge-x/changelog (archived)

Confusingly, the Bridge2 can ship with 1.x firmware as noted in this article (archived). Probably some kind of transition period.

2.4.1

This version is undocumented.

I personally have this firmware and it's either a bit broken or some features have been removed. Things like the nxt "ops" endpoints just gives 404 making pairing of certain devices impossible.

2.4.0

For some reason this is not on the changelog page, but on a news page (archived)

Soon we will start rolling out an update to Nexa Bridge X that will help you save a little more electricity at home. The update mainly consists of two new features, one of which has already been available for a while; electric spot prices and Sensibo.

Below we go through what this is.

Electricity spot prices

For those who are a little less familiar, electricity spot prices (or hourly prices) are the price that your electricity supplier buys your electricity for, excluding grid fees, taxes, VAT, etc. This price is thus the basis for your electricity price, one way or another.

Note that you must have an hourly price in your subscription.

When you select your region (SE1, SE2, SE3 or SE4) in the app, Nexa Bridge X will retrieve the price and compile it. When this is done, you can, among other things, receive notifications when the price is considered cheap or expensive, you can receive warnings about the current cost and start automating the various prices.

A good example of automation is that you can turn off one or more gadgets when the price goes over X number of cents. For example, washing machine, dryer or dishwasher.

Sensibo

This is a small product you can buy that allows you to control most of the models of air source heat pumps available. When you pair this to your Nexa Bridge X, your air source heat pump will appear just like any other device, where you can then turn it on and off and regulate the temperature.

Here you can then create smart automations. For example, you can reduce the temperature at night automatically or turn off the air heat pump when the door is opened, all to save on electricity.

Other improvements

This update also includes quite a few minor improvements and bug fixes, some of which are listed below (including the apps):

  • The battery level of devices is downloaded more continuously (Z-Wave)
  • The cost of electricity is now calculated hourly for the price set, instead of at the end of the day. Previously, it gave a distorted picture when it came to variable hourly rates.
  • It is possible to set associations (let a Z-Wave transmitter control a receiver directly)
  • Simplified configuration parameters appear under the device when changing it (Z-Wave)
  • PDF manual and product sheet can appear under the device if you change it (Z-Wave)
  • Fixed a problem that caused sunrise and sunset to sometimes be incorrectly calculated for several hours
  • Fixed a problem that meant that the scheduling sometimes in some cases did not run at the appointed time
  • Fixed an issue that made it impossible to set configuration parameters on some devices (Z-Wave)
  • Fixed a problem that caused old sensor data not to be deleted, which in turn meant that the space on the Bridge could run out after a very long time

2.3.9

  • Support for electricity spot prices
  • Support for Sensibo
  • Retrieves battery levels more continuously (Z-Wave)
  • It is possible to set associations (let a Z-Wave transmitter control a receiver directly) (Z-Wave)
  • Fixed an issue that made it impossible to set configuration parameters on some devices (Z-Wave)
  • PDF manual and product sheet can appear under the device if you change it (Z-Wave)

2.2.7

  • Support for HomeKit
  • Turn on lights when a fire alarm goes off
  • Time synchronization bug fixes
  • Possibility to change the brightness of the LEDs

2.0.12

This release has no official information.

However, the official API documentation seems to be generated from this release.

Raw
3_API.md

Nexa Bridge X API

Kudos to Nexa for providing developer documentation for this device!

The API is open on the following ports:

  • 80: Web server
  • 8887: WebSocket for realtime updates
  • 8888: Also a websocket, but always JSON instead of cap:{} ?!

Factory login is nexa / nexa

Runs on node with Express and currently unknown libraries.

Firmware 2.4.1 runs on node v12.14.1 spesifically.

Legacy Nexa Bridge

The legacy Nexa Bridge, aka "Bridge1" has a very similar API to the "Bridge2". A few differences:

  • The /nodes endpoint does not contain any values. These have to be looked up from the /nodes/:id endpoint.
  • The /energy endpoint responds with a different data model.
  • The "capability" properties is value models is always called "name" (which is also in Bridge2, but the "capability" was probably added to avoid confusion with node names vs capability names).
  • Calling a binary switch value update is {"cap": "switchBinary", "method": "turnOn"}, not {"cap": "switchBinary", "value": 1}

Documented capabilities

https://nexa.se/docs/capabilities_public.json (archived)

Undocumented capabilities

  • battery - percentage 0-100
  • notificationIntrusion - binary true/false
  • configuration - configuration parameters (key/value)

Documented endpoints

https://nexa.se/docs/ (archived api endpoints) (archived api info)

Undocumented endpoints

  • GET /v1/info
    • ?extended=1
  • GET /v1/eventlog
    • ?limit=0,1
    • ?where=
  • GET /v1/wifi
  • GET /v1/scenarios
  • GET /v1/triggers
  • GET /v1/triggers/:id
  • GET /v1/usersettings
  • GET /v1/clients
  • GET /v1/clients/:id
  • GET /v1/rooms
  • DELETE /v1/nodes/:id
  • GET /v1/nodes
    • ?field=
  • GET /v1/ex/system
  • GET /v1/ex/addons
  • GET /v1/ex/addons/categories
  • DELETE /v1/clients
    • ?clientId=
  • DELETE /v1/rooms/:id
  • DELETE /v1/scenarios/:id
  • DELETE /v1/triggers/:id
  • POST /v1/clients
  • POST /v1/clients/:id
  • POST /v1/location
  • POST /v1/triggers
  • POST /v1/triggers/:id
  • POST /v1/scenarios
  • POST /v1/scenarios/cmd
  • POST /v1/rooms
  • POST /v1/rooms/:id
  • POST /v1/usersettings
  • POST /v1/ex/contacts
  • POST /v1/ex/contacts/:id/delete
  • POST /v1/ex/nodes/save
  • POST /v1/actions/restartnx
  • POST /v1/actions/led
    • ?level=
  • POST /v1/actions/remoteSupport
    • ?port=
  • POST /v1/energy/price
    • ?price=
  • POST /v1/system2/startRxPairing
  • POST /v1/system2/txPairing
    • ?timeout=
  • POST /v1/nodeops/removeNode
  • POST /v1/nodeops/removeNodeAbort
  • POST /v1/nodeops/addNode
  • POST /v1/nodeops/addNodeAbort
  • POST /v1/nodeops/listenGarvan
  • POST /v1/nodeops/listenGarvanAbort
  • POST /v1/nodeops/nexaOperations/sendLearningCode
  • POST /v1/nodeops/nexaOperations/learnTrasmitter
    • ?action=

Websocket

The websocket streams updates from system and devices.

Messages

Weather

It's not currently known how often this is published.

{"systemType":"weather","subtype":"air_pressure_at_sea_level","value":1022.7,"time":"2023-01-03T21:00:00.013Z"}
{"systemType":"weather","subtype":"air_temperature","value":-18,"time":"2023-01-03T21:00:00.022Z"}
{"systemType":"weather","subtype":"cloud_area_fraction","value":0,"time":"2023-01-03T21:00:00.037Z"}
{"systemType":"weather","subtype":"relative_humidity","value":81.9,"time":"2023-01-03T21:00:00.048Z"}
{"systemType":"weather","subtype":"wind_speed","value":1.5,"time":"2023-01-03T21:00:00.059Z"}
{"systemType":"weather","subtype":"wind_speed_of_gust","value":2.7,"time":"2023-01-03T21:00:00.067Z"}
{"systemType":"weather","subtype":"precipitation_amount","value":0,"time":"2023-01-03T21:00:00.075Z"}
{"systemType":"weather","subtype":"probability_of_precipitation","value":0,"time":"2023-01-03T21:00:00.083Z"}
{"systemType":"weather","subtype":"probability_of_thunder","value":0,"time":"2023-01-03T21:00:00.091Z"}
{"systemType":"weather","subtype":"summary","value":"clearsky_night","time":"2023-01-03T21:00:00.100Z"}

System

The minute and clock is published every minute, and hour every hour.

{"systemType":"time","subtype":"minute","value":0,"time":"2023-01-03T21:00:00.243Z"}
{"systemType":"time","subtype":"hour","value":22,"time":"2023-01-03T21:00:00.248Z"}
{"systemType":"time","subtype":"clock","value":"22:00","time":"2023-01-03T21:00:00.252Z"}

Inclusion

Seems to emit registration data:

removeNodeStarted
nodeManager:{"systemType":"system","name":"nodeManager","event":"removeNodeStarted","time":"2023-02-20T17:54:24.898Z"}
removeNodeStarted
nodeManager:{"systemType":"system","name":"nodeManager","event":"removeNodeStarted","time":"2023-02-20T17:54:29.930Z"}
nodeManager:{"systemType":"system","name":"nodeManager","event":"removed","nodeId":"u7zkVPbu8N41psi2","time":"2023-02-20T17:54:30.040Z"}
nodeRemoved


nodeManager:{"systemType":"system","name":"nodeManager","event":"addNodeStarted","time":"2023-02-20T18:12:22.956Z"}
addNodeStarted
addNodeFoundNew:{"id":0}
nodeManager:{"systemType":"system","name":"nodeManager","event":"addNodeFoundNew","id":0,"time":"2023-02-20T18:12:23.049Z"}
nodeManager:{"systemType":"system","name":"nodeManager","event":"interviewStage","stage":1,"time":"2023-02-20T18:12:23.277Z"}
interviewStage:{"stage":1}
nodeManager:{"systemType":"system","name":"nodeManager","event":"interviewStage","stage":2,"time":"2023-02-20T18:12:25.342Z"}
interviewStage:{"stage":2}
addNodeFoundNew:{"id":25}
nodeManager:{"systemType":"system","name":"nodeManager","event":"addNodeFoundNew","id":25,"time":"2023-02-20T18:12:30.180Z"}
inclusionMetadata:{"id":"interviewing_cc","name":"Battery"}
nodeManager:{"systemType":"system","name":"nodeManager","event":"inclusionMetadata","ccName":"Battery","time":"2023-02-20T18:12:30.649Z"}
inclusionMetadata:{"id":"interviewing_cc","name":"Manufacturer Specific"}
nodeManager:{"systemType":"system","name":"nodeManager","event":"inclusionMetadata","ccName":"Manufacturer Specific","time":"2023-02-20T18:12:42.076Z"}
nodeManager:{"systemType":"system","name":"nodeManager","event":"inclusionMetadata","ccName":"Version","time":"2023-02-20T18:18:55.512Z"}
nodeManager:{"systemType":"system","name":"nodeManager","event":"added","nodeId":"4svLyQ0qUDcN0gRX","time":"2023-02-20T18:19:12.120Z"}

Device

These messages are not pure JSON. For some reason they're prefixed with the same value as capability.

Also, a sourceNode of -1 indicates a "virtual" device update, i.e.: internal power and metering values.

Publishing of these seem to be in realtime from the devices (but proxied through the Nexa device express server).

power:{"systemType":"device","sourceNode":"-1","capability":"power","name":"power","value":1420.13,"subtype":"state","time":"2023-01-03T21:02:15.342Z"}
Raw
4_MISC.md

Nexa Bridge X Misc

Misc information about the device.

Open ports

Port 8887 not shown in output from nmap, but this is still open.

22/tcp   open  ssh
80/tcp   open  http
111/tcp  open  rpcbind
8888/tcp open  sun-answerbook

Shell access

This device has an openssh server running, but it only accepts id-rsa key logins. No username or password.

Key is unknown.

Discovery information

Hostname is nexabridge2.local and can be discovered via zeroconf/bonjour.

Legacy bridge is nexabridge.local

Discoveries

  • The server on the Nexa Bridge X includes workarounds for sensors that reports broken values (like the infamous 10 bit random flip in metering that causes huge negative numbers. Nexa actually has this defect in their own products)
  • This bridge does not fully respect the z-wave standards when it comes to API exposure, which means some data is missing and events, names etc. might actually diverge from their actual function. An example is the certain environmental sensors with humidity warnings or leak detection can be reported as a fire alarm.
  • The interview process when doing device inclusion can hang in certain cases
  • If the capability is not supported by the bridge, you won't get any control at all in HA
  • Battery levels reporting seems narrow (I get 50% on a device that reports ~60% on zwavejs)
Raw
5_TEARDOWN.md
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment