diff --git a/README.md b/README.md index 3a1c7f7..437063f 100644 --- a/README.md +++ b/README.md @@ -37,13 +37,21 @@ This library supports the default, UART (serial) communication interface. For c
### Arduino Library Commands -`begin()` passes a serial stream to the library and returns a boolean value indicating whether serial data is available. The function also sets a public one-byte `status` or error code. Status codes are defined in the library's header file. +`begin()`  passes a serial stream to the library and returns a boolean value indicating whether serial data is available. The function also sets a public one-byte `status` or error code. Status codes are defined in the library's header file. -The `getData( dist, flux, temp)` function passes back three, signed, 16-bit measuremnent data values. It sets the `status` error code byte and returns a boolean value indicating 'pass/fail'. If no serial data is received or no header sequence (`0x5959`) is detected within one (1) second, the function sets an appropriate `status` error code and 'fails'. Given the asynchronous nature of the device, the serial buffer is flushed before reading and the `frame` and `reply` data arrays are zeroed out to delete any residual data. This helps with valid data recognition and error discrimination. +`getData( dist, flux, temp)`  passes back three, signed, 16-bit measuremnent data values. It sets the `status` error code byte and returns a boolean value indicating 'pass/fail'. If no serial data is received or no header sequence (`0x5959`) is detected within one (1) second, the function sets an appropriate `status` error code and 'fails'. Given the asynchronous nature of the device, the serial buffer is flushed before reading and the `frame` and `reply` data arrays are zeroed out to delete any residual data. This helps with valid data recognition and error discrimination. -A `getData( dist)` function is available that passes back only the distance value. +`getData( dist)`  will pass back only the distance value. -`sendCommand( cmnd, param)` sends a 32bit command and a 32bit parameter to the device. It sets the `status` error code byte and returns a boolean 'pass/fail' value. A proper command (`cmnd`) must be selected from the library's list of twenty defined commands. A parameter (`param`) may be entered directly as an unsigned number, but it is better to choose from the Library's defined parameters because **an erroneous parameter can block communication and there is no external means of resetting the device to factory defaults.** +`sendCommand( cmnd, param)`  sends a 32 bit command (`cmnd`) and a 32 bit paramter (`param`) to the device. It will set the `status` error code byte and return a boolean 'pass/fail' value. A `cmnd` must be selected from this library's set of seventeen defined commands. A `param` must always be included. The `param` may be entered directly as an unsigned number, or chosen from the Library's set of defined parameters. For many commands, i.e. `HARD_RESET`, the correct `param` is a `0` (zero). + +`cmnd`   The defined commands are:
+`GET_FIRMWARE_VERSION`, `TRIGGER_DETECTION`, `SOFT_RESET`, `HARD_RESET`, `SAVE_SETTINGS`, `SET_FRAME_RATE`, `SET_BAUD_RATE`, `STANDARD_FORMAT_CM`, `PIXHAWK_FORMAT`, `STANDARD_FORMAT_MM`, `ENABLE_OUTPUT`, `DISABLE_OUTPUT`, `SET_I2C_ADDRESS`, `SET_SERIAL_MODE`, `SET_I2C_MODE`, `I2C_FORMAT_CM`, `I2C_FORMAT_MM` + +`param`   The defined paramters are:
+`BAUD_9600`, `BAUD_14400`, `BAUD_19200`, `BAUD_56000`, `BAUD_115200`, `BAUD_460800`, `BAUD_921600`
+and
+`FRAME_0`, `FRAME_1`, `FRAME_2`, `FRAME_5`, `FRAME_10`, `FRAME_20`, `FRAME_25`, `FRAME_50`, `FRAME_100`, `FRAME_125`, `FRAME_200`, `FRAME_250`, `FRAME_500`, `FRAME_1000` Any change of device settings (i.e. frame-rate or baud-rate) must be followed by a `SAVE_SETTINGS` command or else the modified values may be lost when power is removed. `SYSTEM_RESET` and `RESTORE_FACTORY_SETTINGS` do not require a `SAVE_SETTINGS` command. @@ -56,6 +64,7 @@ Also included:
  ●  Valuable information regarding Time of Flight distance sensing in general and the Texas Instruments OPT3101 module in particular are in a Documents sub-folder. All of the code for this library is richly commented to assist with understanding and in problem solving. +
### Using the I2C version of the device According to Benewake: @@ -64,12 +73,15 @@ According to Benewake: Because the Data Frame Rate is limited to 1000Hz, this condition implys 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. -To configure the device for I2C communication, a command must be sent using the UART inteface. Therefore, this reconfiguation should be made prior to the device's service installation, either by using this library's `SET_I2C_MODE` command or the serial GUI test application and code supplied by the manufacturer. +To configure the device for I2C communication, a command must be sent using the UART interface. Therefore, this reconfiguation should be made prior to the device's service installation, either by using this library's `SET_I2C_MODE` command or the serial GUI test application and code supplied by the manufacturer. -The `SET_I2C_MODE` command does not require a subsequent `SAVE_SETTINGS` command. The device will remain in I2C mode after power has been removed and restored. The only way to return to serial mode is with the `SET_SERIAL_MODE` command. Even a `RESTORE_FACTORY_SETTINGS` command will NOT restore the device to its default, UART communication interface mode. +On some devices, the `SET_I2C_MODE` command will not require a subsequent `SAVE_SETTINGS` command. The device will remain in I2C mode after power has been removed and restored. The **only way** to return to serial mode is with the `SET_SERIAL_MODE` command. Even a `RESTORE_FACTORY_SETTINGS` command will NOT restore the device to its default, UART communication interface mode. The device functions as an I2C slave device and the default address is `16` (`0x10` Hex) but is user-programable by sending the `SET_I2C_ADDRESS` command and a parameter in the range of `1` to `127`. The new setting will take effect immediately and permanently without a `SAVE_SETTINGS` command, however the `RESTORE_FACTORY_SETTINGS` command will restore the default address. The I2C address can be set while still in serial communication mode or, if in I2C mode, the example sketch included in the TFMini-Plus-I2C library can be used to test and change the address. +When switching modes, please remember to switch the data cables, too. That sounds obvious, but has tripped me up more than once. +
+ ### Using the I/O modes of the device The so-called I/O modes are not supported in this library. Please do not attempt to use any I/O commands that you may find to be defined in this library's header file.