智能网关>> go-nukibridgeapi>> 返回
项目作者： christianschmizz

项目描述 ：
Makes Nuki's Bridge API accessible from the command-line.
高级语言： Go
项目地址: git://github.com/christianschmizz/go-nukibridgeapi.git
创建时间： 2020-10-26T17:58:25Z
项目社区：https://github.com/christianschmizz/go-nukibridgeapi
开源协议：MIT License
下载


go-nukibridgeapi

This project aims to make Nuki’s Bridge API accessible. Either through the
provided library or as a program from the command-line.

The Nuki Bridge acts as gateway between your Nuki
Smartlock and your Wifi network, which enables
you to access your Nuki devices remotely.

Develop

Therefore it is introducing a command-line tool called nukibridgectl which
implements access to the basic functions of your Nuki bridge for now.

:warning: Encrypted token support: There is currently no automatic detection for
support of encrypted tokens. Users of the library have to make use of the UseEncryptedToken
option to enable the use of encrypted tokens. Therefor the CLI tool only supports hashed tokens.

Activate the Bridge API

Before you can access the bridge’s API you have to activate it. It’s not active
by default.

Check API status

If you are unsure about whether the bridge’s API is already activated or not
you can check with curl:

  1. $ curl http://<bridge-address>

It will come up with HTTP 400 Bad Request when active. Otherwise you’ll see
something like Connection refused.

Activate the API

To activate the bridge API you have to bring you bridge into maintenance mode
go to “Manage Bridge” in the Nuki app. During the Bridge’s setup procedure you
can configure the settings of your Wi-Fi as well as the developer mode. To use
the API you have to enable the developer mode.

The token you need for accessing the API is shown only once when activating
the developer mode. So, make a note of it.

Discover bridges

Note: The discovery of bridges does not require a valid token.

For discovering bridges you need a working internet-connection, and you have to
execute nukibridgectl from the LAN the bridge is in. Afterwards the discover
command should report your bridge.

  1. $ nukibridgectl discover
  2. ID        IP             Port Updated
  3. 123456789 192.168.178.1  8080 2020-10-01 20:00:00 +0000 UTC

Help

To get a quick overview of the capabilities nukibridgectl offers I recommend
having a look at the help:

  1. $ nukibridgectl --help

Which might look like this:

  1. Work seamlessly with your Nuki Bridge from the command line.
  3. Usage:
  4.   nukibridgectl <command> <subcommand> [flags]
  5.   nukibridgectl [command]
  7. Available Commands:
  8.   bridge      Bridge commands
  9.   discover    Discover bridges
  10.   help        Help about any command
  12. Flags:
  13.       --config string   config file (default is $HOME/.nukibridgectl.yaml)
  14.   -h, --help            help for nukibridgectl
  16. Use "nukibridgectl [command] --help" for more information about a command.

Configuration

Config file

For ease of use I would recommend the use of a settings-file named
.nukibridgectl.yaml in one of the subsequent locations:

  • /etc/nukibridgectl/
  • Your home directory
  • Working dir

The file should look like this:

  1. host: "192.168.178.1:8080"
  2. token: abcde6

To use a custom name or location for your configuration file:

  1. $ nukibridgectl --config /my/config/feelfree.yaml ...

Params

If you want to pass on your configuration at the command-line you can do so, too:

  1. $ nukibridgectl bridge --host 192.168.178.1:8080 --token abcde6 <command>

Examples

List devices

After you set up your configuration you can query the bridge for available devices: 

  1. $ nukibridgectl bridge list
  2. Type ID        Name        Battery Firmware Version
  3. 0    123456789 Wohnungstür 68%     2.9.10
  4. 2    123456789 Haustür     0%      1.6.4

A type of 0 means a Smartlock, a type of 2 an Opener.

Simple Locking / Unlocking of a Nuki Smartlock

To just lock/unlock a smart lock (type: 0) you type:

  1. $ nukibridgectl bridge lock 0 <deviceID>
  2. $ nukibridgectl bridge unlock 0 <deviceID>

Applying more elaborate lock actions

See nuki Bridge’s API docs on lock action for
a list of available actions and their purpose. 

  1. # Execute actions at a smart lock (type: 0) via lockAction
  2. $ nukibridgectl bridge lockAction 0 <deviceID> <lock|unlock|unlatch|lockandgo|lockandgowithunlatch>
  4. # Execute actions at an opener (type: 2) via lockAction
  5. $ nukibridgectl bridge lockAction 2 <deviceID> <rto_on|rto_off|esa|cm_on|cm_off>

Query the state

See nuki Bridge’s API docs on lock states for
further details on the available information.

Short reminder from the Nuki docs:

Warning: /lockstate gets the current state directly from the device and so should not be used for constant polling to avoid draining the batteries too fast. /list can be used to get regular updates on the state, as is it cached on the bridge.

  1. $ ./nukibridgectl bridge lockState 2 123456789

Tests

Integration tests

To run the tests on a physical bridge at your LAN:

  1. % make integration-test BRIDGE_HOST=<ip:port> BRIDGE_TOKEN=<token>

Debugging things

You noticed some unexpected behaviour or just want to know whats going on
behind the scenes? You can enable debug logging by setting DEBUG at your env.

  1. $ DEBUG=1 nukibridgectl bridge --host 192.168.178.1:8080 --token abcde6 info

DBus Bridge

nukibridgectl can also forward all events of your Nuki bridge to a DBus
instance. This is useful if you want to open up your Nuki events to a broader
audience, e.g. 3rd party applications.

Therefor nukibridgectl will launch a local webserver and registers itself for
callbacks.

Fire up a local DBus instance for testing

  1. $ MY_SESSION_BUS_SOCKET=/tmp/dbus/$USER.session.usock
  2. $ dbus-daemon --session --nofork --address unix:path=$MY_SESSION_BUS_SOCKET

Run nukibridgectl

  1. $ DBUS_SESSION_BUS_ADDRESS=unix:path=/tmp/dbus/$USER.session.usock DEBUG=1 go run cmd/nukibridgectl/main.go bridge watch en0
  3. 2020-11-21T15:43:58+01:00 DBG   bridge.CallbackData{
  4.         ... // 5 identical fields
  5.         BatteryCritical:       false,
  6.         KeypadBatteryCritical: false,
  7. -       DoorsensorState:       3,
  8. +       DoorsensorState:       2,
  9. -       DoorsensorStateName:   "door opened",
  10. +       DoorsensorStateName:   "door closed",
  11.         RingactionTimestamp:   s"0001-01-01 00:00:00 +0000 UTC",
  12.         RingactionState:       false,
  13.   }
  15. 2020-11-21T15:44:04+01:00 DBG   bridge.CallbackData{
  16.         ... // 5 identical fields
  17.         BatteryCritical:       false,
  18.         KeypadBatteryCritical: false,
  19. -       DoorsensorState:       2,
  20. +       DoorsensorState:       3,
  21. -       DoorsensorStateName:   "door closed",
  22. +       DoorsensorStateName:   "door opened",
  23.         RingactionTimestamp:   s"0001-01-01 00:00:00 +0000 UTC",
  24.         RingactionState:       false,
  25.   }

Monitoring

  1. $ dbus-monitor --address unix:path=/tmp/$USER.session.usock
  3. signal time=1605969838.072019 sender=:1.0 -> destination=(null destination) serial=7 path=/nuki/bridge; interface=nuki.bridge; member=Event
  4.    struct {
  5.       int32 597123456
  6.       int32 0
  7.       int32 2
  8.       int32 3
  9.       string "unlocked"
  10.       boolean false
  11.       boolean false
  12.       int32 3
  13.       string "door opened"
  14.       boolean false
  15.    }
  17. signal time=1605969844.810805 sender=:1.0 -> destination=(null destination) serial=8 path=/nuki/bridge; interface=nuki.bridge; member=Event
  18.    struct {
  19.       int32 597123456
  20.       int32 0
  21.       int32 2
  22.       int32 3
  23.       string "unlocked"
  24.       boolean false
  25.       boolean false
  26.       int32 2
  27.       string "door closed"
  28.       boolean false
  29.    }