systemset: Setup Hardware Interfaces
The system configuration can be permanently changed with the command systemset. Either a completely new
configuration or only changes to the existing configuration can be specified via the command line.
It is possible to create a new configuration for test purposes, but this will not be changed in The-Black-Box.
Synopsis
- Options:
- -h, --help
Displays help on commandline options.
- --help-all
Displays help, including generic Qt options.
- -v, --version
Displays version information.
- -a, --address <host>
Host address of the gateway [localhost].
- -p, --port <port>
Port of the gateway [51955].
- --debug
Report additional debug info in log.
- -s, --severity <level>
Max severity (fatal|error|warning|info|debug|verbose) of log message.
- -i, --in, --digital <pin>
Set pin to digital input.
- -o, --out <pin>
Set pin to digital output.
- --analog <pin>
Set pin to analog input.
- --falling <pin>
Set pin to falling edge interrupt input.
- --rising <pin>
Set pin to rising edge interrupt input.
- --both <pin>
Set pin to both edges interrupt input.
- --hardwired
Set the hardwired pins (#20-#23)
- -u, --use
Use current (retrieve from remote) as base configuration.
- -d, --dont
Don’t write configuration to black box; just show.
- --enable-pwm <channel>
Enable pwm channel with id.
- --disable-pwm <channel>
Disable pwm channel with id.
- --frequency-pwm <frequency>
Set the frequency [Hz] of PWM.
- --sampling-time <time>
Set the ADC sampling time (0-7); 0: fastest.
- --oversampling <n>
Enable ADC oversampling 2^n (0-8).
- --bitshift <bit>
Add bits for result of oversampling (0-4).
- --i2c0 <speed>
Speed I2C0 (disable|normal|fast|fastplus).
- --i2c1 <speed>
Speed I2C1 (disable|normal|fast|fastplus).
- --uart0 <baudrate>
Baudrate UART0 (disable|9600|14400|…|256000).
- --uart1 <baudrate>
Baudrate UART1 (disable|9600|14400|…|256000).
- --can <baudrate>
Baudrate CAN bus (disable|33.3|83.3|100|125|250|500|1000).
- --extended
CAN identifiers are extended (29 bits).
- --overwrite
Overwrite can filter settings.
- --filter-mask <filter>
CAN filter in mask mode ‘identifier,mask’ for id.
- --filter-identifier <filter>
CAN filter in identifier mode ‘identifier1,identifier2’ for id.
- --spi <speed>
Transfer SPI (disable|312.5|625|…|40).
- --mode-spi <mode>
Mode SPI (0|1|2|3).
- --lsbfirst-spi
LSB instead of MSB first for transmission.
- --bitlength-spi <bits>
Bitlength SPI (4|5|…|16).
- Arguments:
name name or identifier of the-black-box.
Examples
By specifying the parameter -u|--use, it is possible to retain the previous configuration and only specify the changes.
To do this, the current configuration is first read out, the changes made by the user are taken into account and
the changed configuration is written back.
The parameter -d|--dont is provided to check the changes to the configuration without changing The-Black-Box.
The changed configuration is displayed on the screen without the system being changed.
The parameter --hardwired makes it possible to set the four integrated, fixed-defined inputs or outputs
of The-Black-Box at once. If these pins are not otherwise specified in the configuration, they cannot be used. This applies, for example,
to the user LED and the integrated buzzer.
It is possible to personalize the device by specifying a name as the last parameter of the command line.
Note
If the configuration is changed, the server is automatically restarted and The-Black-Box the system is configured accordingly.
Configure Digital and Analog Pin
A pin can be configured in four ways: as a digital -i|--in|--digital or analog --analog input, as a
digital -o|--out output and as an interrupt .
An interrupt behaves like a digital input; here, however, a rolling counter is incremented continuously. The
trigger for an interrupt can be either a rising --rising or falling --falling edge at the digital input.
Using --both increments the counter regardless of the type of edge.
To configure several pins of one type, the parameter must be specified several times,
for example by the sequence -i 1 -i 3. It is not possible to specify a comma-separated list or similar.
Note
The possible configuration of a pin depends on the pin itself. This applies in particular to the analog input, which only four pins support.
Using ./systemset -a blackbox2 -s info --in 0 --out 3 --falling 7 -u -d "Michael's Box" the existing
configuration will be updated. In addition to the existing functions the pin 0 is configured as digital
input, pin 3 can be used as digital output and pin 7 acts as counter for falling edge interrupts. The
name of this new configuration is ‘Michael’s Box.’ However due to the -d switch on the command line
the new configuration is not written back the The-Black-Box. The output is given as:
2024-05-22 15:55:53.708 NONE Press Ctrl-C to abort application.
2024-05-22 15:55:53.714 INFO Try to connect to blackbox2@51955...
2024-05-22 15:55:53.714 INFO Read current configuration from black box...
2024-05-22 15:55:53.743 INFO Client is connected...
2024-05-22 15:55:53.745 INFO Session identifier 9, protocol version 0
2024-05-22 15:55:53.749 INFO Received configuration from black box 'the-black-box', Fri May 17 09:24:37 2024 GMT
2024-05-22 15:55:53.750 INFO New configuration will not be written to black box.
2024-05-22 15:55:53.750 INFO Black-Box: 'Michael's Box' - Wed May 22 13:55:53 2024 UTC
2024-05-22 15:55:53.751 INFO Pin0:Digital Input
2024-05-22 15:55:53.751 INFO Pin1:Unknown
2024-05-22 15:55:53.751 INFO Pin2:Unknown
2024-05-22 15:55:53.751 INFO Pin3:Digital Output
2024-05-22 15:55:53.752 INFO Pin4:Unknown
2024-05-22 15:55:53.752 INFO Pin5:Unknown
2024-05-22 15:55:53.752 INFO Pin6:Unknown
2024-05-22 15:55:53.752 INFO Pin7:Falling Edge Interrupt
2024-05-22 15:55:53.752 INFO Pin8:Unknown
2024-05-22 15:55:53.752 INFO Pin9:Unknown
2024-05-22 15:55:53.752 INFO Pin10:Unknown
2024-05-22 15:55:53.753 INFO Pin11:Unknown
2024-05-22 15:55:53.753 INFO Pin12:Unknown
2024-05-22 15:55:53.753 INFO Pin13:Unknown
2024-05-22 15:55:53.753 INFO Pin14:Unknown
2024-05-22 15:55:53.753 INFO Pin15:Unknown
2024-05-22 15:55:53.753 INFO Pin16:Unknown
2024-05-22 15:55:53.754 INFO Pin17:Analog Input
2024-05-22 15:55:53.754 INFO Pin18:Analog Input
2024-05-22 15:55:53.754 INFO Pin19:Unknown
2024-05-22 15:55:53.754 INFO Pin20:Falling Edge Interrupt
2024-05-22 15:55:53.754 INFO Pin21:Digital Output
2024-05-22 15:55:53.754 INFO Pin22:Analog Input
2024-05-22 15:55:53.754 INFO Pin23:Digital Output
2024-05-22 15:55:53.755 INFO Pin24:Unknown
2024-05-22 15:55:53.755 INFO Pin25:Unknown
2024-05-22 15:55:53.755 INFO Pin26:Unknown
2024-05-22 15:55:53.755 INFO Pin27:Unknown
2024-05-22 15:55:53.755 INFO Pin28:Unknown
2024-05-22 15:55:53.755 INFO Pin29:Unknown
2024-05-22 15:55:53.755 INFO Pin30:Unknown
2024-05-22 15:55:53.756 INFO Pin31:Unknown
2024-05-22 15:55:53.756 INFO PWM Frequency: 1220.7 Hz (0/65535)
2024-05-22 15:55:53.756 INFO Channel0:Unknown
2024-05-22 15:55:53.756 INFO Channel1:Unknown
2024-05-22 15:55:53.756 INFO Channel2:Unknown
2024-05-22 15:55:53.756 INFO Channel3:Unknown
2024-05-22 15:55:53.756 INFO I2C 0:Unknown
2024-05-22 15:55:53.757 INFO I2C 1:Unknown
2024-05-22 15:55:53.757 INFO SPI:Unknown
2024-05-22 15:55:53.757 INFO UART 0:Unknown
2024-05-22 15:55:53.757 INFO UART 1:Unknown
2024-05-22 15:55:53.757 INFO CAN:Unknown
Without the -d parameter the configuration is written back to the device. The complete
command is then ./systemset -a blackbox2 -s info --in 0 --out 3 --falling 7 -u "Michael's Box".
2024-05-22 15:56:38.019 NONE Press Ctrl-C to abort application.
2024-05-22 15:56:38.021 INFO Try to connect to blackbox2@51955...
2024-05-22 15:56:38.021 INFO Read current configuration from black box...
2024-05-22 15:56:38.137 INFO Client is connected...
2024-05-22 15:56:38.139 INFO Session identifier 10, protocol version 0
2024-05-22 15:56:38.159 INFO Received configuration from black box 'the-black-box', Fri May 17 09:24:37 2024 GMT
2024-05-22 15:56:38.174 INFO Client is connected...
2024-05-22 15:56:38.176 INFO Session identifier 11, protocol version 0
2024-05-22 15:56:38.176 INFO Send new configuration to black box 'Michael's Box', Wed May 22 13:56:38 2024 GMT
Configure PWM Output
Up to four PWM outputs are supported, which are switched on by the parameter --enable-pwm or
switched off by the parameter --disable-pwm. It is also possible to configure the frequency (if required)
of the PWM signal using --frequency-pwm.
Note
The frequency of the PWM signal is identical for all outputs. This cannot be configured individually.
In order to enable the pwm channel 0 using a frequency of 50 Hz the command
is ./systemset -a blackbox2 -s info -u --enable-pwm 0 --frequency-pwm 50 and outputs
2024-05-22 15:58:50.812 NONE Press Ctrl-C to abort application.
2024-05-22 15:58:50.813 INFO Try to connect to blackbox2@51955...
2024-05-22 15:58:50.813 INFO Read current configuration from black box...
2024-05-22 15:58:51.013 INFO Client is connected...
2024-05-22 15:58:51.015 INFO Session identifier 13, protocol version 0
2024-05-22 15:58:51.031 INFO Received configuration from black box 'the-black-box', Wed May 22 13:57:52 2024 GMT
2024-05-22 15:58:51.047 INFO Client is connected...
2024-05-22 15:58:51.048 INFO Session identifier 14, protocol version 0
2024-05-22 15:58:51.048 INFO Send new configuration to black box 'the-black-box', Wed May 22 13:58:51 2024 GMT
Configure I2C Bus
The device supports the use of two independent I2C buses, the speed of which can be set via the
parameter --i2c0 resp. --i2c1.
Configure SPI Bus
The device contains an single SPI bus (master mode) that allows one or more connected peripheral devices to be controlled. The connections for SPI are located on the left of the three 12-pin connectors: MOSI, MISO, CLK. In some cases, the interfaces of SPI devices are labeled with an alternative notation: SDI and SDO. In this case, MOSI must be connected to SDI and MISO to SDO using an appropriate cable. In addition, the selection of the external SPI device (chip select) must be configured. There are several options for this, which are described below.
The SPI can be configured using several parameters --spi, --mode-spi, --lsbfirst-spi, and --bitlength-spi.
The bus speed is set using the parameter --spi. Eight options are supported: 312.5 or 625 kbit/s, 1.25,
2.5, 5, 10, 20, or 40 Mbit/s. The mode can also be set (for details on the mode
see https://en.wikipedia.org/wiki/Serial_Peripheral_Interface). Most devices support mode 0 by default. If an LSB
instead of MSB bit order is to be used, the parameter --lsbfirst-spi must be specified. The bit length can also be configured
using --bitlength-spi. A length of 8 bits should be sufficient in most cases.
The chip select signal must be set to select the peripheral component. This signal can be set either by a corresponding output pin of The-Black-Box or by other external circuitry. The corresponding output pin can be specified for the write and read commands.
Note
The chip select line is logically 0 active, i.e., to select a device, the line must be cleared.
In the following example, a sensor is connected via SPI and the device is configured accordingly using the
command ./systemset -a blackbox0007.local -s info -u --spi 1.25 --mode-spi 0 --bitlength-spi 8 -o 0. Pin #0 is used
as the chip select signal. The command ./systemget -a blackbox0007.local -f 0 -s info then displays the successful
configuration.
2025-07-23 12:34:53.151 NONE Press Ctrl-C to abort application.
2025-07-23 12:34:53.152 INFO Try to connect to blackbox0007.local@51955...
2025-07-23 12:34:53.309 INFO Black-Box: 'the-black-box v1.7.0' - Mi 23 Jul 10:31:47 2025 UTC
2025-07-23 12:34:53.309 INFO Pin0:Digital Output
2025-07-23 12:34:53.310 INFO Pin1:Unknown
2025-07-23 12:34:53.310 INFO Pin2:Unknown
2025-07-23 12:34:53.310 INFO Pin3:Unknown
2025-07-23 12:34:53.310 INFO Pin4:Unknown
2025-07-23 12:34:53.310 INFO Pin5:Unknown
2025-07-23 12:34:53.310 INFO Pin6:Unknown
2025-07-23 12:34:53.310 INFO Pin7:Unknown
2025-07-23 12:34:53.310 INFO Pin8:Unknown
2025-07-23 12:34:53.310 INFO Pin9:Unknown
2025-07-23 12:34:53.310 INFO Pin10:Unknown
2025-07-23 12:34:53.310 INFO Pin11:Unknown
2025-07-23 12:34:53.310 INFO Pin12:Unknown
2025-07-23 12:34:53.310 INFO Pin13:Unknown
2025-07-23 12:34:53.310 INFO Pin14:Unknown
2025-07-23 12:34:53.310 INFO Pin15:Unknown
2025-07-23 12:34:53.310 INFO Pin16:Unknown
2025-07-23 12:34:53.310 INFO Pin17:Unknown
2025-07-23 12:34:53.310 INFO Pin18:Unknown
2025-07-23 12:34:53.310 INFO Pin19:Unknown
2025-07-23 12:34:53.310 INFO Pin20:Falling Edge Interrupt
2025-07-23 12:34:53.310 INFO Pin21:Digital Output
2025-07-23 12:34:53.310 INFO Pin22:Analog Input
2025-07-23 12:34:53.310 INFO Pin23:Digital Output
2025-07-23 12:34:53.310 INFO Pin24:Unknown
2025-07-23 12:34:53.310 INFO Pin25:Unknown
2025-07-23 12:34:53.310 INFO Pin26:Unknown
2025-07-23 12:34:53.310 INFO Pin27:Unknown
2025-07-23 12:34:53.310 INFO Pin28:Unknown
2025-07-23 12:34:53.310 INFO Pin29:Unknown
2025-07-23 12:34:53.310 INFO Pin30:Unknown
2025-07-23 12:34:53.310 INFO Pin31:Unknown
2025-07-23 12:34:53.310 INFO PWM Frequency: 1220.7 Hz (0/65535)
2025-07-23 12:34:53.310 INFO Channel0:Unknown
2025-07-23 12:34:53.310 INFO Channel1:Unknown
2025-07-23 12:34:53.310 INFO Channel2:Unknown
2025-07-23 12:34:53.310 INFO Channel3:Unknown
2025-07-23 12:34:53.310 INFO ADC sampling time: 2.5 cycles, oversampling: No, No bit shift
2025-07-23 12:34:53.310 INFO I2C 0:Unknown
2025-07-23 12:34:53.310 INFO I2C 1:Unknown
2025-07-23 12:34:53.310 INFO SPI rate: 1.25 MBit/s:Mode 0:8 bits:MSB First.
2025-07-23 12:34:53.310 INFO UART 0:Unknown
2025-07-23 12:34:53.310 INFO UART 1:Unknown
2025-07-23 12:34:53.310 INFO CAN:Unknown
Configure UART Serial Communication
Configure Controller Area Network (CAN)
To configure the CAN bus, the bus rate must be set using --can and the hardware acceptance filters must be configured using
--filter-mask and/or --filter-identifier. The-Black-Box has an internal 120 Ohm terminator resistor, which
is activated by a hardware-switch.
The parameter --extended is used to process the identifiers of
the CAN messages in extended format (29 instead of 11 bits). A total of 10 individual filter entries are possible.
By specifying the optional parameter --overwrite, the existing entries are overwritten (in combination with the
parameter --use).
Note
If the filters are not configured or configured incorrectly, no messages can be received with the command.
The acceptance filter can be configured and enables two modes:
mask mode using
--filter-mask: Bit mask specifies which messages (identifiers) are accepted. The mask allows certain patterns to be accepted. A set bit in the mask indicates whether the corresponding bit in the identifier (this can be either a one or a zero) is taken into account during filtering. If a bit in the mask is zero, this bit is not taken into account during filtering.identifier mode using
--filter-identifier: Value specifies the identifier that is accepted (exact match).
In both cases, two integers must be entered separated by commas. In the first case one identifier and one mask, in the second case two identifiers.
Note
Make sure that there are no spaces before and after the comma.
In the following example, the filter for receiving CAN messages is configured with the identifiers 0x666 or 1638
and 0x676 or 1654. The baud rate is 100 kbit/s. The two identifiers can be specified explicitly in pairs in
the identifier mode. The corresponding command is ./systemset -a blackbox2 -s info -u --can 100 --filter-identifier 1638,1654.
Alternatively, the filter can also be configured by specifying an identifier and a mask using
./systemset -a blackbox2 -s info -u --can 100 --filter-mask 1638,2031. The two identifiers
0b110’0110’0110 (1638) and 0b110’0111’0110 (1654) only differ in one bit position. The bit mask therefore results
in 0b111’1110’1111 (2031).
In order not to filter out any messages at hardware level, a mask with zeros must be specified as
./systemset -a blackbox2 -s info -u --can 100 --filter-mask 0,0.
Reset Configuration
The command ./systemset -a blackbox2 -s info --hardwired resets the configuration of The-Black-Box to
a defined initial state.
2024-05-22 15:57:52.374 NONE Press Ctrl-C to abort application.
2024-05-22 15:57:52.376 INFO Try to connect to blackbox2@51955...
2024-05-22 15:57:52.579 INFO Client is connected...
2024-05-22 15:57:52.581 INFO Session identifier 12, protocol version 0
2024-05-22 15:57:52.581 INFO Send new configuration to black box 'the-black-box', Wed May 22 13:57:52 2024 GMT