-
Notifications
You must be signed in to change notification settings - Fork 7
[Deprecated] Running the hub in standalone mode
Once you finish programming all of your badges, you can use the badge hub to initialize the badges and periodically pull data. For this version of the badges, we use a Python-based hub to perform these operations. The code was tested mainly on Ubuntu (14.04) and Raspbian.
Every time a badge is turned on, it will wait for a hub to connect and send the current time so it can initialize the badge's internal clock.
You'll need Python 2.7.X, pip and several other libraries:
sudo apt-get install python python-dev libglib2.0-dev python-pip
Another prerequisite (other than using a computer with bluetooth 4.0), is BlueZ 5.23 or higher, preferably 5.29 or higher. The latest Raspbian (Jessie) comes with BlueZ 5.23 wish is not great, but seems to be working. Other version and distributions might not come with BlueZ 5.23+. To check the version on your machine, run:
bluetoothd -v
If you decided to install a new version of BlueZ, you are likely to need to install it from the source. Here's the procedure we have been using. It's been tested on Raspbian Wheezy and Ubuntu 14.04 and seems to be working well.
If you are using Raspbian Jessie, skip to the next section
Install dependencies:
sudo apt-get update
sudo apt-get upgrade
sudo apt-get -y install libdbus-1-dev libdbus-glib-1-dev libglib2.0-dev libical-dev libreadline-dev libudev-dev libusb-dev make
Download and install BlueZ version 5.29 or higher:
wget http://www.kernel.org/pub/linux/bluetooth/bluez-5.37.tar.xz
tar xf bluez-5.37.tar.xz
cd bluez-5.37
mkdir release
./configure --disable-systemd
make -j4
sudo make install
Upgrading BlueZ when an existing 5.XX package already exists is not simple. We have been working on an Ansible script that does that, but it is not ready yet. In the meantime, I recommend reading the following sites for more information:
- https://learn.adafruit.com/install-bluez-on-the-raspberry-pi/installation - tutorial by Adafruit described the installation process of a new version of BlueZ. I believe they miss some steps there
- https://www.element14.com/community/community/stem-academy/microbit/blog/2016/09/16/1-microbit-1-raspberry-pi-3-1-bluez-upgrade-1-huge-headache - a comprehensive description of the upgrade process. It it almost complete, but requires some manual execution of a command each time you reboot
Optional - create a new Python Virtualenv:
cd Place/Where/You/Store/Envs/
virtualenv env
source env/bin/activate
clone the project and install the requirements
git clone https://github.com/HumanDynamics/openbadge-hub-py.git
cd openbadge-hub-py
sudo pip install -r requirements.txt
When starting the hub, it will continuously connect to all badges in range that are listed in the whitelist, update their internal time, give them commands to start recording audio and proximity, and pull data. It is the hub's responsibility to know which data to pull - When sending a pull command data, the hub requests all the data from a specific timestamp onward. In order to know which data to request, the hub keeps a list of timestamps (one for audio, one for proximity) for each badges.
There are two main ways to use the hub - as a standalone machine, or with a backend server. The main difference - in standalone mode the hub uses a configuration file to tell which badges it should connect to, while in server mode the hub connects to the backend server (openbadge-server) to pull a list of devices and synchronize the last timestamps so hubs don't ask for the same data multiple times.
This is the default behavior.
- Go to the Badge hub library: openbadge-hub-py
- Create a file called "device_macs.txt", and enter the MAC addresses of your badges. The format for this file is . Please use the following format for the MAC address: AA:BB:CC:DD:EE:FF
- Start the hub: sudo ./badge_hub.py pull
The pull command continuously scans for badge within range, sends date for uninitialized badges, and pulls data when available. If you wish to run the command in the background, you can try:
nohup sudo ./badge_hub.py pull&
To use the server mode, you first need to install and configure an openbadge server (see the openbadge-server repo). Then:
- Go to the Badge hub library: openbadge-hub-py
- Use the ".env_template" to create a file called ".env" and setup the server address and port
- Start the hub: sudo ./badge_hub.py -m server pull
The pull command continuously scans for badge within range, sends date for uninitialized badges, and pulls data when available. If you wish to run the command in the background, you can try:
nohup sudo ./badge_hub.py -m server pull&
Note - the current hub code will take badges from all projects defined in the server. Future version will limit the hub to see only badges associated to the hub's project
- mode - can be used to determine whether the hub is in standalone or server mode. this option must come BEFORE the pull command (e.g. badge_hub.py -m server pull)
- recording options - can be used to tell the hub which features to activate in the badges - audio, proximity, both or none. The default is both. Example, if you only want proximity scans:
sudo ./badge_hub.py -m server pull -r proximity
The hub has several other useful commands you can use:
- scan - scans for badges and save the scan results to file, together with the signal strength
- sync_all - connects to all the badges in the whitelist and try to set their internal clock
- start_all - connects to all the badges in the whitelist and try to start audio recording and proximity scans
Similarly to the pull command, you can use the "-m server" option to tell the hub to connect to a server.
Note - the file format below is obsolete. This section will be updated soon.
The badge hub stores the data received from each badge in a separate file (each file name is based on the MAC address). Data is stored in CSV format with the following structure:
datetime,voltage,sample length,array of samples
- datetime is in YYYY-MM-DD HH24:MI:SS.fff format. For example: 2016-03-04 12:53:30.250, where 250 is the number of milliseconds
- voltage is the voltage of the battery at the time the sample was taken. When the voltage drops below 2.2V data might be noisy
- Sample length is the time, in milliseconds, that each sample represents (or time between samples). This is typically set to 50ms
- Samples array is an array of bytes, each represents one sample. The spacing between samples always equals sample length
Depending on the version of the firmware you are using, there may be duplicates in the data - data are sent in "chunks", with each chunk holding up to 114 bytes. We allow partial chunks to be sent, and therefore the same chunk maybe be sent several times - sometimes as a partial chunk, and later as a full chunk.