Read an I2C register from a CODESYS function block

What you need

• A CODESYS project whose runtime runs on a Linux target with an I2C bus, and the bus number. Bus 1 in the case below.
• The i2c library. In the Library Manager, Add Library, search for i2c, add it.
• An I2C master in the Devices tree: right-click I2C, Add Device, I2C master. Raw register access needs no devicedesc.xml and no device library.
• The device datasheet: the 7-bit slave address, the register map, the byte order of multi-byte registers, the scale factor, and the write-cycle time.
• Terminal access to the same target, for the i2cget reference read and the cross-checks later.

Take the reference reading at the terminal first

1. Run i2cget -y 1 0x36 0x04 w. The 1 is the bus, 0x36 the 7-bit address, 0x04 the register, and w asks for a 2-byte word. Drop the w for a 1-byte register.
2. Add -f when a kernel driver already claims the address.
3. Read the result. 0x7c4d came back in the case this article follows, so the wiring, the address and the bus number are good. Write that word down: the function block has to reproduce it. If the command fails, fix the hardware, the address or the bus before any PLC code. A function block cannot succeed where i2cget fails.

I2C is an open-drain bus, so the terminal tools and the runtime can both use it while the PLC runs. That gives you a live cross-check in both directions: write with i2cset and read the value back in the block, then write from the block and read it back with i2cget.

Confirm the address in the datasheet before any i2cset line. A write to the wrong address lands on some other chip on the same bus and changes one of its registers.

The function block: pointer write, then read

Declare the block's data like this:

• usiAddress : USINT := 16#36; the 7-bit slave address
• byReg : BYTE := 16#04; the register pointer
• baBuffer : ARRAY[0..1] OF BYTE; the two data bytes
• nLen : DINT; how many bytes the read returned
• wRaw : WORD; the packed word
• rValue : REAL; the scaled engineering value

Then, in this order:

1. Put the register number in byReg. The pointer is one byte on this device, from the register map.
2. Send it as a one-byte write: I2C_master.write(usiAddress, ADR(byReg), 1);. This sets the device's internal pointer.
3. Read the data as its own transaction: nLen := I2C_master.read(usiAddress, ADR(baBuffer), 2);
4. Gate every later line on nLen = 2. Both bytes arrived. Any other value means the device did not acknowledge or the transfer came back short, so check the address form, the bus selected in the I2C master device, and the pull-up resistors.
5. Pack the word high byte first: wRaw := MEM.PackBytesToWord(baBuffer[1], baBuffer[0]);. The first byte the device sends is the low byte, the same convention i2cget w reports.
6. Scale per the datasheet. The voltage register on this HAT counts 78.125 µV each, so rValue := wRaw * 78.125 / 1000000; gives volts.

Pass buffers by pointer, always. I2C_master.write(16#68, 16#15, 1) hands the value 16#15 to the runtime where it expects a memory address, so no register byte reaches the bus. Declare the register as a BYTE variable and pass ADR(byReg).

Both calling styles you will meet in example code reach the same master: the positional form above, and the named form (usiAddress :=, pbyBuffer :=, nBufferLen :=) inside a block declared EXTENDS i2c, which calls SUPER^() at the top of its body.

Two calls, two transactions. A minority of devices want one combined transaction with a repeated start between the pointer write and the read, and refuse the two-stop form; the timing section of the datasheet says which kind you have.

Example: reading the UPS word at 16#36, register 16#04

Inputs:

• Bus 1, 7-bit address 16#36 and register 16#04, from the working i2cget -y 1 0x36 0x04 w command.
• Read length 2 bytes, because the command ends in w.
• Terminal reference 0x7c4d, taken before any PLC code ran.
• 78.125 µV per count, the datasheet scale for the voltage register 16#02.

Rule in words: one write carrying the single pointer byte, one read of two bytes, a gate on the returned length, and a pack with the high byte first.

Arithmetic:

• The pointer write I2C_master.write(16#36, ADR(byReg), 1) with byReg := 16#04 puts 04 on the bus and stops.
• The read returns nLen = 2, with baBuffer[0] = 16#4D and baBuffer[1] = 16#7C, because the low byte arrives first.
• wRaw := MEM.PackBytesToWord(baBuffer[1], baBuffer[0]) gives 16#7C4D = 124 × 256 + 77 = 31821.

Result: wRaw holds 16#7C4D, the same word the terminal printed, so the transaction matches the reference end to end.

Decision: change byReg to 16#02 and rerun the same six steps for the voltage. The datasheet says whether that register is one scaled word or an integer byte plus a fraction byte. If your block returns 16#4D7C the two pack arguments are swapped; 0 means the read never completed, so go back to step 4.

Check it worked

Then leave the PLC running and probe the same register with i2cget. The bus is open-drain, so both can work at once, and the two readings must match at the same moment. That comparison catches a block whose pointer write runs only on the first call: the device then serves whatever register the last transaction left.

Write a register in one transaction

A register write is a single call whose buffer carries the register byte first and the data bytes behind it:

1. abWrite : ARRAY[0..2] OF BYTE; for a 16-bit value.
2. abWrite[0] := 16#15; the register.
3. abWrite[1] := DWORD_TO_BYTE(dwValue); the low data byte.
4. abWrite[2] := DWORD_TO_BYTE(SHR(dwValue, 8)); the high data byte.
5. I2C_master.write(16#68, ADR(abWrite), 3); one transaction, length 3: 1 register byte plus 2 data bytes.

Swap positions 1 and 2 in the buffer when the datasheet wants the high data byte first. The same mapping turns any i2cset block write into a call: a line that sends 13 data bytes after register 0x02 takes one buffer of 14 bytes and a length of 14.

Three mistakes break writes:

• Register in one write and data in a second. The second transaction's first byte lands in the device as another register address.
• A buffer declared as an array of WORD and filled with byte values. Every element occupies 2 bytes, and on a little-endian target 16#15 leaves as 15 00, shifting every byte behind it.
• A read-back issued immediately after the write. Parts with an internal write buffer stay busy for the datasheet's write-cycle time, several ms on EEPROM-style devices, and drop the read until it elapses.

Raw calls or a device description

Raw calls fit one or two simple register maps: this UPS HAT, a temperature sensor. A device with dozens of registers and a power-up configuration sequence is better served by a device description, where the register map is written once instead of at every call site. Watch for the moment a third configuration register joins the code; that is the move point.

Recommendation: read simple register-mapped devices with the pointer-write-then-read pattern above, gate every read on a returned length of 2, and keep the byte order in one packing call; move to a device description when the device needs a multi-register configuration sequence at power-up.

Once rValue comes out in real units, put it where people act on it: display the value in a visualization puts the number on the operator page, and log the variables to a database keeps the history. If the number belongs on a screen the whole floor reads, live factory data display: signage or dashboard settles which kind of screen that is.

Questions