Debug mode¶

To switch on the debug mode, where the communication details are printed:

#!/usr/bin/env python3
import minimalmodbus

instrument = minimalmodbus.Instrument('/dev/ttyUSB1', 1, debug = True)
print(instrument.read_register(289, 1))

With this you can easily see what is sent to and from your instrument, and immediately see what is wrong. This is very useful also if developing your own Modbus compatible electronic instruments.

Similar in interactive mode:

>>> instrument.read_register(4097,1)
MinimalModbus debug mode. Writing to instrument: '\n\x03\x10\x01\x00\x01\xd0q'
MinimalModbus debug mode. Response from instrument: '\n\x03\x02\x07\xd0\x1e)'
200.0

The data is stored internally in this driver as Python bytes objects. For example a byte with value 18 (dec) = 12 (hex) = 00010010 (bin) is stored in a bytes object of length one. This can be created by typing b'\x12' (which has the length 1). See https://docs.python.org/3/reference/lexical_analysis.html#string-and-bytes-literals for details on escape sequences.

For more information about hexadecimal numbers, see https://en.wikipedia.org/wiki/Hexadecimal.

Note that the letter A has the hexadecimal ASCII code 41, why the string '\x41' prints 'A'. The Latin-1 encoding is used (on most installations?), and the conversion table is found on https://en.wikipedia.org/wiki/Latin_1.

The bytes objects can look pretty strange when printed, as values 0 to 31 (dec) are ASCII control signs (not corresponding to any letter). For example ‘vertical tab’ and ‘line feed’ are among those. To make the output easier to understand, print the representation, repr(). Use:

print(repr(bytestringname))

Registers are 16 bit wide (2 bytes), and the data is sent with the most significant byte (MSB) before the least significant byte (LSB). This is called big-endian byte order. To find the register data value, multiply the MSB by 256 (dec) and add the LSB.

Error checking is done using CRC (cyclic redundancy check), and the result is two bytes.

Example¶

We use this example in debug mode. It reads one register (number 5) and interpret the data as having 1 decimal. The slave has address 1 (as set when creating the instrument instance), and we are using MODBUS function code 3 (the default value for read_register()):

>>> instrument.read_register(5,1)

This will be displayed:

MinimalModbus debug mode. Writing to instrument: '\x01\x03\x00\x05\x00\x01\x94\x0b'

In the section ‘Modbus implementation details’ above, the request message structure is described. See the table entry for function code 3.

Interpret the request message (8 bytes) as:

Displayed	Hex	Dec	Description
`\x01`	01	1	Slave address (here 1)
`\x03`	03	3	Function code (here 3 = read registers)
`\x00`	00	0	Start address MSB
`\x05`	05	5	Start address LSB
`\x00`	00	0	Number of registers MSB
`\x01`	01	1	Number of registers LSB
`\x94`	94	148	CRC LSB
`\x0b`	0b	11	CRC MSB

So the data in the request is:

Start address: 0*256 + 5 = 5 (dec)

Number of registers: 0*256 + 1 = 1 (dec)

The response will be displayed as:

MinimalModbus debug mode. Response from instrument: '\x01\x03\x02\x00º9÷'

Interpret the response message (7 bytes) as:

Displayed	Hex	Dec	Description
`\x01`	01	1	Slave address (here 1)
`\x03`	03	3	Function code (here 3 = read registers)
`\x02`	02	2	Byte count
`\x00`	00	0	Value MSB
`º`	ba	186	Value LSB
`9`	37	57	CRC LSB
`÷`	f7	247	CRC MSB

Out of the response, this is the payload part: \x02\x00º (3 bytes)

So the data in the response is:

Byte count: 2 (dec)

Register value: 0*256 + 186 = 186 (dec)

We know since earlier that this instrument stores a temperature of 18.6 C as 186. We provide this information as the second argument in the function call read_register(5,1), why it automatically divides the register data by 10 and returns 18.6.

Special characters¶

Some ASCII control characters have representations like \n, and their meanings are described in this table:

`repr()` shows as	Can be written as	ASCII hex	ASCII dec	Description
`\t`	`\x09`	09	9	Horizontal Tab (TAB)
`\n`	`\x0a`	0a	10	Linefeed (LF)
`\r`	`\x0d`	0d	13	Carriage Return (CR)

It is also possible to write for example ASCII Bell (BEL, hex = 07, dec = 7) as \a, but its repr() will still print \x07.

More about ASCII control characters is found on https://en.wikipedia.org/wiki/ASCII.