search

crownstone / crownstone-lib-python-ble

bluetooth module of the python library
Apache License 2.0
0 stars 2 forks source link

readme

Crownstone BLE library

A library to interact with Crownstones via Bluetooth LE.

This library uses Bleak as bluetooth backend, which supports Windows, MacOS and Linux.

Installation

Python 3.7 or 3.8 is required for this library. At the moment an upstream dependency (pythonnet) is broken (on Windows 10) for Python 3.9 and newer.

If you want to use python virtual environments, take a look at the README_VENV and be sure that your environment is activated before installing. Afterwards it's as simple as:

python3 -m pip install crownstone_ble

Async functions

This library uses async methods, which must be awaited. This is part of Python and uses the asyncio core module to do this. If you're unsure about how to use these, there's a million guides and tutorials online. We will assume you know how to use these in the rest of the documentation.

CrownstoneBle

Initialization

To use Crownstone BLE, you first import it from crownstone_ble.

from crownstone_ble import CrownstoneBle

ble = CrownstoneBle()

CrownstoneBle is composed of a number of top level methods and modules for specific commands. We will first describe these top level methods.

__init__(bleAdapterAddress=None)

When initializing the CrownstoneBle class, you can provide the bluetooth adapter address to choose which bluetooth adapter to use. This only works on linux. You can get these addresses by running:

hcitool dev

These addresses are in the "00:32:FA:DE:15:02" format. The constructor is not explicitly called with __init__, but like this:

ble = CrownstoneBle(bleAdapterAddress="00:32:FA:DE:15:02")

On other platforms you can't define which bluetooth adapter to use.

async shutDown()

Shuts down the library nicely. This is should be done when closing your script.

setSettings(adminKey: string, memberKey: string, basicKey: string, serviceDataKey: string, localizationKey: string, meshApplicationKey: string, meshNetworkKey: string)

The Crownstone uses encryption by default, so this library needs keys to encrypt and decrypt data. These keys are 16 characters long like "adminKeyForCrown" or 32 characters as a hex string like "9332b7abf19b86ff48156d88c687def6". Your keys can be obtained from the cloud. Either do this manually, or use the cloud library.

loadSettingsFromFile(path: string)

As an alternative to using setSettings, you can load it from a json file. The path is relative to the script being executed. An example of this json file is:

{
 "admin":  "adminKeyForCrown",
 "member": "memberKeyForHome",
 "basic":  "basicKeyForOther",
 "serviceDataKey":  "MyServiceDataKey",
 "localizationKey":  "aLocalizationKey",
 "meshApplicationKey":  "MyGoodMeshAppKey",
 "meshNetworkKey":  "MyGoodMeshNetKey",
}

Searching for Crownstones

In order to do something with a Crownstone, you need to know which Crownstones there are. This can be done by scanning. There are basic and convenience functions to do this.

async getCrownstonesByScanning(scanDuration=3)

This will scan for scanDuration in seconds and return an array of the Crownstone it has found. This is an array of dictionaries that look like this:

{
   "address": string,      # mac address like "f7:19:a4:ef:ea:f6"
   "setupMode": boolean,   # is this Crownstone in setup mode?
   "validated": boolean,   # if True, this Crownstone belongs to your Sphere (ie. it can be decrypted by the provided keys).
   "rssi": Float           # average of the rssi of this Crownstone. If None, there have been no valid measurements.
}

This array can be directly put in the 'addressesToExclude' field of the 'getNearest..' methods.

async startScanning(scanDuration=3)

This will start scanning for Crownstones in a background thread. The scanDuration denotes how long we will scan for. Once scanning is active, BleTopics.advertisement events will be triggered with the advertisements of the Crownstones that share our encryption keys or are in setup mode.

async stopScanning()

This will stop an active scan.

async getNearestCrownstone(rssiAtLeast=-100, scanDuration=3, returnFirstAcceptable=False, addressesToExclude=[]) -> ScanData or None

This will search for the nearest Crownstone. It will return ANY Crownstone, not just the ones sharing our encryption keys.

If anything was found, the ScanData will be returned. This datatype is defined here.

async getNearestValidatedCrownstone(rssiAtLeast=-100, scanDuration=3, returnFirstAcceptable=False, addressesToExclude=[]) -> ScanData or None

Same as getNearestCrownstone but will only search for Crownstones with the same encryption keys. If anything was found, the ScanData will be returned. This datatype is defined here.

async getNearestSetupCrownstone(rssiAtLeast=-100, scanDuration=3, returnFirstAcceptable=False, addressesToExclude=[]) -> ScanData or None

Same as getNearestCrownstone but will only search for Crownstones in setup mode. If anything was found, the ScanData will be returned. This datatype is defined here.

Connecting

Most commands from the control and state modules will require you to connect to a Crownstone before sending the command.

async connect(address: string)

This will connect to the Crownstone with the provided MAC address. You get get this address by scanning or getting the nearest Crownstone.

async disconnect()

This will disconnect from the Crownstone.

Operation mode

A fresh Crownstone starts in operation mode "setup". In this mode, it has limited functionality and does not belong to anyone. You can claim it by performing a setup, which is usually done with the smartphone app, as that also registers it at the cloud.

async def getMode(self, address, scanDuration=3) -> CrownstoneOperationMode

This will scan until it has received an advertisement from the Crownstone with the specified address. Once it has received an advertisement, it knows the mode. We will return once we know.

It can raise a CrownstoneBleException with the following types:

async def waitForMode(self, address, requiredMode: CrownstoneOperationMode, scanDuration=3) -> CrownstoneOperationMode

This will wait until it has received an advertisement from the Crownstone with the specified address. Once it has received an advertisement, it knows the mode. We will scan for the scanDuration amount of seconds or until the Crownstone is in the required mode.

It can raise a CrownstoneBleException with the following types:

async setupCrownstone(address: string, sphereId: int, crownstoneId: int, meshDeviceKey: string, ibeaconUUID: string, ibeaconMajor: uint16, ibeaconMinor: uint16)

New Crownstones are in setup mode. In this mode they are open to receiving encryption keys. This method facilitates this process. No manual connection is required.

Control module

The modules contain groups of methods. You can access them like this:

import asyncio
from crownstone_ble import CrownstoneBle

# initialize the Bluetooth Core
ble = CrownstoneBle()

async def example():
    # set the switch stat eusing the control module
    await ble.connect(address) # address is a mac address (or handle on OSX)
    await ble.control.setSwitch(0)
    await ble.disconnect()

loop = asyncio.get_event_loop()
loop.run_until_complete(example())

Methods:

async setSwitch(switchVal: int)

You can switch the Crownstone. 0 for off, 100 for on, between 0 and 100 to dim. There are also special values to be found in SwitchValSpecial. If you want to dim, make sure dimming is enabled. You can enable this using the allowDimming() method.

async commandFactoryReset()

Assuming you have the encryption keys, you can use this method to put the Crownstone back into setup mode.

async allowDimming(allow: bool)

Enable or disable dimming on this Crownstone. Required if you want to dim with setSwitch().

async disconnect()

Tell the Crownstone to disconnect from you. This can help if your Bluetooth stack does not reliably disconnect.

async lockSwitch(lock: bool)

Lock the switch. If locked, its switch state cannot be changed.

async reset()

Restart the Crownstone.

State module

This is used to get state variables from the Crownstone. [https://github.com/crownstone/bluenet/blob/master/docs/PROTOCOL.md#state-packet-1]

The modules contain groups of methods. You can access them like this:

import asyncio
from crownstone_ble import CrownstoneBle

# initialize the Bluetooth Core
ble = CrownstoneBle()

async def example():
    # set the switch state using the control module
    await ble.connect(address)
    switchstate = await ble.state.getSwitchState()
    await ble.disconnect()

loop = asyncio.get_event_loop()
loop.run_until_complete(example())

async getSwitchState()

Get the switch state as SwitchState class.

async getTime()

Get the time on the Crownstone as a timestamp since epoch in seconds. This has been corrected for location.

Event bus

API

once(TopicName: string, functionPointer)

This will subscribe for a single event. After this event, the listener will be removed automatically. It still returns a unsubscriptionId if you want to cleanup before the event occurs.

subscribe(TopicName: string, functionPointer)

Returns a subscription ID that can be used to unsubscribe again with the unsubscribe method

unsubscribe(subscriptionId: number)

This will stop the invocation of the function you provided in the subscribe method, unsubscribing you from the event.

Events

These events are available for the BLE part of this lib:

BleTopics.newDataAvailable

This is a topic to which events are posted which are unique. The same message will be repeated on the advertisement and the rawAdvertisement packets.

BleTopics.rawAdvertisement

This topic will broadcast all incoming Crownstone scans, including those that do not belong to your sphere (ie. can't be decrypted with your keys).

BleTopics.advertisement

This topic will broadcast all incoming Crownstone scans which belong to your sphere (ie. which can be decrypted with your keys).

Data format

All these events contain the same data format:

class ScanData:

    def __init__(self):
        self.address       = None    # this is the handle of the device that broadcast the advertisement. This is usually a MAC address, but on OSX it is a handle.
        self.rssi          = None    # the signal strength indicator
        self.name          = None    # name of the device
        self.operationMode = None    # CrownstoneOperationMode enum (SETUP, NORMAL, DFU, UNKNOWN)
        self.serviceUUID   = None    # the UUID of the scanned service
        self.deviceType    = None    # type of Crownstone
        self.payload       = None    # See below.
        self.validated     = None    # Whether your provided keys could decrypt this advertisement

These fields are always filled. The payload will differ depending on what sort of data is advertised. You can see all possible types here. These payloads all have a type field which is defined here. Payloads come in these flavours:

Usage

You can obtain the eventBus directly from the lib:

from crownstone_ble import BleEventBus, BleTopics

# simple example function to print the data you receive
def showNewData(data):
    print("received new data: ", data)

# Set up event listeners
subscriptionId = BleEventBus.subscribe(BleTopics.newDataAvailable, showNewData)

# unsubscribe again
BleEventBus.unsubscribe(subscriptionId)

Common issues

Bluetooth on Linux

If bluetooth seems stuck, try:

sudo rfkill block bluetooth
sudo rfkill unblock bluetooth

License

Open-source license

This software is provided under a noncontagious open-source license towards the open-source community. It's available under three open-source licenses:

License: LGPL v3 License: MIT License: Apache 2.0

Commercial license

This software can also be provided under a commercial license. If you are not an open-source developer or are not planning to release adaptations to the code under one or multiple of the mentioned licenses, contact us to obtain a commercial license.

Contact

For any question contact us at https://crownstone.rocks/contact/ or on our discord server through https://crownstone.rocks/forum/.