...
Gliffy name AP Bridge Diagram
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:
| No Format |
|---|
$ sudo apt-get install python2.7 python2.7-dev supervisor stunnel4 ntp
$ sudo pip install configobj pyzmq protobuf pyserial |
| Info |
|---|
The pyzmq Python package requires a compiler and the Python development package (headers and library) to build a Python extension. |
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 Include Page
...
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.
| No Format |
|---|
$ sudo update-apc-config.py auto |
...
The update-apc-config.py script can also be used to perform manual configuration of the AP Bridge instances as described in the Include Page
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 following lines supervisor configuration must be added to the supervisor configuration 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:
| No Format |
|---|
[unix_http_server]
file=/var/run/supervisor_server.sock
chmod=0660
chown=dust:dust |
In the include section, add:
| No Format |
|---|
[include]
files=/opt/dust-apc/etc/supervisor.conf.d/*.conf |
To restart supervisor:
| No Format |
|---|
$ 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.
...
Refer to the commands section of the Include Page
...
- 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 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.
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
...
- .
...
- 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 is required by the console interface to the AP Bridge and several configuration scripts.
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.
...
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
...
| No Format |
|---|
$ 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