Control-app configuration¶
All configuration files native to the control application are in ini-file format. There are two types of INI files:
Main configuration files: For the various settings of the control application.
Peripheral configuration files: For configuration peripherals, generally sensors or actuators.
Main configuration¶
By default the main configuration file is expected at /etc/control/control.ini. This configuration file contains all general settings. For a reference of all configuration items, please see Control board configuration reference. In addition, if a file named /localstore/.spidr4/control.ini is found, this will be merged with the configuration file. This ‘overlaying’ allows additional settings, or modification of existing settings, specific to a board. Generally /localstore/* is never overwritten, even not when explicity flashing an SD card with a tool like Etcher or dd. This makes it useful for these board-specific modifications, but note that swapping the SD will remove these type of modifications.
When a carrier-board is attached, the contents of the EEPROM on carrier-board is extracted to /tmp/eeprom (see Carrier board configuration). A file carrier.ini is expected in this archive. This file is also merged with the main configuration.
The main configuration includes a reference to the peripheral configuration, which will be discussed in the next section.
Peripheral configuration¶
The peripheral configuration is a configuration file for the peripherals, and is expected in the location /etc/control/peripherals.ini, though this is configurable from the main file. This configuration file is used to load sensors and actuators. Actuators in this cases is quite broad. Anything which is meant to control ‘something’, is an actuator. For example, an i2c multiplexer is an actuator.
Most devices are controlled using i2c, and follow the following general convention:
; required for all peripherals
[<identifier>]
part=<driver part name>
; required for all i2c-based peripherals
bus=<i2c-bus>
addr=<i2c-device-addr>
; only if it is behind a multiplexer
mux_ref=<mux identifier>
mux_idx=<mux port>
; .. other device-specific configurations
As with the configuration, an overlay can be placed as /localstore/.spidr4/peripherals.ini. This can be used to configure board-specific modifications, but note that swapping the SD card will remove these changes.
Second, peripherals can be loaded from the carrier. This uses the same mechanism as the main configuration. When the carrier EEPROM is extracted, it can contain any number of files. One such files is /tmp/eeprom/carrier_prpl.ini, which is loaded in the default /etc/control/peripherals.ini using special ‘embedding’ syntax:
; Carrier INI file reference.
[:/tmp/eeprom/carrier_prpl.ini]
bus=i2c1
mux_ref=board_mux
mux_idx=0
namespace=carrier
This defines all peripherals loaded from carrier_prpl are on i2c bus
Hardware specific configuration¶
The primary MAC EEPROM of the control-board is used to store a number of ‘tags’ in the 128 bytes writable space. Though these tags are free-format, there are a number of predefined (list subject to change):
v1 - Hardware v1 (excludes other v*)
v2 - Hardware v2 (excludes other v*)
si5346 - Uses si5346 instead of the standard si5344
clk49m - Uses 49 MHz instead of 33 MHz clock
This allows persistent tags across firmware updates. Each new control-board should be setup with tags using the hwprop tool. This tool allows configuring of tags, and writing to EEPROM. These hardware tags can be used for control application customization though conditional configuration elements.
In the case of INI files this means hardware specific tags can be added to ANY section, simply by appending the tags to the section name, for example:
; default case
[clock]
part=si5344
bus=i2c0
addr=0x68
cfgfile=/etc/control/si5344spidr4.txt
; 49 Mhz clock case
[clock clk49m]
part=si5344
bus=i2c0
addr=0x68
cfgfile=/etc/control/si5344spidr4_49m.txt
; si5346 clock chip case
[clock si5346]
part=si5346
bus=i2c0
addr=0x60
cfgfile=/etc/control/si5346spidr4.txt
Multiple tags can be added, and the section must be a subset of the hardware property tags of the board for the section to be activated. A matched section will replace the original section, if it exists. None of the original key-values will remain.
For example, in the example above, if clk49m is tag is set, it will replace the [clock] section completely. If multiple conditional sections match, the last section will be used. If there is no original section, the matching section will simply be renamed. For example:
[display ssd1327]
bus=i2c1
addr=0x3d
driver=ssd1327
width=128
height=128
mux_addr=0x70
mux_val=0x04
Will convert to a [display] section if the tag ssd1327 exists. Otherwise it will be removed.
If a section contains multiple tags, they have to be a subset of the hardware properties tag-list. For example if you have the hardware has the tags v1, clk49m and si5346 it will not match the section [clock v2 ck49m], but it will match [clock v1 clk49m] or [clock clk49m si5346], or simply [clock v1].