The (python) hub is used for controlling, monitoring, and communicating with the badges. The code was tested mainly on Ubuntu (14 & 16) and Raspbian. In this document, we mostly assume Ubuntu for a development environment, and Raspberry Pi (Raspbian and HypriotOS) for deployment.
In order to simplify setup and deployment, the hub code can now be wrapped in a Docker container.
There are two main modes of operation -
- Standalone - in this mode, the hub loads a list of badges from a static files and writes data to local files. This mode is useful for testing, development, and when you only need a single hub
- Server - in server mode, the hub communicates with a server (openbadge-server). It will read the list of badges, and send back information such as badge health and collected data
Important notes:
- When using multiple hubs, it's important to set up NTP properly so that the time on the hubs is synchronized. Unsynchronized clocks will lead to significant data loss and data corruption
- When running the hub on Raspberry Pi, the hub will modify system parameters in order to (significantly) speed up Bluetooth communication. These settings might affect the communication with other Bluetooth devices, and therefore we do not apply these changes to non-raspberry pi machines
- Docker uses different base images for Ubuntu and Raspbian, and therefore there are different .yml files for different operating systems
To use the hub in standalone mode, you need to create two files under the config folder
- devices.txt - list of member badges. These badges will collect proximity and audio data
- devices_beacon.txt - list of beacons badges. These badges will only broadcast their IDs
You can refer to "devices.txt.example" and "devices_beacons.txt.example" as a reference for the file structure. Important notes:
- Make sure you provide all members and beacons with the same project id (otherwise they will not see each other)
- By convention, member badges should have an id between 1 and 15999. Beacon ids should be between 16000 and 32000
- Choose different project ids for different projects that are running at the same time. This will prevent id conflicts
- For project id, pick a number between 1 and 254. Avoid using project id 0 since this is the default value for ibeacons
Next, use docker-compose to run the hub itself. You can either use the dev_ubuntu.yml (for linux, mac or windows) or dev_jessie.yml (if you are using raspberry pi). For example:
docker-compose -f dev_ubuntu.yml build
docker-compose -f dev_ubuntu.yml up
For convenience, we mount the local source files, data, logs and config directories as volumes in docker. This allows faster builds and easier access to the data generated in this mode.
Note - by default, docker will start the hub in standalone mode. However, you can override the command parameters:
docker-compose -f dev_ubuntu.yml run openbadge-hub-py -m server pull
If you choose to run the hub in server more, remember to create a .env file and set the parameters accordingly. See the next section for more information.
In order to get an interactive shell for the hub container, you need to overwrite the entrypoint:
docker-compose -f dev_ubuntu.yml run --entrypoint /bin/bash openbadge-hub-py
For deployment, we are going to assume Raspberry Pi as a platform. The following sections explain how to setup the raspberry pi, and then how run the hub code using Docker.
It seems that Hypriot has some issues with Pi Zero W (Bluetooth won't start). Therefore, it's better to use Raspbian until they fix the problem.
Download the latest Jessie lite.
The default username and password for Hypriot are pi/raspberry
Now we use flash to write the image to your SD card. If you are using Ubuntu, the SD card will likely be /dev/mmcblk0. If you are not sure, you can omit the --device flash, and it will show you a list of devices. Also, note that we are setting the hostname of the machine using this command
flash --device /dev/mmcblk0 2017-04-10-raspbian-jessie-lite.img
Now, we'll need to turn on SSH and change the hostname. We'll do that by altering the following files on the SD card:
- First, mount the boot partition and main partition
- Create a file call "ssh" under the boot partition
- Edit /etc/hostname in the main partition and replace "raspberrypi" with your hostname
- Unmonut both partitions
- If you need wifi, you can look here for instructions on how to set it up https://wiki.brewpi.com/getting-started/raspberry-pi-docker-install#install-raspbian
Place the SD card in your raspberry pi and power it up.
Copy your SSH public key to the raspberry pi. If you don't have a public one, follow these instructions https://help.github.com/articles/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent/#generating-a-new-ssh-key
ssh-copy-id -oStrictHostKeyChecking=no -oCheckHostIP=no pi@badgepi-xx
Run the following command to change the id of the operating system (this is required for docker-machine):
ssh pi@badgepi-xx sudo sed -i \'s/ID=raspbian/ID=debian/g\' /etc/os-release
Connect to raspberry pi, and run the following commands:
- ssh pi@badgepi-xx
- change your password using passwd
- extend the file system (sudo raspi-config --expand-rootfs), then reboot
- change the timezone (sudo dpkg-reconfigure tzdata)
- DO NOT RUN update & upgrade before installting docker. It causes issues (sudo apt-get update && sudo apt-get upgrade -y)
Double check that your hubs sync their time with a NTP server. Unsync clocks will lead to data corruption and loss
Now, latest versions os docker-machine has some issues with raspbian - docker-machine will fail without an obvious error. To fix it, you'll need to do the following:
ssh pi@badgepi-xx sudo sed -i \'s/ID=debian/ID=raspbian/g\' /etc/os-release
ssh pi@badgepi-xx sudo 'curl -sSL https://get.docker.com | sh'
ssh pi@badgepi-xx sudo sed -i \'s/ID=raspbian/ID=debian/g\' /etc/os-release
Then follow the instructions below for setting up with docker-machine.
Create a .env file (use the env.example file from the root directory as a template) and change the server address, port and key:
- BADGE_SERVER_ADDR : server address (e.g. my.server.com)
- BADGE_SERVER_PORT : port
- APPKEY : application authentication key (needs to match APPKEY in your server configuration)
Use docker-machine to setup Docker on your raspberry pi (it will use your SSH key to connect): ''' docker-machine create --engine-storage-driver=overlay --driver generic --generic-ssh-user pi --generic-ip-address badgepi-xx.yourdomain.com badgepi-xx '''
Note - in the latest docker version (true for 2017/07/07), there's a bug. Try adding the following to the create command: ''' --engine-install-url=https://web.archive.org/web/20170623081500/https://get.docker.com '''
Make the new machine the active machine:
eval $(docker-machine env badgepi-xx)
Make sure you are in the openbadge-hub-py directoy, and run docker-compose (it will use docker-compose.yml as default) :
docker-compose build
docker-compose up -d
TBD
This feature is no longer available as a hub command. Instead, use the django admin tool to import badges.
One of the main requirements for the hub is the BlueZ library. Newer version of Ubuntu and Raspbian include a somewhat new version of BlueZ, so just make sure you use a recent release and ensure BlueZ version is >= 5.29. To check which version you are using, type:
bluetoothd --version
Go to Localization options, then:
Locale -> remove en_GB, add en_US.UTF-8, then choose enUS.UTF-8 as default
Keyboard layout -> choose a generic keyboard -> in the next list you'll see only UK keyboards. Go down and choose "other" -> Choose English (US) -> Choose English (US) agian
Ingeneral, follow the instructions on how to setup a regular hub, except:
- Do not expand the file system. It seems that HypriotOS and Jessie both expand it automatically. So in order to turn it off, edit /boot/boot/cmdline.txt and remove the call to init=/usr/lib/raspi-config/init_resize.sh
- Istead, use fdisk to extend it to a smaller partition. You can find more infomration here - http://www.raspberry-projects.com/pi/pi-operating-systems/raspbian/troubleshooting/expand-filesystem-issues . In general:
- sudo fdisk /dev/mmcblk0
- Then press 'p' to see the current partitions on the disk
- Now delete the 2nd partition (it won't actually delete the data on it)
- Press 'd' > Enter
- Press '2' > Enter
- Now re-create it:
- Press 'n' > Enter
- Press 'p' > Enter
- Press '2' > Enter
- Enter the First sector and the same value as the original /dev/mmcblk0p2 partition
- Set the new size. I used +3G to create a 3GB partition (you'll need some space for building the hub images)
- Now press 'p' > Enter to see the new partition setup.
- Finally press 'w' > Enter to write it
- Now reboot: sudo shutdown -r now
- Once its back do the resize: sudo resize2fs /dev/mmcblk0p2
- Use docker-machine to install docker dependencies, etc
- Then run update & upgrade
Then save the image
- See this post for information - https://raspberrypi.stackexchange.com/questions/8305/how-to-make-an-image-img-from-whats-on-the-sd-card-but-as-compact-as-the-or
- make sure partitions are unmounted
- sudo fdisk -l /dev/mmcblk0
- sudo dd if=/dev/mmcblk0 of=openbadge-hub-py.img bs=512 count=<END of second partition + 1>
Burn image into a new SD card
- Use dd, flash or Etcher.io
After you create a copy, make sure to:
- Change the hostname
- Extend the filesystem
Download the Raspbian lite (e.g. 2017-04-10-raspbian-jessie-lite.img) the the offical site.
Install the image on a SD card
- On most operating systems, you can use Etcher (https://etcher.io/)
- More instructions can be found here - https://www.raspberrypi.org/documentation/installation/installing-images/linux.md
Turn on ssh on raspberry pi
- Mount the boot partition of the SD Card
- Create an empty file called ssh
- Unmount
Change the hostname
- Mount the main volume
- Change /etc/hostname
- Unmount
Copy your SSH public key to the raspberry pi. If you don't have one, follow these instructions
ssh-copy-id -oStrictHostKeyChecking=no -oCheckHostIP=no pi@badgepi-xx
Run the following command to change the id of the operating system (this is required for docker-machine):
ssh pi@badgepi-xx sudo sed -i \'s/ID=raspbian/ID=debian/g\' /etc/os-release
Connect to raspberry pi, and run the following commands:
- ssh pi@badgepi-xx
- sudo raspi-config
- Expand space
- Change password
- sudo apt-get update
- sudo apt-get upgrade
- sudo dpkg-reconfigure tzdata
Double check that your hubs sync their time with a NTP server. Unsync clocks will lead to data corruption and loss