Developer Hub Setup

Any connected device created with an Afero ASR requires an Afero Hub to communicate with the cloud. Options for an Afero Hub include a dedicated Afero Secure Hub, a smartphone running the Afero mobile app, or the Afero Hub Software package, which allows you to create your own standalone hub. We refer to the latter as an Afero Developer Hub, or Developer Hub for short. Our first release is for Raspberry Pi, or any other ARM-based computer system running Debian Linux.

This Raspberry Pi release includes the following:

  • Afero Hub Software - Software daemon that provides communication between Afero powered devices and the internet (via the Linux system's internet connectivity).
  • Beetle - Software daemon that provides communication between the Afero Hub Software daemon and BlueZ, the Linux Bluetooth stack.

To set up an Afero Developer Hub, please use the information in the sections below:

Caveats and Considerations

  • Raspberry Pi requires Raspbian version 2016-03-18 only, for now.
    • Available from raspberrypi.org.
    • Newer versions of Raspbian have incompatible BlueZ software.
    • We expect a future version of either Raspbian or the Afero Hub Software will lift this restriction.
  • Use at your own risk.
  • Your mileage may vary.

Requirements

Please note the hardware and operating system requirements listed below.

Hardware Requirements

  • ARM-based systems running Debian Linux or any Debian variant:
    • Raspberry Pi 3 (Raspbian version 2016-03-18 only)
      • No additional hardware is required.
    • Raspberry Pi 1 or 2 Model B or B+ (Raspbian version 2016-03-18 only)
    • C.H.I.P. Single-Board Computer (from Next Thing Co.)
      • Standalone C.H.I.P. board or Pocket C.H.I.P. is supported.
      • Any flavor of Version 4.4 is supported (Headless, GUI, or Pocket ChipOS).
      • No additional hardware is required.
    • Other ARM-based Debian Linux systems should also work, but they have not been tested.
      • As long as you have Bluetooth hardware supported by BlueZ.
      • Any internet connectivity is supported.

We will be adding support for other small computing systems as demand and time permits.

The Afero Hub Software is not particularly platform- or architecture-specific and should work on other comparable systems. We have tested most extensively with the Raspberry Pi Model 3; we recommend using that system for your Developer Hub.

Raspbian OS Requirement

The Afero Hub Software packages are only supported on the Raspberry Pi running the Raspbian OS, and (for now) only release 2016-03-18 of the Raspbian OS.

  1. Download the 2016-03-18 version of Raspbian from raspberrypi.org.
  2. Write the OS image to an SD card. For assistance, please read the Raspberry Pi documentation for Windows, macOS, or Linux.
  3. IMPORTANT! After booting the SD card in your Pi, you must do the following:
    1. Run the command sudo raspi-config, making sure to select option 1 (Expand Filesystem).
    2. Reboot your Pi.
    3. Proceed to the installation of the Hub Software package, below.

Installing the Afero Hub Software

You can install the Afero Hub Software in either of two ways. The first, via APT repository, is preferred.

Installing the Hub Software via APT Repository (Recommended)

Afero provides a Debian Repository for the packages we publish. If you add our repository to your system’s Advanced Packaging Tool (APT) sources list, you can install and update packages through the normal Debian package tools, such as aptitude and apt-get.

Run the following commands to download a script that will add Afero to your APT sources:

$ wget https://cdn.afero.io/repo/deb/addrepo.sh
$ bash ./addrepo.sh
  • This script adds the Afero repo information and signing key to your system configuration.
  • Select y to run apt-get update as part of the script. This will take a few minutes to run.
$ sudo apt-get install afero-hub

This will fetch the afero-ble and afero-hub packages as well as any other prerequisite packages you may need. These packages use supervisor(1) to launch and monitor their processes, so that utility will be installed if you don’t already have it.

During installation, you will be prompted to accept the Afero Developer Terms of Service, which is the license that covers your use of the Afero ble and hub packages.

Skip down to Adding the Virtual-Hub Device to Your Account to continue.

Installing the Hub Software Manually

If you don’t wish to use our package repository, or if you’re installing these packages offline, you may download them manually from the following URLs:

If you intend to install these packages offline, you will also need to download the supervisor, qrencode, and bluetooth packages, either from a connected Debian system (with the command: sudo apt-get download supervisor bluetooth qrencode) or fetch them online from https://packages.debian.org/jessie/allpackages/.

Install these packages with the following commands:

$ sudo dpkg -i supervisor*.deb qrencode*deb bluetooth*deb
$ sudo dpkg -i afero-ble*.deb

You will be prompted to accept the Afero Developer Terms of Service, which is the license that covers your use of the Afero ble and hub packages.

$ sudo dpkg -i afero-hub*.deb

Continue with Adding the Virtual-Hub Device to Your Account.

Adding the Virtual-Hub Device to Your Account

The installation of the Hub Software package will create a virtual-hub device that you can connect to your Afero account by scanning a QR code, just as you do with other devices such as Modulo.

The steps are listed below:

  1. Accept Terms of Service - During installation, you must accept the Afero Developer Terms of Service before the packages will install. The document is available to read during the package installation, or you may find the latest version online at https://www.afero.io/legal#developer.
  2. Scan QR code with mobile app - The package installation will present a QR code on your screen. Launch the Afero mobile app on your smartphone, and tap Add Device to add a device to your account, then scan the QR code.

    If the QR code won’t scan for some reason, tap Manually Add Device and type the alphanumeric Association ID listed below the QR code.

The software will then connect to the Afero Cloud to associate the Hub Software with your account.

At this point, installation is complete, and your hub is ready to use!

Managing the Afero Hub Software

Starting, Stopping, and Restarting the Hub Software

The Afero Hub Software provides two daemons, beetle and hubby (process name of Afero Hub Software), which are managed through the supervisor(1) utility. They automatically start when the package is installed, and also when the system boots, but they can be controlled manually as well.

Use the following command to display the state of the two daemons:

$ sudo supervisorctl status

You will see output similar to:

beetle         RUNNING    pid 8324, uptime 5 days, 2:50:44
hubby          RUNNING    pid 8325, uptime 5 days, 2:50:44

If hubby does not say RUNNING but instead says STARTING or BACKOFF, it is possible that your Hub Software configuration has been damaged. Launch the mobile app, select your hub, then tap Settings/Remove Device. Then run the following command to re-create a QR code to re-scan and attach the Hub Software to your account again:

$ sudo dpkg-reconfigure afero-hub

You should not, under normal circumstances, have to manually stop and restart the Hub Software daemons; but if you do, the following commands will do the trick:

To stop the daemons, use:

$ sudo supervisorctl stop hubby beetle

To manually start the daemons, use:

$ sudo supervisorctl start hubby beetle

Managing the Virtual-Hub Device

If for some reason you remove the virtual-hub device from your Afero account, or if the virtual-hub stops working, you can easily re-add it to the same or another Afero account, without re-installing the software. To do this, run the following command on your system:

$ sudo dpkg-reconfigure afero-hub

You’ll be asked if you want to re-build the hub configuration:

  • Answer no if you removed the virtual-hub device, and simply want to re-add it. Answering no will cause the existing virtual-hub device’s QR code to be displayed. Simply scan the QR code to add it to an Afero account.
  • Answer yes if your virtual-hub device stops working, especially if there are messages in /var/log/syslog that indicate the device’s configuration has been damaged. Answering yes will rebuild the configuration, and allow you to add the hub-device by scanning a new QR code.
    If the old virtual hub remains in the mobile app after you’ve added the new device, select the old device hex and tap Remove Device to remove it from your account.

Removing, Reinstalling, and Upgrading the Hub Software

You can remove, re-install, and upgrade these packages using normal Debian package commands.

  • To remove the software but keep your configuration intact (to preserve your virtual-hub device), run:

    $ sudo apt-get remove afero-hub afero-ble
  • To remove the software along with your associated configuration, first remove the virtual-hub device from your Afero account via the mobile app, then run:

    $ sudo apt-get remove --purge afero-hub afero-ble
  • If you installed the packages manually (rather than through apt-get), do one of the following:
    • To remove the software but leave the virtual-hub device intact, run:

      $ sudo dpkg -r afero-hub afero-ble
    • To remove both the package and the virtual-hub device, run:

      $ sudo dpkg -P afero-hub afero-ble
  • When we release a new version of the Hub Software, you can upgrade the packages through the normal apt-get process:

    $ sudo apt-get install --only-upgrade afero-ble
    $ sudo apt-get install --only-upgrade afero-hub

    Upgrading the packages will preserve the virtual-hub device attached to your account.

Getting Support

Support for the Afero Hub Software is provided through the Afero Developer Forums at https://forum.afero.io. More sensitive questions (e.g., concerning your credentials) can be sent to developer@afero.io.

The Afero Hub Software daemons write information to /var/log/syslog so if you have any issues with the operation of the Hub Software please be sure to save a copy of /var/log/syslog before you contact us.