Skip to content

Commit 2f0dfd1

Browse files
larsblumberglarsblumberg
authored
Merge pull request #20 from getsenic/feature/dbus
Replace Nuimo SDK with new implementation that uses BlueZ's D-Bus API
2 parents 5bb5de4 + 15f94f9 commit 2f0dfd1

File tree

12 files changed

+1182
-620
lines changed

12 files changed

+1182
-620
lines changed

‎LICENSE

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
The MIT License (MIT)
22

3-
Copyright (c) 2016 Senic GmbH
3+
Copyright (c) 2017 Senic GmbH
44

55
Permission is hereby granted, free of charge, to any person obtaining a copy
66
of this software and associated documentation files (the "Software"), to deal

‎README.md

+113-61
Original file line numberDiff line numberDiff line change
@@ -1,95 +1,147 @@
11
# Nuimo Python SDK
2+
[Nuimo](https://senic.com) is a universal smart device controller made by [Senic](https://senic.com).
23

3-
The **Nuimo** SDK is a single Python source file. It has been tested with Python 2.7 and Python 3.4.
4+
The Nuimo Python SDK for Linux allows you to integrate your Nuimo(s) into any type of Linux application or script that can execute Python code.
5+
6+
## Prerequisites
7+
The Nuimo SDK requires [Python 3.4+](https://www.python.org) and a recent installation of [BlueZ](http://www.bluez.org/). It is tested to work fine with BlueZ 5.43, slightly older versions should however work, too.
48

59
## Installation
610
These instructions assume a Debian-based Linux.
711

8-
1. `git clone https://github.com/getsenic/nuimo-linux-python`
9-
2. `cd nuimo-linux-python`
12+
On Linux the [BlueZ](http://www.bluez.org/) library is necessary to access your built-in Bluetooth controller or Bluetooth USB dongle. Some Linux distributions provide a more up-to-date BlueZ package, some other distributions only install older versions that don't implement all Bluetooth features needed for this SDK. In those cases you want to either update BlueZ or build it from sources.
1013

11-
The remainder of these instructions assume `nuimo-linux-python` is the current directory.
14+
### Updating/installing BlueZ via apt-get
1215

13-
For convenience, the following groups of commands are included in a shell script **examples/install.sh**
16+
1. `bluetoothd --version` Obtains the version of the pre-installed BlueZ. `bluetoothd` daemon must run at startup expose the Bluetooth API via D-Bus.
17+
2. `sudo apt-get install --no-install-recommends bluetooth` Installs BlueZ
18+
3. If the installed version is too old, proceed with next step: [Installing BlueZ from sources](#installing-bluez-from-sources)
1419

20+
### Installing BlueZ from sources
1521

16-
### 1. Install bluez (Linux)
22+
The `bluetoothd` daemon provides BlueZ's D-Bus interfaces that is accessed by the Nuimo SDK to communicate with Nuimo Bluetooth controllers. The following commands download BlueZ 5.43 sources, built them and replace any pre-installed `bluetoothd` daemon. It's not suggested to remove any pre-installed BlueZ package as its deinstallation might remove necessary Bluetooth drivers as well.
1723

18-
On Linux the [Bluez](http://www.bluez.org/) library is necessary to access your inbuilt Bluetooth controller or Bluetooth USB dongle.
19-
If you are using a Raspberry Pi, the Bluez library is pre-installed in Raspian Jessie. The Raspberry Pi 3 comes with Bluetooth Controller hardware.
24+
1. `sudo systemctl stop bluetooth`
25+
2. `sudo apt-get update`
26+
3. `sudo apt-get install libusb-dev libdbus-1-dev libglib2.0-dev libudev-dev libical-dev libreadline-dev libdbus-glib-1-dev unzip`
27+
4. `cd`
28+
5. `mkdir bluez`
29+
6. `cd bluez`
30+
7. `wget http://www.kernel.org/pub/linux/bluetooth/bluez-5.43.tar.xz`
31+
8. `tar xf bluez-5.43.tar.xz`
32+
9. `cd bluez-5.43`
33+
10. `./configure --prefix=/usr --sysconfdir=/etc --localstatedir=/var --enable-library`
34+
11. `make`
35+
12. `sudo make install`
36+
13. `sudo ln -svf /usr/libexec/bluetooth/bluetoothd /usr/sbin/`
37+
14. `sudo install -v -dm755 /etc/bluetooth`
38+
15. `sudo install -v -m644 src/main.conf /etc/bluetooth/main.conf`
39+
16. `sudo systemctl daemon-reload`
40+
17. `sudo systemctl start bluetooth`
41+
18. `bluetoothd --version # should now print 5.43
2042

21-
1. `bluetoothd --version` (Shows the version of the pre-installed bluez. **bluetoothd** daemon must run at startup to use Bluez)
22-
2. `sudo apt-get install --no-install-recommends bluetooth` (Installs Bluez)
43+
Please note that some distributions might use a different directory for system deamons, apply step 13 only as needed.
2344

24-
**or**
25-
```
26-
sh examples/install.sh install
27-
```
28-
#### Using bluez commandline tools
29-
Bluez also provides commandline tools such as **hciconfig, hcitool, bluetoothctl** to interact with Bluetooth devices.
30-
**bluetoothctl** was introduced in Bluez version 5.0 but many Linux distributions are still using Bluez 4.x.
45+
### Enabling your Bluetooth adapter
46+
47+
1. `sudo hciconfig hci0 up` Enables your built-in Bluetooth adapter or external Bluetooth USB dongle
48+
49+
### Using BlueZ commandline tools
50+
BlueZ also provides an interactive commandline tool to interact with Bluetooth devices. You know that your BlueZ installation is working fine if it discovers any Bluetooth devices nearby.
51+
52+
`sudo bluetoothctl` Starts an interactive mode to talk to BlueZ
53+
* `power on` Enables the Bluetooth adapter
54+
* `scan on` Start Bluetooth device scanning and lists all found devices with MAC addresses
55+
* `connect AA:BB:CC:DD:EE:FF` Connects to a Nuimo controller with specified MAC address
56+
* `exit` Quits the interactive mode
57+
58+
### Installing Nuimo Python SDK
59+
60+
To install Nuimo module and the Python3 D-Bus dependency globally, run:
61+
62+
`sudo pip3 install nuimo`
63+
`sudo apt-get install python3-dbus`
64+
65+
#### Running the Nuimo control script
66+
67+
To test if your setup is working, run the following command. Note that it must be run as root because on Linux, Bluetooth discovery is a restricted operation.
68+
69+
`sudo python3 nuimoctl.py --discover`
70+
`sudo python3 nuimoctl.py --connect AA:BB:CC:DD:EE:FF` (Replace the MAC address with your Nuimo's MAC address)
71+
72+
## SDK Usage
73+
74+
### Discovering nearby Nuimo controllers
75+
76+
The SDK entry point is the `ControllerManager` class. Check the following example to dicover any Nuimo controller nearby.
77+
78+
Please note that communication with your Bluetooth adapter happens over BlueZ's D-Bus API, hence an event loop needs to be run in order to receive all Bluetooth related events. You can start and stop the event loop via `run()` and `stop()` calls to your `ControllerManager` instance.
3179

32-
1. `sudo hciconfig hci0 up` (Enables your Bluetooth dongle)
33-
2. `sudo hcitool lescan` (Should discover your Nuimo, press Ctrl+C to stop discovery)
34-
3. `bluetoothctl devices` (Lists the previously paired peripherals)
3580

36-
**or**
37-
```
38-
sh examples/install.sh scan
39-
```
40-
#### Manually connect to Nuimo with bluez (optional, skip this step if you are not interested)
41-
42-
1. `sudo hcitool lescan | grep Nuimo` (Copy your Nuimo's MAC address and press Ctrl+C to stop discovery)
43-
2. `gatttool -b FA:48:12:00:CA:AC -t random -I` (Replace the MAC address with the address from step 1)
44-
3. `connect` (Should successfully connect to Nuimo)
45-
4. `characteristics` (Displays [Nuimo's GATT characteristics](https://senic.com/files/nuimo-gatt-profile.pdf))
46-
5. Look for uuid `F29B1529-...` (button press characteristic) and note its `char value handle` (2nd column). Here: `001d`.
47-
6. Add `1` to the handle. Here: `001d + 1 = 001e` (Hexadecimal value representation; [use a calculator if necessary](http://www.miniwebtool.com/hex-calculator/?number1=001d&operate=1&number2=1))
48-
7. `char-write-req 001e 0100` (Registers for button click events; replace `001e` with the handle from step 6)
49-
8. Hold Nuimo's click button pressed and release it. `gatttool` should now notify all button press events.
50-
8. `exit` to leave `gatttool`
51-
52-
**or**
5381
```
54-
sh examples/install.sh connect
82+
import nuimo
83+
84+
class ControllerManagerPrintListener(nuimo.ControllerManagerListener):
85+
def controller_discovered(self, controller):
86+
print("Discovered Nuimo controller", controller.mac_address)
87+
88+
manager = nuimo.ControllerManager(adapter_name='hci0')
89+
manager.listener = nuimo.ControllerManagerPrintListener()
90+
manager.start_discovery()
91+
manager.run()
92+
5593
```
5694

57-
### 2. Install Nuimo Python SDK
95+
### Connecting to a Nuimo controller and receiving user input events
5896

59-
#### Install the system dependencies
97+
Once `ControllerManager` has discovered a Nuimo controller you can use the `controller` object that you retrieved from `ControllerManagerListener.controller_discovered()` to connect to it. Alternatively you can create a new instance of `Controller` using the name of your Bluetooth adapter (typically `hci0`) and Nuimo's MAC address.
6098

61-
sudo apt-get install build-essential pkg-config libboost-python-dev libboost-thread-dev libbluetooth-dev libglib2.0-dev python-dev python-setuptools`
99+
Make sure to assign a `ControllerListener` object to the `listener` attribute of your controller instance. It will notify you about all Nuimo controller related events such connection, disconnection and user input events.
62100

63-
#### Install Nuimo SDK & it's Python dependencies
101+
The following example connects to a Nuimo controller and uses the predefined `ControllerPrintListener` class to print all controller events:
64102

65-
If you're using Python 2.X run:
103+
```
104+
import nuimo
66105
67-
sudo python setup.py install
106+
controller = nuimo.Controller(adapter_name='hci0', mac_address="AA:BB:CC:DD:EE:FF")
107+
controller.listener = nuimo.ControllerPrintListener(controller=controller)
108+
controller.connect()
68109
69-
If you're using Python 3.X run:
110+
manager = ControllerManager(adapter_name="hci0")
111+
manager.run()
70112
71-
sudo python3 setup.py install
113+
```
72114

73-
This will install Nuimo SDK package and it's dependency Gattlib (see
74-
note about Gattlib below) to Python package directory.
115+
As with Nuimo controller discovery, remember to start the Bluetooth event loop with `ControllerManager.run()`. Please make sure to use the same `ControllerManager` for starting and stopping the event loop.
75116

76-
#### Running the example script
117+
### Write to Nuimo's LED matrix
77118

78-
To test if your setup is working, run the following command (note that it must be run as root because on Linux, Bluetooth discovery is a restricted operation).
119+
Once a Nuimo controller is connected you can send an LED matrix to its display. Therefor create an `LedMatrix` object by initializing it with a string. That string should contain 81 characters: each character, starting from top left corner, tells whether the corresponding LED should be on or off. The following example shows a cross:
79120

80121
```
81-
sudo python examples/test.py
122+
matrix = nuimo.LedMatrix(
123+
"* *"
124+
" * * "
125+
" * * "
126+
" * * "
127+
" * "
128+
" * * "
129+
" * * "
130+
" * * "
131+
"* *"
132+
)
133+
controller.display_matrix(matrix)
134+
82135
```
83136

84-
You can find the example script here: [examples/test.py](/examples/test.py)
85-
86-
#### Tested on
87-
1. Raspberry Pi Model 3 - Raspbian Jessie Full (raspberrypi 4.1.18)
88-
2. Linux Mint 17.3 Rosa
137+
## Support
138+
139+
Please open an issue or drop us an email to [[email protected]](mailto:[email protected]).
140+
141+
## Contributing
142+
143+
Contributions are welcome via pull requests. Please open an issue first in case you want to discus your possible improvements to this SDK.
89144

90-
### Note about Pygattlib
91-
[Pygattlib](https://bitbucket.org/OscarAcena/pygattlib) is a Python library to use the GATT Protocol for Bluetooth LE devices. It is a wrapper around the implementation used by gatttool in the bluez package. Unlike some other Python Bluetooth libraries, Pygattlib does not need invoke any external programs.
145+
## License
92146

93-
**Known Issues**
94-
Pygattlib may not be reliable on your platform. We are investigating these issues at Senic.
95-
1. The library sometimes appears to get 'stuck', especially when executing `discover_characteristics`.
147+
The Nuimo Python SDK is available under the MIT License.

‎examples/install.sh

-81
This file was deleted.

‎examples/test.py

-92
This file was deleted.

‎gatt/__init__.py

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
from .gatt import DeviceManager, Device, Service, Characteristic

0 commit comments

Comments
 (0)