The IMPLib2 API

This part of the documentation covers the public API of the IMPLib2. For more in dept information of the IMPBus2 technology please refere to the official IMPBUS2 Developers Manual.

The Bus Class

class implib2.Bus(port='/dev/ttyUSB0', rs485=False)

The Bus object represents the IMPBus2 master device. It is used to initialize the Bus, set the baudrate and find the connected probes. A simple example of how to initialize and search the bus would be:

>>> from implib2 import Bus, Module
>>> bus = Bus('/dev/ttyUSB0')
>>> bus.sync()
>>> bus.scan()

Parameters:

• port (string) – The serial port to use, defaults to /dev/ttyUSB0
• rs485 (bool) – Set this to True in order to use the way more relaxed rs485 timings. Defaults to False.

find_single_module()

Find a single module on the Bus.

This command is used to identify a single module on the bus which serial number is unknown. It is a broadcast command and serves to get the serial number of the module.

Return type:False or tuple containing the serial number.

get(serno, table, param)

This is the base command for getting some information from the probes. Instead of using this command directly, it’s highly recommendet to use the higher level API commands in Module. Nevertheless here is a small example of how to use this command to request the serial number of a probe:

>>> table = 'SYSTEM_PARAMETER_TABLE'
>>> param = 'SerialNum'
>>> serno = 33912
>>> bus.get(serno, table, param)

Parameters:

• serno (int) – Serial number of the probe to request.
• table (string) – System table containing the requested infomation.
• param (string) – Parameter od row containing the requested infomation.

Return type:

bool

get_eeprom_page(serno, page_nr)

This is the base command for reading a single page of EEPRom data from a particular probe. It is later used within some higher API commands within the Module-Class. For more Information please refer to the description in the EEPRom-Class.

Parameters:

• serno (int) – Serial number of the probe to address.
• page_nr (int) – EEPRom Page to get.

probe_module_long(serno)

This command with will call up the slave which is addressed by its serial number. In return, the slave replies with a complete address block. It can be used to test the presence of a module in conjunction with the quality of the bus connection.

Parameters:serno (int) – Serial number of the probe do connect. Return type:bool

probe_module_short(serno)

This command will call up the slave which is addressed by its serial number. In return, the slave replies by just one byte: The CRC of its serial number. It is the shortest possible command without the transfer of any data block and the only one without a complete address block. It can be used to test the presence of a module.

Parameters:serno (int) – Serial number of the probe do connect. Return type:bool

probe_range(broadcast)

This command is very similar to probe_module_short(). However, it addresses not just one single serial number, but a serial number range. This is done by setting the values of byte 4 to byte 6 of the package header to a broadcast pattern. For more details refer to the explanation at scan().

Parameters:serno (int) – Broadcast address. Return type:bool

scan(minserial=0, maxserial=16777215)

Command to scan the IMPBUS for connected probes.

This command can be uses to search the IMPBus2 for connected probes. It uses the probe_range() command, to address a whole serial number range and in the case of some ‘answers’ from the range it recursively devides the range into equal parts and repeads this binary search schema until the all probes are found.

Note

Searching the IMPBus2

The 3 bytes IMPBus2 serial numbers spans a 24bit [0 - 16777215] address range, which is a whole lot of serial numbers to try. So in order to quickly identify the connected probes the command probe_range() can be used. In order to address more than one probe a a time the header package of the probe_range() command contains a range pattern where you would normaly find the target probes serial number. Example:

range serno:   10010001 10000000 00000000 (0x918000)
range address: 10010001 00000000 00000000
range mark:    00000000 10000000 00000000

As you can see in the example above, the “range serno” from the header package consists of a range address and a range marker. The Range marker is alwayse the most right ‘1’ of the “range serno”:

range min:     10010001 00000000 00000000 (0x910000)
range max:     10010001 11111111 11111111 (0x91ffff)

So all probes with serial numbers between min and max would answer to a probe_range() command with the “range serno” 0x918000. The probes would send the CRC of there serial number as reply to this command. But because the probes share the same bus it is higly possible the replyes are damaged when red from the serial line. So the onoly thing we will know from a probe_range() command is whether or not there is someone in the addressed range. So the next thing to do, if we get something back from the addressed range, is to devide the range into two pices by shifting the range mark right:

range mark:  00000000 01000000 00000000 (new range mark)
lower half:  10010001 00000000 00000000 (old mark gets 0)
higher half: 10010001 10000000 00000000 (old mark gets 1)

So the new “range sernos” (“range address” + “range mark”) are:

lower half:  10010001 01000000 00000000 (0x914000)
higher half: 10010001 11000000 00000000 (0x91c000)

This way we recursively divide the range until we hit the last ranges, spanning only two serial numbers. Than we can query them directly, using the probe_module_short() command.

Parameters:

• minserial (int) – Start of the range to search (usually: 0).
• maxserial (int) – End of the range to search (usually: 16777215).

Return type:

tuple

set(serno, table, param, value, ad_param=0)

This is the base command for sending and storing some information in the tables of the probes. It’s the counterpart of the get() command. Instead of using this command directly, it’s highly recommendet to use the higher level API commands in Module. Nevertheless here is a small example of how to use this command to set the serial number of a probe:

>>> table = 'SYSTEM_PARAMETER_TABLE'
>>> param = 'SerialNum'
>>> serno = 33912
>>> new_serno = 33913
>>> bus.set(serno, table, param, [new_serno])

Parameters:

• serno (int) – Serial number of the probe to address.
• table (string) – System table to store the infomation.
• param (string) – Parameter od row containing the requested infomation.
• value (iterable) – Values to store.

Return type:

bool

set_eeprom_page(serno, page_nr, page)

This is the base command for writing a single page of EEPRom data into a particular probe. It is later used within some higher API commands within the Module-Class. For more Information please refer to the description in the EEPRom-Class.

Parameters:

• serno (int) – Serial number of the probe to address.
• page_nr (int) – EEPRom Page to write.
• page (bytes) – EEPRom page data.

sync(baudrate=9600)

This command synchronises the connected modules to the given baudrate.

The communication between master and slaves can only be successful if they use the same baudrate. In order to synchronise the modules on a given baudrate, the bus master has to transmit the broadcast command “SetSysPara” with the parameter Baudrate on all possible baudrates. There must be a delay of at least 500ms after each command!

Parameters:baudrate (int) – Baudrate to use (1200-2400-4800-9600). Raises:BusError – If baudrate is unknown. Return type:True

wakeup()

This function sends a broadcast packet which sets the ‘EnterSleep’ parameter of the ‘ACTION_PARAMETER_TABLE’ to ‘0’, which actually means to disable the sleep mode of all connected modules. But the real aim of this command is to wake up sleeping modules by sending ‘something’.

Return type:True

The Module Class

class implib2.Module(bus, serno)

The Module object represents a IMPBus2 probe. It is used to provide a easy to use interface for the probe specific commands. It is mostly just a small wrapper around the much more general Bus.set() and Bus.get() commands. To create a Module object you first to supply a Bus object and a serial number. As a quick example we will catch up with the code from Bus and extend that a bit, pretending we have two probes with the serial numbers 10010 and 10011 connected to the bus:

>>> from implib2 import Bus, Module
>>> bus = Bus('/dev/ttyUSB0')
>>> bus.sync()
>>> bus.scan()
(10010, 10011)

Now that we found our two probes lets create the Module objects:

>>> module10 = Module(bus, 10010)
>>> module11 = Module(bus, 10011)

And now, lets use the Module objects to gain some informations from the probes:

>>> module10.get_hw_version()
1.14
>>> module10.get_fw_version()
1.140301
>>> module11.get_hw_version()
1.14
>>> module11.get_fw_version()
1.140301

Parameters:

• bus (Bus) – An instaciated Bus object to use.
• serno (int) – The serial number of the probe to address.

Return type:

Module

get_event_mode()

Command to retrieve the event mode parameter of the probe. For more informations look at set_event_mode().

:raises : ModuleError - If event mode is not known.

Return type:string

get_fw_version()

Command to retrieve the firmware version number of the probe.

Return type:float

get_hw_version()

Command to retrieve the hardware version number of the probe.

Return type:float

get_measure_mode()

Command to retrieve the measure mode parameter of the probe. For more informations look at set_measure_mode().

Raises:ModuleError - If measure mode is not known. Return type:string

get_measurement(quantity='Moist')

This command gets the measured value of the requested quantity. It’s mostly used within a wrapper like get_moisture().

Parameters:quantity (str) – The measure quantity to request. Return type:int or float

get_moisture()

This command is a simple wrapper arrond start_measure(), measure_running() and get_measure().

Return type:float

get_serno()

Command to retrieve the serial number of the probe.

Return type:int

get_table(table)

Spezial Command to get a whole table.

Warning

Not yet implemented!

Basicly you get a whole table, witch means the data-part of the recieved package consists of the concatinated table values. If the table don’t fit into one package the status byte of the header-part will be ‘0xff’. Than you have to wait a bit and recieve packages as long as the status byte is ‘0x00’ again. To extract the concatenated table-values you have to split the data in order of the Parameter-No., the length of each value can is equal to the Parameter-Length.

You can use the parameters GetData, DataSize and TableSize to gain information about the spezific table.

Parameters:table (string) – Table to retrieve from probe. Return type:json

measure_running()

This command checks if the measurement cycle is in progress.

Return type:bool

read_eeprom()

Command to read the EEPROM image from the probe. The image get’s stored into a EEPROM object.

Return type:EEPROM Raises:ModuleError - If length of the constructed EEPRom does not match the length value from the probe table.

set_event_mode(mode='NormalMeasure')

Command to set the the EventMode of the probe. This parameter can be set to six different values:

Note

0. NormalMeasure: Normal measurement Mode.
1. TDRScan: TDRScan Mode.
2. AnalogOut: Used for setting the analog out to a fixed value.
3. ASIC_TC: Mode to perform a ASIC temperature compensation.
4. Self Test: Mode to perform varios self tests.
5. MatTempSensor: Mode to do a material temperatur compensation.

Parameters:mode (string) – The EventMode to use. Return type:bool Raises:ModuleError - If mode is not known.

set_measure_mode(mode='ModeA')

Command to set the measure mode of the probe. There a 3 different measure modes.

Note

ModeA

On Request, the probe checks the parameter StartMeasure in Measure Parameter Table. If the parameter is 0, the probe does nothing. If the parameter is 1, the probe does the measurement and then sets the parameter to 0 again. Setting the parameter to 1 must be carried out through RS485 or IMPBus by an external command.

ModeB

Single, the probe measures once after it is powered on. This mode is normally used in the case that the probe is connected to a data logger which samples the analog output after being powered on.

ModeC

Cyclic, the probe measures cyclically. That means, the probe measures once and sleeps the time SleepTimeInModeC, then it wakes up automatically and repeats the process. This mode is normally aused in casees when the probe is always powered and measures periodically.

Parameters:mode (string) – Mode to use. Return type:bool Raises:ModuleError - If mode is unknown.

set_serno(serno)

Command to change the serial number of the probe.

Parameters:serno (int) – Serial number so use. Return type:bool

set_table(table, data)

Special command to set the values of a hole table.

Warning

Not yet implemented!

You can use the parameters GetData, DataSize and TableSize to gain information about the spezific table.

Parameters:

• table (string) – Name of the table to write.
• data (json) – Table data to write.

Return type:

bool

start_measure()

This command starts a measurement cycle and returns when the measurement is finished. It’s mostly used within a wrapper like get_moisture().

Return type:bool

unlock()

Command to unlock the write protected rows in the probes tables. The unlock key is the CRC + 0x8000 of serial number of the probe. Be aware that the key changes as the serial number is changed.

Return type:bool

write_eeprom(image)

Command to write a new EEPROM image to the probe. The EEPROM image must be an instance of the EEPROM.

Parameters:image (EEPROM) – The Image to write. Return type:bool

The EEPRom Class

class implib2.EEPROM(filename)

This Class represents a simple data structure to hold an EEPROM image. It can be used with Module.write_eeprom() to update the EEPROM image of the probe.