i2cread: Read Register from I2C

This command i2cread makes it possible to apply one or more registers -r|--register to a connected I2C device perodically. It is possible to specify the data type -d|--data of the register.

Synopsis

Usage: ./i2cread [options] device

Client app connecting to ‘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]

--debug

Report additional debug info in log.

-s, --severity <level>

Max severity (fatal|error|warning|info|debug|verbose) of log message.

-r, --register <value>

Register address of the I2C device [-1].

-b, --bus <value>

I2C bus device connected to [0].

-n, --number <value>

Number of bytes to be read from I2C device [4].

-d, --data <mode>

Interpret data as (array|8|16|32|64) byte.

--value <value>

Value (8|16|32|64 bit) to be expected.

--xor <bitmask>

Value to be xor’ed .

--and-not <bitmask>

Value to be and-not’ed.

Arguments:

device address of I2C device.

Examples

In this example we use the push button (connected to the second I2C bus) with the following register map: https://cdn.sparkfun.com/assets/learn_tutorials/1/1/0/8/Qwiic_Button_I2C_Register_Map.pdf.

Read Single Register Once

Using ./i2cread -a blackbox2 -s info -f 0 -r 0 -b 1 -n 1 -d 8 111 the register 0 (8 bit value) will be queried once. Any 8-bit values are output to the console in binary form in addition to decimal and hexadecimal representation.

2024-05-27 21:23:33.287 NONE  Press Ctrl-C to abort application.
2024-05-27 21:23:33.298 INFO  Client is connected...
2024-05-27 21:23:33.303 INFO  Session identifier 83, protocol version 0
2024-05-27 21:23:33.303 INFO  I2C-Read '1' byte(s) at bus '1', device id '111', and 1 register(s) every 0 ms.
2024-05-27 21:23:33.309 INFO  Register:  0, data:  93|0x5d|0b01011101

In this example at register address 0, you will find the value 0x5d (identifier of the button).

The command ./i2cread -a blackbox2 -s info -f 0 -r 1 -b 1 -n 2 -d 16 111 outputs the register 1 (version information of the button) as 16 bit value using -d 16 (two bytes).

2024-05-27 21:39:19.431 NONE  Press Ctrl-C to abort application.
2024-05-27 21:39:19.442 INFO  Client is connected...
2024-05-27 21:39:19.447 INFO  Session identifier 84, protocol version 0
2024-05-27 21:39:19.447 INFO  I2C-Read '2' byte(s) at bus '1', device id '111', and 1 register(s) every 0 ms.
2024-05-27 21:39:19.455 INFO  Register:  1, data:   258|0x0102

Alternatively ./i2cread -a blackbox2 -s info -f 0 -r 1 -b 1 -n 2 -d array 111, the value can be output as a byte sequence using -d array without interpretation of any data type.

2024-05-27 21:44:42.601 NONE  Press Ctrl-C to abort application.
2024-05-27 21:44:42.617 INFO  Client is connected...
2024-05-27 21:44:42.623 INFO  Session identifier 85, protocol version 0
2024-05-27 21:44:42.623 INFO  I2C-Read '2' byte(s) at bus '1', device id '111', and 1 register(s) every 0 ms.
2024-05-27 21:44:42.630 INFO  Register:  1, data: 2|0x02 1|0x01

Note

A maximum of 8 consecutive byte values can be read with one request (-n 8). This corresponds to a 64-bit value.

Polling Register Set

In this example ./i2cread -a blackbox2 -s info -f 1000 -r 27 -r 29 -n 2 -d 16 -b 1 111, the two registers 27 (LED pulse cycle time) and 29 (LED pulse off time) are queried with a period of 1s. Both registers have a width -n|--number of 2 bytes and the values are displayed as 16-bit decimal and hexadecimal numbers -d|--data. It should be noted that only the initial value and changes are output to the console.

2024-05-27 21:06:21.070 NONE  Press Ctrl-C to abort application.
2024-05-27 21:06:21.119 INFO  Client is connected...
2024-05-27 21:06:21.123 INFO  Session identifier 79, protocol version 0
2024-05-27 21:06:21.129 INFO  Client is connected...
2024-05-27 21:06:21.134 INFO  Session identifier 80, protocol version 0
2024-05-27 21:06:21.134 INFO  I2C-Read '2' byte(s) at bus '1', device id '111', and 2 register(s) every 1000 ms.
2024-05-27 21:06:21.275 INFO  Register: 27, data:  1000|0x03e8
2024-05-27 21:06:21.275 INFO  Register: 29, data:   250|0x00fa
2024-05-27 21:06:41.143 INFO  Register: 27, data:   750|0x02ee
2024-05-27 21:07:14.144 INFO  Register: 29, data:  1000|0x03e8

While the pulse cycle time in this example is shortened from 1000 ms to 750 ms, the pulse off time is extended from 250 ms to 1000 ms.

Note

The specification of the value width -n|--number and the representation as a data type -d|--data must match. If more than one register (using several -r|--register switches at the command line) is read out, the width and representation apply equally to all specified registers.

Auto Stop Mode

It is possible for this application to exit automatically when a certain value has been read from one or more registers. For this purpose, a comparison value (expected value) can be specified with the parameter --value. In addition, an exclusive-or bit operation --xor and an and-not bit operation --and-not can be performed on the read value (actual value). The ì2cread app terminates if the expected value equals to (actual value xor xor-bitmask) and not and-not-bitmask.

In the following example ./i2cread -a blackbox2 -b 1 -s info -r 25 -n 1 -d 8 --value 123 111 the app terminates when the register 25 is set exactly to 123.

2024-06-11 16:29:24.538 NONE  Press Ctrl-C to abort application.
2024-06-11 16:29:24.740 INFO  Client is connected...
2024-06-11 16:29:24.742 INFO  Session identifier 358, protocol version 0
2024-06-11 16:29:24.743 INFO  I2C-Read '1' byte(s) at bus '1', device id '111', and 1 register(s) every 1000 ms.
2024-06-11 16:29:24.743 INFO  Auto-stop mode using value=123, xor=0, andnot=0
2024-06-11 16:29:24.748 INFO  Register: 25, data:   5|0x05|0b00000101
2024-06-11 16:29:47.747 INFO  Register: 25, data:  33|0x21|0b00100001
2024-06-11 16:29:54.747 INFO  Register: 25, data:  11|0x0b|0b00001011
2024-06-11 16:29:56.748 INFO  Register: 25, data:  22|0x16|0b00010110
2024-06-11 16:29:59.748 INFO  Register: 25, data: 123|0x7b|0b01111011
2024-06-11 16:29:59.749 INFO  Expected value(s) found!

Using ./i2cread -a blackbox2 -b 1 -s info -r 25 -n 1 -d 8 --value 8 --xor 8 --and-not 247 111 the command stops when Bit 3 is cleared.

2024-06-11 16:41:04.133 NONE  Press Ctrl-C to abort application.
2024-06-11 16:41:04.340 INFO  Client is connected...
2024-06-11 16:41:04.342 INFO  Session identifier 362, protocol version 0
2024-06-11 16:41:04.343 INFO  I2C-Read '1' byte(s) at bus '1', device id '111', and 1 register(s) every 1000 ms.
2024-06-11 16:41:04.343 INFO  Auto-stop mode using value=8, xor=8, andnot=247
2024-06-11 16:41:04.347 INFO  Register: 25, data: 123|0x7b|0b01111011
2024-06-11 16:41:21.347 INFO  Register: 25, data:  31|0x1f|0b00011111
2024-06-11 16:41:26.347 INFO  Register: 25, data: 160|0xa0|0b10100000
2024-06-11 16:41:26.348 INFO  Expected value(s) found!

In this example the command ./i2cread -a blackbox2 -b 1 -s info -r 25 -n 1 -d 8 --value 192 --and-not 63 111 terminates when Bit 6 and 7 is set.

2024-06-11 16:45:21.708 NONE  Press Ctrl-C to abort application.
2024-06-11 16:45:21.904 INFO  Client is connected...
2024-06-11 16:45:21.905 INFO  Session identifier 365, protocol version 0
2024-06-11 16:45:21.905 INFO  I2C-Read '1' byte(s) at bus '1', device id '111', and 1 register(s) every 1000 ms.
2024-06-11 16:45:21.905 INFO  Auto-stop mode using value=192, xor=0, andnot=63
2024-06-11 16:45:21.910 INFO  Register: 25, data: 160|0xa0|0b10100000
2024-06-11 16:45:46.909 INFO  Register: 25, data:  31|0x1f|0b00011111
2024-06-11 16:45:56.913 INFO  Register: 25, data: 200|0xc8|0b11001000
2024-06-11 16:45:56.915 INFO  Expected value(s) found!