spiread: Read Register from SPI

Reading information from an SPI device is similar to reading information from an I2C device. However, due to the different technical concept, there are some differences, which are discussed below. The selection of a peripheral device is not done via an address but via a dedicated chip select line. Please also note the information on configuring the SPI bus using the systemset command. If the chip select line is specified as the last call parameter when calling with the spiread command, this line is briefly set to 0 (active) when accessing the device and then set back to 1 (inactive) after the read instruction is completed. If the chip select line is not specified in the call, this selection must be made in another way (for example, by hardware wiring).

Note

Don’t forget to configure the device for SPI before accessing it for reading or writing!

Synopsis

Usage: ./spiread [options] chipselect Client app connecting to ‘The-Black-Box’ device for test purposes.

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].
-f, --frequency <period>: Frequency (period) of sending in ms [1000].
-s, --severity <level>: Max severity (fatal|error|warning|info|debug|verbose) of log message.
-F, --file <filename>: Logs to file.
-C, --console <stream>: Console output stream (off|std|err) of log messages [std].
--debug: Report additional debug info in log.
-J, --json: Enable JSON output.
--stop <number>: Stop after received messages.
--error <number>: Stop after received error messages.
-1, --once: Stop after first received message or error.
-r, --register <value>: Initial register/dummy sent to SPI device.
-n, --number <value>: Number of bytes to be read from SPI device [4].
-d, --data <mode>: Interpret data as (array|8|16|32|64) byte.
-e, --endian <endian>: Endianness of the value (little|big) [little].
--read-bit <bit>: Bit position (0-7) to mark read operation.
--multibyte-bit <bit>: Bit position (0-7) to mark multibyte-read.

Arguments:

chipselect Optional chipselect of SPI device.

Examples

In order to cause the peripheral device (“slave”) to send data, it must first be initiated by the “master”. This is done by a dummy byte, which contains, for example, the address of a register to be read. The register is specified by the parameter -r|--register. In addition, the dummy byte mentioned above can indicate whether a register is to be read or written. For this purpose, a corresponding bit in the dummy byte can be set independently of the register address using the parameter --read-bit.

The following examples use an LIS3DH motion sensor from ST. This sensor allows various registers to be read, for example address 0x0f, which returns a unique identifier (0x33). The sensor is connected to the device via output line 0.

The command ./spiread -a blackbox0007.local -s info -1 -r 0x0f -n 1 -d 8 --read-bit 7 0 then produces the example output. We read a single byte.

2025-07-23 13:16:52.226 INFO  Use little endian to interpret data.
2025-07-23 13:16:52.227 INFO  Setting read bit 7.
2025-07-23 13:16:52.241 INFO  SPI-Read '1' byte(s) at chipselect '0', and 1 register(s) every 1000 ms.
2025-07-23 13:16:52.249 INFO  Register: 15|0xf, raw:  51|0x33|0b00110011

By specifying multiple registers, these are read out one after the other and output to the console. The parameter -r must be specified multiple times, e.g. ./spiread -a blackbox0007.local -s info -r 0x23 -r 0x27 -n 1 -d 8 --read-bit 7 --stop 3 -f 100 0

2025-07-23 16:58:32.298 INFO  Use little endian to interpret data.
2025-07-23 16:58:32.298 INFO  Setting read bit 7.
2025-07-23 16:58:32.327 INFO  SPI-Read '1' byte(s) at chipselect '0', and 2 register(s) every 100 ms.
2025-07-23 16:58:32.336 INFO  Register: 35|0x23, raw:   8|0x08|0b00001000
2025-07-23 16:58:32.337 INFO  Register: 39|0x27, raw: 255|0xff|0b11111111
2025-07-23 16:58:32.435 INFO  Register: 35|0x23, raw:   8|0x08|0b00001000
2025-07-23 16:58:32.435 INFO  Register: 39|0x27, raw: 255|0xff|0b11111111
2025-07-23 16:58:32.535 INFO  Register: 35|0x23, raw:   8|0x08|0b00001000
2025-07-23 16:58:32.535 INFO  Register: 39|0x27, raw: 255|0xff|0b11111111

Another special feature is the reading of several consecutive bytes or registers. To ensure that the corresponding register address is incremented after each byte is read, a corresponding bit can be set with the parameter --multibyte-bit in the dummy byte.

In the example, the acceleration can be read out at high resolution as 10 or 12 bits at the sensor. For this purpose, two bytes (the low and high bytes) must be read out for one direction of movement. In the example, the byte at register address 0x28 is read, followed by the value at address 0x29, and converted into a 16-bit value. The command ./spiread -a blackbox0007.local -s info -r 0x28 -n 2 -d 16 --read-bit 7 --multibyte-bit 6 --stop 10 0 outputs:

2025-07-23 17:02:58.665 INFO  Use little endian to interpret data.
2025-07-23 17:02:58.665 INFO  Setting read bit 7.
2025-07-23 17:02:58.665 INFO  Setting multi-byte bit 6.
2025-07-23 17:02:58.682 INFO  SPI-Read '2' byte(s) at chipselect '0', and 1 register(s) every 1000 ms.
2025-07-23 17:02:58.690 INFO  Register: 40|0x28, raw:   144|0x0090
2025-07-23 17:02:59.695 INFO  Register: 40|0x28, raw: 61728|0xf120
2025-07-23 17:03:00.690 INFO  Register: 40|0x28, raw: 63104|0xf680
2025-07-23 17:03:01.694 INFO  Register: 40|0x28, raw:  5232|0x1470
2025-07-23 17:03:02.695 INFO  Register: 40|0x28, raw: 14832|0x39f0
2025-07-23 17:03:03.690 INFO  Register: 40|0x28, raw: 62544|0xf450
2025-07-23 17:03:04.690 INFO  Register: 40|0x28, raw:  7280|0x1c70
2025-07-23 17:03:05.691 INFO  Register: 40|0x28, raw:  6320|0x18b0
2025-07-23 17:03:06.691 INFO  Register: 40|0x28, raw: 11504|0x2cf0
2025-07-23 17:03:07.694 INFO  Register: 40|0x28, raw:  2672|0x0a70

Note

Be sure to check the documentation for the SPI device to see if and how multiple consecutive bytes can be read. Under certain circumstances, the peripheral may implement an automatic increase in the register address after each byte-wise read access.

The following example reads the acceleration in all three directions of movement at the sensor and outputs it as a sequence of individual bytes. Without specifying the parameter --multibyte-bit, the identical address would be read six times. The command ./spiread -a blackbox0007.local -s info -r 0x28 -n 6 -d array --read-bit 7 --multibyte-bit 6 --stop 10 0 outputs the following:

2025-07-23 17:05:36.405 INFO  Use little endian to interpret data.
2025-07-23 17:05:36.405 INFO  Setting read bit 7.
2025-07-23 17:05:36.405 INFO  Setting multi-byte bit 6.
2025-07-23 17:05:36.556 INFO  SPI-Read '6' byte(s) at chipselect '0', and 1 register(s) every 1000 ms.
2025-07-23 17:05:36.564 INFO  Register: 40|0x28, raw: 224|0xe0   0|0x00   0|0x00 255|0xff 240|0xf0  64|0x40
2025-07-23 17:05:37.571 INFO  Register: 40|0x28, raw:  48|0x30   1|0x01  32|0x20 255|0xff 192|0xc0  64|0x40
2025-07-23 17:05:38.563 INFO  Register: 40|0x28, raw:  32|0x20   1|0x01 240|0xf0 254|0xfe  32|0x20  65|0x41
2025-07-23 17:05:39.568 INFO  Register: 40|0x28, raw: 240|0xf0 253|0xfd 176|0xb0  39|0x27 224|0xe0  44|0x2c
2025-07-23 17:05:40.563 INFO  Register: 40|0x28, raw: 176|0xb0  18|0x12  16|0x10  58|0x3a 128|0x80 240|0xf0
2025-07-23 17:05:41.566 INFO  Register: 40|0x28, raw:  96|0x60  49|0x31 144|0x90 232|0xe8  48|0x30  48|0x30
2025-07-23 17:05:42.563 INFO  Register: 40|0x28, raw: 192|0xc0 238|0xee 176|0xb0  38|0x26 160|0xa0 210|0xd2
2025-07-23 17:05:43.563 INFO  Register: 40|0x28, raw: 176|0xb0 243|0xf3   0|0x00  23|0x17 128|0x80  58|0x3a
2025-07-23 17:05:44.568 INFO  Register: 40|0x28, raw: 144|0x90   3|0x03 240|0xf0 227|0xe3  96|0x60  48|0x30
2025-07-23 17:05:45.570 INFO  Register: 40|0x28, raw: 144|0x90   9|0x09  32|0x20 253|0xfd 240|0xf0  64|0x40