Introduction: TextPlayBulb : REST Enabled PlayBulb Using Raspberry Pi 3, BLE and Telegram

By
About: I am UX Consultant, an HCI Researcher and a former teaching assistant in information science working in Germany. An Electronic and software hobbyist.

This instructable shows how to connect to a PlayBulb Color bluetooth LED lamp using Python, a Raspberry Pi 3 and Bluetooth library and to extend the controls via a REST API for an IoT scenario, and as a bouns, the project also shows how to extend the REST API to control your PlayBulb over an IM text client e.g. Telegram, such as talking to your automated home via text.

This project is build on 3 modules :

  1. pyBulbDriver : Connect to the PlayBulb via BLE gatttool and python.
  2. pyBulbServer : Using the pyBulbDriver to expose the playbulb control via REST API.
  3. pyBulbMessenger : Connecting to a telegram bot to send and receive commands via telegram client installed on any smart phone, and using the REST API to issue commands to the PlayBulb.

You can clone the project via git repository : https://github.com/FireLin/textplaybulb.git

Goal of Project:

To create a base tool for interacting with your bulb via different modalities such as texting for now, future scenarios could involve speech commands, gesturing to the lamp ... etc.

Other resources used to create this instructable:

Contribution

pyBulbDriver is extended to be more flexible and parameterized for ease of future extension, building a scenario to allow you to fiddle with texting your lamp. Simple interface for testing and fiddling around.

Limitation

The driver is written for PlayBulb Colour, for other types of PlayBulb e.g. Original or candle, the bluetooth code in pyBulbDriver needs to changed according to the aforementioned protocol.

You need to register a telegram account, and get an api key, which you add in the pyBulbMessenger.py, follow the setting up the telegram bot in Other resources.

Step 1: Setting Up the Project

1. Getting your API key from Telegram

>> Follow the current instructable to get your API key https://www.instructables.com/id/Set-up-Telegram-Bo...

>> Add your api key to variable api in pyBulbMessenger.py

2. Setting your PlayBulb Name in pyBulbDriver

>> For the gatttool to find the write device, set your device name to be scanned using pyBulbDriver.scanForBulb("PLAYBULB COLOUR"). Example can be found in pyBulbServer.py to set up your REST Server

3. To start the project

>> You need to start pyBulbServer.py first, then followed by pyBulbMessenger.py for the texting. You can test the pyBulbServer commands using CURL.

4. Material Needed :

>> Raspberry Pi 3 and PlayBulb Color or PlayBulb Candle

>> Installing Telegram for Android or iOS

5. Installation of Rasberry Pi 3 LE Bluetooth :

http://www.elinux.org/RPi_Bluetooth_LE

Step 2: Walking Through the Code

pyBulbDriver.py

pyBulbDriver contains the driver classes for connecting to the PlayBulb via BLE

pyBulbDriver can be used also for any other generic projects, as it only contains the code to scan and set up playBulb connections.

The main APIs for User Application interface :

  • scanForBulb(devicename:String) > To scan for the PlayBulb or PlayBulbs via their device name
  • setBulbColor(s:int ,r:int ,g:int ,b:int) > To define the brightness and RGB color (0 to 255) values

  • setBulbEffect(s:int ,r:int ,g:int ,b:int ,mode:int ,onbeat:int, offbeat:int) > Similar to setBulbColor, but includes the type of effect and speed. To know more check the color protocol Effects section https://github.com/Phhere/Playbulb/blob/master/pro...

In this class you will also find other helper methods meant for data integrity check and not for user interface

  • convertRGBToHexaCmd(s,r,g,b)
  • convertIntToHex(number)
  • checkModeAndSpeed(mode,offbeat,onbeat)
  • checksRGBInBounds(s,r,g,b)

pyBulbServer.py

pyBulbServer exposes the User Application interface into RESTful hyperlinks using PUT and JSON to send and receive data to the pyBulbDriver. Also the scan and initialization of the BLE connection is made when the server is activated.

pyBulbResource(Resource) channels the calls to the REST Server using color and effect to define the bulb command.

Example For commanding an effect :

http://127.0.0.1/bulb/effect

JSON POST > {data':'{"s":0,"r":255,"g":255,"b":255,"m":1,"on":15,"off":15}'}

pyBulbMessenger.py

Finally pyBulbMessenger is responsible for interfacing the Telegram bot connected to your telegram smart phone client. For more details about how to configure and connect to a telegram bot check https://www.instructables.com/id/Set-up-Telegram-Bo....

cmdHandler(bot, update) is where the text commands are defined and connected to the PlayBulb via the RESTful API.

Currently the project only have text, another goal is to also send recorded voice messages that would be sent to a speech recognizer to activate other commands (Not Implemented Yet).


Step 3: Conclusion

The current architecture design was more about simplification than scalability. Still missing group connectivity, also more applications concerning texting the bulb either for straight command or playful interaction is still under research.

By subscribing to git repo or following, more details will come on these updates. The reason for such a project was to interface the playBulb and creating a RESTful interface for ease of development in an IoT (internet of things scenario) but also to open the chance to use different modalities via the IM Client telegram such as pictures, voice and text to interact with appliances from a research perspective.