MappyDot Registers and Instruction Set

After the MappyDots have booted and determined their device addresses (approximately 1000ms), you can send each of the following I2C commands/registers to the individual MappyDots. 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/MappyDotFirmware/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.
  • 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. Available from firmware version 1.4.

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.
  • 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
  • u (0x75) - Calibrate Reference SPAD - The calibration does not require specific target or lighting conditions.
  • U (0x55) - Temperature Calibration - Performed after Reference SPAD calibration, before offset and cross-talk calibrations and before the first ranging is performed. It should be performed again when temperature varies more than 8degC compared to the initial calibration temperature.
  • 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 VL53L0X Ranging - Re-initialises the VL53L0X ranging procedures.
  • H/h (0x48/0x68)* - VL53L0X Shutdown - H for VL53L0X 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. Available from firmware version 1.4.
  • J (0x4A) - SignalRateRtnMegaCps - Returns 16 bit signal rate in Mega Cps. Available from firmware version 1.4.

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.
  • k (0x6B) [custom_profile_bytes] - Custom Profile Settings - Sets the custom profile settings. See custom profile byte order for more information. Available from firmware version 1.2. Please note, this is an advanced setting and there is no input checking on these values. Any incorrect settings can cause incorrect device operation. If the device experiences issues, please reset device. Please be sure to test settings work before storing the settings as startup defaults. Please note, new settings don't apply until a measurement mode change.

Factory Defaults

These are the factory defaults programmed into the MappyDot Pluses.

  • Measurement Mode - VL53L0X_Default
  • Ranging Mode - Continuous
  • Averaging - Disabled
  • Filtering - Enabled
  • GPIO Mode - Measurement
  • LED Mode - PWM (30cm threshold)

Current Settings Byte Order

  • 0:   Measurement budget in ms.
  • 1:   Ranging mode.
  • 2:   Measurement mode.
  • 3:   LED mode.
  • 4,5: LED threshold.
  • 6:   GPIO mode.
  • 7,8: GPIO threshold.
  • 9: Filtering.
  • 10 Averaging.
  • 11: Averaging Samples
  • 12: Interdevice crosstalk.
  • 13: Interdevice crosstalk delay.
  • 14: Interdevice crosstalk timeout (ticks/1000).
  • 15: VL53L0X shutdown.

 

Measurement Modes

  • h (0x68) - Highly Accurate - 1.2m - 5Hz - 200ms
  • l (0x6C) - Long Range - 2m - 30Hz - 33.3ms
  • s (0x73) - High Speed - 1.2m - 50Hz - 20ms
  • d (0x64) - VL53L0X Default - 1.2m - 33Hz - 30.3ms
  • m (0x6D) - MappyDot Mode - 2m auto switching - 50Hz - 20ms (only works in continuous ranging mode. If set to this mode and single ranging mode is selected, continuous mode will be set. If single ranging is set afterwards, the ranging mode will switch back to VL53L0X Default).
  • c (0x63) - Custom Profile - Changes to custom profile mode if custom profile settings are set. If settings are not set it will revert to the default profile. Available from firmware version 1.2.

 

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 - Range Valid - Ranging measurement is valid.
  • 1 - Sigma Fail - 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 - 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 - Phase Fail - Phase fail 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.

 

Custom Profile Settings Byte Order

For more details on what each value does, please see the API programming documents. The byte order of the custom profile is as follows:

| byte 0 | byte 1 | byte 2 | byte 3 | byte 4 | byte 5 | byte 6 | byte 7 | byte 8 |
| THRESH | THRESHOLD_VALUE | SR_F_R | SM_F_R |  TIMING_BUDGET  | VP_P_R | VP_F_R |
  • 0: Range Ignore Threshold - Boolean value stored as byte.
  • 1,2: Range Ignore Threshold Value - Used if range ignore threshold is true. Value (N) needs to be multiplied by 0.023 then 65536 before placing into byte array.
  • 3: Signal Rate Final Range - 2 decimal point value is expressed as integer. Multiply range value by 100 before placing into byte array.
  • 4: Sigma Final Range
  • 5,6: Timing Budget - In ms (the API expresses these values as us).
  • 7: VCSEL Period Pre Range
  • 8: VCSEL Period Final Range

All two byte values should be treated as uint16_t and all single byte values should be treated as uint8_t. The first byte in a two byte value is the most significant bits and the second byte is the least significant bits.

For details on how to store these values, here are the default measurement profile values:

RANGE_IGNORE_THRESHOLD 1
RANGE_IGNORE_THRESHOLD_VALUE 1.5
SIGNAL_RATE_FINAL_RANGE 0.25
SIGMA_FINAL_RANGE 18
TIMING_BUDGET 33000us //30Hz
VCSEL_PERIOD_PRE_RANGE 14
VCSEL_PERIOD_FINAL_RANGE 10

Here are the values after performing the correct conversions to the above:

RANGE_IGNORE_THRESHOLD 1
IGNORE_THRESHOLD_VALUE 2261 //Rounded up from 1.5 x 0.023 x 65536 = 2260.992
SIGNAL_RATE_FINAL_RANGE 25
SIGMA_FINAL_RANGE 18
TIMING_BUDGET 33
VCSEL_PERIOD_PRE_RANGE 14
VCSEL_PERIOD_FINAL_RANGE 10

Now these values expressed as bytes:

| byte 0 | byte 1 | byte 2 | byte 3 | byte 4 | byte 5 | byte 6 | byte 7 | byte 8 |
|  0x01  | ‭ 0x08  |  0xD5‬  |  0x19  |  0x12  |  0x00  |  0x21  |  0x0E  |  0x0A  |

 

 

Copyright © SensorDots 2020