Package: tfmpi2c
tfmpi2cA Python module for the Benewake TFMini-Plus Lidar sensor in I2C modeTheTFMini-Plusis largely compatible with theTFMini-Sand therefore that device is able to use this module.  One difference is that upon command to change communication mode, such asSET_I2C_MODEorSET_SERIAL_MODE, theTFMini-Plusswitches mode immediately, whereas theTFMini-Srequires a subsequentSAVE_SETTINGcommand before the change takes place.  This module isnot compatiblewith theTF-Lunain I2C mode.  This module is alsonot compatiblewith theTFMini, which is an entirely different product with its own command set and data structure.From hardware v1.3.5 and firmware v1.9.0 and above, theTFMini-Plusinterface can be configured in either UART (Serial) or I2C (two-wire) communication mode.  This module isonlyfor the I2C mode.Internally, the device samples at about 4KHz.  It presents frames of data to the interface at a programmable rate from 0 up to about 10KHz.  The default data-frame rate is 100Hz.  "Standard" data-frame rates are: 0, 1, 2, 5, 10, 20, 25, 50, 100, 125, 200, 250, 500, and 1000Hz.  Single data-frames can be obtained by setting the frame rate to 0 and sending aTRIGGER_DETECTIONcommand.After a getData() command, three module variables are updated:●distDistance to target in centimeters. Range: 0 - 1200●fluxStrength or quality of return signal or error. Range: -1, 0 - 32767●tempTemperature of device chip in code. Range: -25°C to 125°CInstalled with the module is atestsfolder that contains an example python script,tfmpi2c_test.py.
All of the code for this module and the test script is richly commented to assist with understanding and in problem solving.I2C mode operationThis module supportsonlythe I2C communication interface.   It is up to the user to ensure that the device is set to that mode.To configure the device for I2C communication, a command must be sent using the UART interface.  This reconfiguration should be made prior to the device's service installation, either by the serial GUI test application and command code supplied by the manufacturer, or by using the example script included with thetfmpluspython module to send aSET_I2C_MODEcommand.The device will remain in I2C mode after power has been removed and restored.  The only way to return to serial mode is with theSET_SERIAL_MODEcommand.  Even aRESTORE_FACTORY_SETTINGScommand will NOT restore the device to its default, UART communication interface mode.TheTFMini-Plusfunctions like an I2C slave device.  The default address is0x10(16 Decimal) but programmable with theSET_I2C_ADDRESScommand and a parameter in the range of1to127.  The new setting will take effect immediately and permanently without aSAVE_SETTINGScommand.  ARESTORE_FACTORY_SETTINGScommand will restore the default address.  The I2C address can be set while still in serial communication mode or, if in I2C mode, the test scripttfmpi2c_test.pyincluded with the module can be used to test and change the address.Threetfmpi2cmodule functionsThree main functions are defined in the module.  Status code, command and parameter variables are also declared.begin( portNumber, devAddress)passes the I2C port number and I2C bus device address to the module, tries to open the port, performs a quick write operation and returns a boolean value indicating successful completion.getData()commands the device to transmit one data-frame, reads the data-frame and extracts the three measurement data values.  It sets the errorstatusbyte code and returns a boolean value indicating function 'pass/fail'.sendCommand( cmnd, param)sends a coded command and a parameter to the device.  It sets thestatuserror code byte and returns a boolean 'pass/fail' value.  A proper command (cmnd) must be selected from the module's list of twenty defined commands.  A parameter (param) may be chosen from the module's list of defined parameters (such as data-frame rate) or entered directly (such as device I2C address).An erroneous parameter can block communication and there is no external means of resetting the device to factory defaults.Any change of device settings must be followed by aSAVE_SETTINGScommand or else the modified values may be lost when power is removed.SYSTEM_RESETandRESTORE_FACTORY_SETTINGSdo not require aSAVE_SETTINGScommand.Using the I/O modes of the deviceThe so-called I/O modes are not supported in this module.  Please do not attempt to use any I/O commands that you may find to be defined in this module.The I/O output mode is enabled and disabled by this 9 byte command:5A 09 3B MODE DL DH ZL ZH SUCommand byte number:00x5A:  Header byte, starts every command frame10x09:  Command length, number of bytes in command frame20x3B:  Command number3    MODE:0x00: I/O Mode OFF, standard data output mode0x01: I/O Mode ON, output: near = high and far = low0x02: I/O Mode ON, output: near = low and far = high4    DL: Near distance lo order byte of 16 bit integer5    DH: Near distance hi order byte6    ZL: Zone width lo byte7    ZL: Zone width hi byte8   SU: Checkbyte (the lo order byte of the sum of all the other bytes in the frame)If an object's distance is greater than the Near distance (D) plus the Zone width (Z) then the object is "far."If the distance is less than the Near distance (D) then the object is "near".The Zone is a neutral area. Any object distances measured in this range do not change the output.The output can be set to be either high when the object is near and low when it's far (Mode 1); or low when it's near and high when it's far (Mode 2).The high level is 3.3V, the low level is 0V.FinallyBenewake is not very forthcoming about the internals, but they did share this:Some commands that modify internal parameters are processed within 1ms.  Some commands require the MCU to communicate with other chips may take several ms.  And some commands, such as saving configuration and restoring the factory settings need to erase the FLASH of the MCU, which may take several hundred ms.And also:1- the measuring frequency of the module should be 2.5 times larger than the IIC reading frequency.2- the iic reading frequency should not exceed 100hzSince the Data-Frame Rate is limited to 1000Hz, this condition implies a 400Hz data sampling limit in I2C mode.  Benewake says sampling should not exceed 100Hz.  They don't say why; but you might keep that limitation in mind when you consider using the I2C interface.