Package: shimmer-listener
shimmer-listenerThis is a project that started from the idea of having a general library that interacted with shimmer apps for tinyos,
inspired from the python demo scripts that can be found inside the sub-directories of thetinyos shimmer apps repository.Contentsshimmer-listenerContentsAboutPresentation protocolInstallationWindowsDebian-likeUsageDocumentationBt Master exampleCallbacksConsole Scriptsshimmer-printershimmer-btslaveAboutThis library allows you to connect to a Shimmer2 mote via Bluetooth both in Master and Slave mode, interacting with it
via the shimmer-apps precedently introduced (even if it's possible to create custom interactions).For now, there's only support for the BluetoothMasterTest app for Master-mode motes. For what concerns Slave-mode motes,
a small initialization protocol (thepresentationprotocol) is used to let the master node know about the data format
used by the mote.The received data can be handled via a data processing function that has to be passed at init time, where you define
what to do with each instance of incoming data (more on this in the example below).Presentation protocolThe presentation protocol is just a small protocol through which a BT Slave Shimmer describes the data frames that
are to be expected when a BT Master initiates a connection. Its structure is the following:#define MAX_FMT_LEN 10#define MAX_STR_LEN 10#define MAX_KEY_NUM 10typedefcharkey_string[MAX_STR_LEN];typedefstruct{uint8_tframesize;uint8_tchunklen;charformat[MAX_FMT_LEN];key_stringkeys[MAX_KEY_NUM];}frameinfo;To let your nesC app implement this protocol, just copy this C snippet into a header file or directly into the
nesC app implementation, create an instance of frameinfo containing your metadata and send it as the first Bluetooth
message (in Bluetooth.connectionMade).The struct fields refer to:framesize, the size of a single frame, meaning the buffer size that you periodically forward to the BT Master.chunklen, the size of one chunk of the frame, a contiguous unit of related data packed into the frame.format, the format of the data packed into the chunk, this refers to thepython 3 struct library format.keys, a list of keys describing each sensed data packed into a chunk.e.g.A Shimmer2r streaming accelerometer + battery data, packs the data as four 16 bit instances in an 8 B chunk. A full
buffer is 120 B wide, containing a total of 15 8 B chunks.Then we'll have:framesize = 120 Bchunklen = 8 Bformat = "hhhh" (h = short int aka 2 B integer in python struct terms)keys = {"accel_x", "accel_y", "accel_z", "batt"}InstallationIf you have any problems installing or building a version of pybluez for your target platform, I have a repository hosting some pre-compiled wheels for different python version and platforms,you can find the wheels here.WindowsYou need to have Microsoft Visual C++ installed in order to build a wheel for pybluez during the installation process.GetVisual Studio Installerhere, go to Workloads and install the whole Build Tools for C++ suite, which is the first option in the top left corner.Then, you can just:pipinstall.IMPORTANTDuring testing on Win10 with Python 3.7 and 3.8, using pybluez 0.23, strange runtime errors (OSError) started popping out. For now, if this happens, the only thing that seems to work 100% of the times is installing by cloning the repository and using the setup.py script as suggested by @demanbart inthis comment:gitclonehttps://github.com/pybluez/pybluezcdpybluez
pythonsetup.pyinstallDebian-likeN.B. Ubuntu for Raspberry PiWhen trying to make the library work on Ubuntu 20.10 for Raspberry Pi,
you should just install the following package:sudoaptinstallpi-bluetoothThis was tested using a Rpi 4.Other Debian-likeThe library uses pybluez, so you will probably have to installlibbluetooth-devandbluez.
On debian-like:sudoaptinstalllibbluetooth-devbluezClone the repo or download a pre-built wheel from the release section, then:pipinstall.# if you cloned the repopipinstall<wheel-name>.whl# if you downloaded the wheelIn order to run the program you have to set bluez to run in compatibility mode, add your user to the bluetooth
group and modify some other setting. I put everything in the set_bt.sh script so that you can just execute:chmod+xsetup_bt.sh
sudo./setup_bt.shThe script is based on the instructions contained in these two stackoverflow responses, and the full credit
for it goes to the authors of these answers. If something is not working, I advise you to directly
refer to these two links.Compatibility modeSetting permissionsUsageIf you are on a debian-like system, your machine will be discoverable in the bluetooth
network by using:sudohciconfighci0piscanDocumentationFull documentation is accessible athttps://abathargh.github.io/shimmer-listener.Bt Master exampleThis is an example of the simplest application that just prints the incoming data instances in Master Mode, with
a slave mote that runs its app that implements the shimmer-listener presentation protocol:fromshimmer_listenerimportbt_init,bt_listen,bt_close,BtModedefprocess_data(mac,data):print(f"Data from{mac}:{data}")bt_init(mode=BtMode.MASTER)try:bt_listen(message_handle=process_data)exceptKeyboardInterrupt:bt_close()You can take a look at theExamplesdirectory and at the_console_scriptsmodule for some practical examples.CallbacksA series of callbacks can be used and set as properties to intercept certain events:on_connect(mac: str, info: frameinfo) -> NoneCalled when a mote identified bymacsuccesfully connects. All the information
regarding the exchanged data format, obtained throughthe presentation protocolare
accessible viainfo.on_message(mac: str, frame: Dict[str, Any]) -> NoneCalled when a message is received from a mote identified bymac. The message is
returned as a dict with the keys previously obtained from thepresentation protocol.on_disconnect(mac: str, lost: bool) -> NoneCalled when a mote identified bymacdisconnects. Iflostis true, the disconnect
event happened because the connection has been lost.fromshimmer_listenerimportbt_init,bt_listen,BtModedefon_connect(mac,info):print(f"BT MAC{mac}: received presentation frame,{info}")defon_disconnect(mac,lost):iflost:print(f"BT MAC{mac}: connection lost")else:print(f"BT MAC{mac}: disconnecting")defon_message(mac,data):print(f"BT MAC{mac}: got{data}")bt_init(mode=BtMode.MASTER)bt_listen(connect_handle=on_connect,message_handle=on_message,disconnect_handle=on_disconnect)Console ScriptsThe following executable applications are shipped with the library and can be used once you install it.shimmer-printerThis is am executable that can be used to quickly check if your devices successfully work with the app. It just prints
every data frame it receives.shimmer-printershimmer-btslaveA simple application encapsulating the original example of the btMasterTest TinyOS app. By using it,
you start an app as a slave device connecting to the shimmer (in this case, the BT Master).shimmer-btslave