MappyDot Plus Registers and Instruction Set

After the MappyDot Pluses have booted and determined their device addresses (approximately 1000ms), you can send each of the following I2C commands/registers to the individual MappyDot Pluses. Each command is a one byte value and with required options (shown in square brackets). Each command has been written below with their hex value (in parenthesis) as well as their human readable counterpart for ease of programming.

These registers are available in the firmware sources for you to include in your project - https://github.com/SensorDots/MappyDotPlusFirmware/blob/master/MappyDot/include/mappydot_reg.h

* Denotes general call enabled for this command.

Basics:

  • r (0x72) - Read Distance - Reads the distance in mm. If in continuous mode, it will return the most recent measurement. If in single measurement mode it will return the last measurement. For distance reads, you can also omit commands all together and just push the MappyDot's read address to the I2C bus. Returns distance in mm. Any distance measured below 30mm will output as 30mm. See distance bytes for distance format. A distance of 0 with an error code of 4 indicates that the target is too far away.
  • S (0x53)* - Perform Single Range - Performs a single distance read. This needs to be performed before a read distance command if in single ranging mode. The length of time to wait between this command and the read command will depend on the mode (see Ranging Modes). You can get this length of time in ms from the read settings command. This has no effect in continuous ranging mode.
  • R (0x52) - Read Accuracy - Reads the current sigma accuracy value. This is an estimation of the standard deviation of the current range, expressed in millimeters.
  • E (0x45) - Read Error Code - Returns the last error code made by the ranging procedure.
  • m (0x6D) [measurement_mode] - Measurement Mode - Sets the measurement mode of the MappyDot.
  • B (0x42) [measurement_budget_ms] - Measurement Budget - Sets the measurement budget in milliseconds between 20 and 1000. If set higher or lower than this range it will revert to the upper/lower limits. Measurement_budget_ms uses the same byte formatting as Distance Bytes.
  • c (0x63)* - Set Continuous Ranging Mode - Sets the MappyDot to make continuous ranging measurements as fast as the current mode will allow.
  • s (0x73)* - Set Single Ranging Mode - Sets the MappyDot to single ranging mode. Measurements will be made on a perform single range command. It is recommended to turn off filtering and averaging in this mode.
  • I (0x49) - Interrupt Check - Checks whether a new range has occurred since last read. Returns 0 for false and 1 for true.

Configuration:

  • F/f (0x46/0x66)* - Filtering - Enables the low pass filter. This is on by default. Not available in single ranging mode. F for on, f for off.
  • V/v  (0x56/0x76)* - Averaging - Enables averaging over x samples (set by i command). Disabled by default. V for on, v for off.
  • p (0x70) [roi_bytes] - Region of Interest - Specifies the region of interest which also sets the field of view of the sensor. Setting any of the byte values outside the appropriate range just ignores the values and the MappyDot Plus will revert to the default ROI. Please note that this will change the accuracy and maximum distance you are capable of ranging at. Minimum ROI size is 4x4. Different sizes correspond to different viewing angles; for example 16x16 - 27 degrees, 8x8 - 20 degrees, 4x4 - 15 degrees. They can be centered around the optical center or at any position on the sensor. Please note, if these values are set incorrectly, the MappyDot will revert back to full region of interest.
  • L (0x4C) [sigma_mm] - Set Sigma Limit Check Value -Sigma is expressed in mm and is the estimation of the standard deviation of the measurement.
  • G (0x47) [signal_KCps] - Set Signal Limit Check Value - Represents the amplitude of the signal reflected from the target and detected by the device.
  • i (0x69) [num_of_samples_byte] - Averaging Samples - Default of 4. Can set from 2 to 10.
  • l (0x6C) [led_mode] - Set LED Mode - Sets the LED mode. See ranging modes.
  • e (0x65) [led_threshold_distance_bytes] - Set LED threshold distance in mm - See distance bytes for distance format.
  • g (0x67) [gpio_mode] - Set POUT GPIO Mode - Sets the mode of the POUT pin.
  • o (0x6F) [gpio_threshold_distance_bytes] - Set GPIO threshold distance in mm - See distance bytes for distance format.
  • a (0x61) [target_distance_bytes] - Calibrate Distance Offset - Recommended to use a white (88% reflectance) target at 100mm, in a dark environment. Target distance can be changed but it has to be chosen in the linear part of the ranging curve. Both Reference SPADs and Ref calibrations have to be performed before calling offset calibration.
  • x (0x78) [target_distance_bytes] - Calibrate Crosstalk
  • K (0x4B) - Enable Crosstalk/Window Compensation
  • k (0x6B) - Disable Crosstalk/Window Compensation
  • u (0x75) - Calibrate Reference SPAD - The calibration does not require specific target or lighting conditions.
  • T/t (0x54/0x74) - Inter-Sensor Crosstalk Reduction - T for on, t for off.
  • q (0x71) [timeout_ms_byte] - Inter-Sensor Crosstalk Timeout - If not using an optional loop wire to connect the last device in the chain back to the master (seen here), the master will not see the measurement pulse return it itself. In this instance, the master will delay for this period of time until it starts another distance measurement then retrigger the chain. Only applicable on the master.
  • Q (0x51) [timeout_ms_byte] - Inter-Sensor Crosstalk Measurement Delay - Sets the delay between measurements from one device to the next in the chain for crosstalk reduction.

Settings:

  • N (0x4E) - Firmware Version - Returns the current firmware version string of the MappyDot as 10 bytes.
  • n (0x6E) [device_name_bytes] - Name Device - Give the device a 16 byte name. If 16 bytes aren't sent, the name routine is ignored.
  • d (0x64) - Device Name - Return the device name as 16 bytes.
  • b (0x62) - Read Current Settings - Returns the current settings bytes.
  • z (0x7A)* - Restore Factory Defaults - Restore default firmware settings and factory calibration. The restored settings are volatile until they are written to start up defaults.
  • w (0x77)* - Write Current Settings as Start Up Default - Writes the current settings as the default startup settings to non volatile storage.

Advanced:

  • X (0x58)* - Reset VL53L1X Ranging - Re-initialises the VL53L1X ranging procedures.
  • H/h (0x48/0x68)* - VL53L1X Shutdown - H for VL53L1X on, h for shutdown.
  • j (0x6A) - Read Non-filtered Value - Reads the latest non-filtered and non-averaged value. Useful for verifying filter characteristics.
  • A (0x41) - AmbientRateRtnMegaCps - Returns 16 bit ambient signal rate in Mega Cps.
  • J (0x4A) - SignalRateRtnMegaCps - Returns 16 bit signal rate in Mega Cps.
  • Y/y (0x59/0x79) - Intersensor Sync Enable - Enables intersensor synchronisation. If enabled, the master device will send a sync pulse on the ADDR lines whenever it takes a measurement (the master can be in single shot or continuous modes) and all the other devices in the chain will cascade trigger off this sync pulse. This needs to be enabled on all devices for it to work for all devices in the chain. All devices also need to have the same measurement settings for it to work correctly (if a slave device is set to 20ms measurement budget and the master is set to 10ms, then the slave device will skip measurements). Y for on, y for off. Available from firmware version 1.2.

Please note, any of the above settings changes are not retained through a power cycle unless the write settings command is sent.

Super Advanced:

  • #!#!#!# - Enter Factory Mode - <WARNING>, this will make any subsequent calibration commands overwrite the factory defaults! Only use this if you are repackaging the MappyDot in a housing and use a specialised jig for accurate calibration. It is recommended to try regular user calibration first before performing this.

 

Factory Defaults

These are the factory defaults programmed into the MappyDot Pluses.

  • Measurement Mode - SHORT_RANGE
  • Measurement Budget - 41ms
  • Ranging Mode - Continuous
  • Field of View - Full (0,15 -> 15,0)
  • Averaging - Disabled
  • Filtering - Enabled
  • GPIO Mode - Measurement
  • LED Mode - PWM (30cm threshold)

 

Current Settings Byte Order

  • 0,1:   Measurement budget in ms.
  • 2:   Ranging mode.
  • 3:   Measurement mode.
  • 4:   LED mode.
  • 5,6: LED threshold.
  • 7:   GPIO mode.
  • 8,9: GPIO threshold.
  • 10: Filtering.
  • 11 Averaging.
  • 12: Averaging Samples
  • 13: Interdevice crosstalk.
  • 14: Interdevice crosstalk delay.
  • 15: Interdevice crosstalk timeout (ticks/1000).
  • 16: VL53L1X shutdown.
  • 17: ROI Top Left X
  • 18: ROI Top Left Y
  • 19: ROI Bottom Right X
  • 20: ROI Bottom Right Y
  • 21: Optical center X
  • 22: Optical center Y

Measurement Modes

  • s (0x73) - Short Range - 1.2m
  • m (0x6D) - Medium Range - 2m
  • l (0x6c) - Long Range - 4m

 

LED Modes

  • o (0x6f) - On - Turn on LED.
  • f (0x66) - Off -Turn off LED.
  • t (0x74) - Threshold enabled - Turns on LED when a specific LED threshold is reached.
  • p (0x70) - PWM enabled - The brightness of the LED will sweep between 0% to 100% depending on the distance measured. The lowest PWM point value is controlled by the LED distance threshold.
  • m (0x6D) - Measurement - Flash when a measurement is being made.

 

GPIO Modes

  • o (0x6F) - High - Set POUT high.
  • f (0x66) - Low - Set POUT low.
  • t (0x74) - Threshold enabled - Sets POUT high when a specific GPIO threshold is reached.
  • p (0x70) - PWM enabled - The PWM of POUT will sweep between 0% to 100% depending on the distance measured. The lowest PWM point value is controlled by the GPIO distance threshold.
  • m (0x6D) - Measurement interrupt - Pulse high when measurement is being made. Will go low once measurement is finished (and ready to read).

 

Distance Bytes

The distance in mm is stored as a two byte unsigned integer (uint16_t). The first byte is the most significant bits and the second byte is the least significant bits. An example of reading the bytes in (Arduino) c is:

Wire.requestFrom(address, 2); distance = Wire.read() << 8; distance |= Wire.read();

The leftmost Wire.read() Arduino I2C command above is performed first and shifted to the most significant bits.

Conversely, if creating the bytes:

Wire.write((uint8_t)(distance >> 8 & 0xFF)); Wire.write((uint8_t)(distance & 0xFF));

 

Range Error Codes

  • 0 - Ranging Valid - Ranging measurement is valid.
  • 1 - Sigma Fail - Raised if Sigma estimator check is above the internal defined threshold. Sigma fail will trigger particularly in ambient light, when the amount of ambient light is adding too much noise onto the ranging measurement. This is useful for measuring excessive ambient light and can be used to change ranging modes if necessary.
  • 2 - Signal Fail - Raised if Signal value is below the internal defined threshold. Signal fail will trigger when the return signal is too low to give enough confidence on the range measured. The limit will be given by either the signal limit or the RIT (Range Ignore Threshold). The measurement value can still be used within reason if this range error is triggered.
  • 4 - Out of Bounds - Raised when phase is out of bounds. This will trigger when wraparound conditions are detected or when noise on signal is too high. This usually occurs if the target is outside the maximum measurement range.
  • 5 - Hardware Fail - Hardware Fail will trigger if a VCSEL failure, or VHV fail are detected.
  • 7 - Wrap Target Fail - Wrapped target, not matching phases. This error will range when target is too close in longer ranging modes.
  • 8 - Processing Fail - Internal algorithm underflow or overflow.
  • 14 - Invalid - The reported range is invalid.

 

ROI Bytes

The region of interest bytes order is as follows:

  • 0: TopLeftX - Top Left x coordinate:  0-15 range
  • 1: TopLeftY - Top Left y coordinate:  0-15 range
  • 2: BotRightX - Bottom Right x coordinate: 0-15 range
  • 3: BotRightY - Bottom Right y coordinate: 0-15 range

The minimum ROI size is 4x4.
 

 

Copyright © SensorDots 2020