Introduction

This section describes how the reference AP Bridge software is integrated with a Linux system (the target platform in Building the AP Bridge Software) . 

Overview

The AP Bridge software is designed to manage the connection between the VManager software and an AP Mote. This section describes how the AP Bridge software interacts with Linux on the target platform. 

OS integration

The AP Bridge software assumes that it is running on a Linux system and assumes that a variety of OS facilities are available. The AP Bridge software uses the Boost libraries to provide a common framework for some platform-specific operations, such as threading, serial I/O and timekeeping. 

External packages

The AP Bridge software relies on several external packages for essential services. The AP Bridge does not build against these packages, but they must be installed for the AP Bridge to operate properly. These packages are commonly available on Linux distributions and should be installed with the distribution's package manager. 

• stunnel and openssl are used to encrypt network communication.
• supervisor provides a central service for starting and stopping processes.
• NTP provides time synchronization. 
• Python 2.7 and several additional Python packages are required by the Console interface to the AP Bridge and several configuration scripts. 
  • configobj is used by the configuration scripts for reading and updating the AP Bridge configuration files. 
  • pyzmq and protobuf are used for inter-process communication between the AP Bridge and AP Bridge Console processes. 

On the Raspberry Pi, these packages can be installed using: 

$ sudo apt-get install python2.7 python2.7-dev supervisor stunnel4 ntp
$ sudo pip install configobj pyzmq protobuf pyserial

Serial devices

The AP Bridge software interacts with the I/O of the AP Mote through serial devices: The Serial API port of the AP Mote is used for general communication between the AP Bridge and the AP Mote, and another I/O is used to reset the AP mote.  In the DC2274 reference design, the reset line of the AP Mote is connected to the FTDI interface chip, such that writing to the TX line of the reset port sends a hardware reset to the AP Mote.  If the Linux system connects to the Serial API port directly, a GPIO is used to drive the AP mote reset line.

The AP Bridge software requires that the path to the serial device for the AP Mote API port and the AP Mote reset line be defined in the configuration file. 

If the reference FTDI/USB interface is used to communicate with the AP Mote, then configuration of the serial devices can be made in the AP Bridge configuration file. If the physical connection between the AP Mote and the AP Bridge hardware is changed, then changes may need to be made to the SerialPort.cpp source code. 

In addition, the CLI port of the AP Mote should be exposed (either tunneled through the Linux system or directly) so that a user can interact with the AP Mote CLI. The CLI port is not used by the AP Bridge software, but it is necessary for certain AP Mote configuration and diagnostics. 

Auto-detection

The reference AP Bridge software contains scripts to automatically detect the connection of an FTDI-based AP Mote device and create the AP Bridge configuration files. This detection mechanism requires the Linux udev system. The udev rules for automatically detecting the AP Mote are installed by the update-apc-config.py script. 

$ sudo update-apc-config.py auto

Manual configuration

The update-apc-config.py script can also be used to perform manual configuration of the AP Bridge instances as described in the VManager AP Bridge User's Guide. 

Startup and shutdown

In the reference software distribution for the Raspberry Pi, the AP Bridge is managed by the supervisor process controller. 

The AP Bridge installs its supervisor configuration under APC_HOME/etc/supervisor.conf.d. In order for the system-level supervisor to pick it up, the supervisor configuration must be updated in /etc/supervisor/supervisord.conf. These changes make it possible for the AP Bridge processes to be managed by supervisor and for the dust user to control the processes without using sudo. After making the configuration changes, the supervisor daemon must be restarted. 

In the unix_http_server section, update to:

[unix_http_server]
file=/var/run/supervisor_server.sock
chmod=0660
chown=dust:dust

In the include section, add:

[include]
files=/opt/dust-apc/etc/supervisor.conf.d/*.conf

To restart supervisor:

$ sudo service supervisor restart

When started in the default configuration, the AP Bridge launches a script that waits for NTP to synchronize time before launching the main AP Bridge process, named apc. The NTP service should be started before the AP Bridge is started.  

Secure communication

The AP Bridge software does not implement the TLS security layer itself. Instead, to implement secure communication with the VManager, the AP Bridge uses stunnel running on the same device. To secure the AP Bridge connection, stunnel is configured to listen to local TCP port 9100 and connect to TCP port 9101 on the VManager host. From the AP Bridge, stunnel establishes a connection to the remote VManager and negotiates the cipher suite with stunnel on the VManager. Stunnel uses the host's openssl library, so both the stunnel and openssl packages should be kept up to date on the VManager and AP Bridge systems. If you do not specify a specific set of security suites to use, stunnel will revert to openssl defaults. Configuring openssl for a particular security suite, or operation in FIPS mode, is left to the system operator.

The stunnel certificate on the VManager is a self-signed certificate that is not verified on the client. Similarly, the VManager stunnel configuration does not verify client certificates. Stunnel can be configured to verify certificates, but the configuration details are left to the system operator. 

AP Bridge Console

The AP Bridge Console is a Python program that provides a command line interface for interacting with the running AP Bridge software. 

Refer to the commands section of the VManager AP Bridge User's Guide for a complete list of available commands.

Permissions

The AP Bridge binary runs as the dust user. To interact with the AP Mote, the AP Bridge software must be able to read and write to the AP Mote's serial devices. On the Ubuntu distribution, this means the dust user must be a member of the dialout group. 

Environment variables

File system layout

The AP Bridge software expects to be able to read and write to directories under APC_HOME. 

• The AP Bridge binaries are installed in APC_HOME/bin. 
• The AP Bridge software reads its configuration from APC_HOME/conf. The AP Bridge process(es) are managed by configuration files stored in APC_HOME/etc/supervisor.conf.d. 
• The AP Bridge generates log files to APC_HOME/logs. Log files are automatically rotated when they reach a certain size.
• The AP Bridge writes certain runtime information to APC_HOME/var/run. 
  

Network connectivity

If the system is being built with APs physically separated from the VManager system, then the simplest implementation is to connect all the devices to the same Ethernet network. Any method that provides a reliable TCP/IP connection between the APs and VManager can be used including WiFi, or cellular. The network connectivity must be consistent and reliable so that the APs can communicate constantly with the VManager. The VManager will consider an AP to be lost if its connectivity is interrupted for 30 seconds. In the event that an AP is lost, the VManager will immediately reassign all mote paths through the remaining APs and motes that are only connected through the lost AP may be lost as well. If the AP returns later on, then the VManager will slowly re-integrate the AP into the network topology through normal optimization cycles. 

To minimize network churn and loss of service, it is critical to build networks with solid connectivity between the APs and the VManager. 

NTP time synchronization

In-network time is mapped to system time at network start, via the master AP (or master APs if GPS is being used). If the AP(s) is/are connected to the system hosting the VManager, then the VManager and AP Bridge software will be synced to a single time base. If the AP is installed on a separate device, then both the VManager system and the AP Bridge host should be synced to the same time base. This can be accomplished using NTP (or GPS when using this method for AP timing), but the details of how time synchronization is configured is left to the system operator. The VManager and each of the AP Bridges connected to it should synchronize to the same time servers. In addition, the AP Bridge software should only be started after the system time has been synced by NTP. The AP Bridge package contains a script apc_launcher.py that waits for NTP to synchronize before launching the main apc process. 

In the event that the VManager system and AP Bridges are not synchronized, the SmartMesh IP network will continue to work normally, however mapping network time to UTC time accurately may be impossible. 

GPS connectivity

The VManager 1.1 release provides support for using a GPS device for time keeping in the AP Bridge software. In the reference configuration for a GPS-enabled AP Bridge, the GPS device's PPS signal is used to feed both the AP Mote and the NTP software running on the AP Bridge device. The AP Bridge software uses GPSd to read the time from the GPS device and to track whether the GPS device is properly synchronized. 

TODO: describe how GPSd is configured, AP Bridge parameters to connect to GPSd

TODO: describe special configuration of NTP to enable GPS inputs, special configuration of RPi kernel to enable PPS GPIO

Troubleshooting

TODO: migrate troubleshooting to a new page

Verifying device time synchronization

Run ntpdate on the AP Bridge device(s) and the VManager to check the offset of each device from the time server. ntpdate will query the configured time servers and print an offset. The offsets should be less than 1 second if the device is synced with the time server. If there are variations between devices by more than 1 second, it is likely that the system is not synced and the time information shown by the VManager API will not be aligned with the true UTC time. 

For example, the device below shows a 26 second offset from the pool of time servers provided by the NTP project:

$ ntpdate -q pool.ntp.org
...
25 Mar 14:09:49 ntpdate[12569]: step time server 132.163.4.101 offset -26.481737 sec

TODO: list the GPS verification steps

References

• supervisor
• stunnel
• pyzmq
• protobuf
• NTP
• GPSd