« Close

Datasheets and User Guides

App Notes

Software & Driver

 

Appendix B - Low-Level Docs

Use the instantaneous readings to grab a reading from each of the sensors while the Digit is connected via USB. The conversion equations used to convert each of these from a raw representation are described below. Alternatively, download the C++, or LabVIEW example code attached at the bottom of this page.

Converting raw temperature data

Temperature on the Digit is stored as an unsigned 12 bit value, this value needs to be converted into a signed number, and multiplied by a conversion factor before it will look like degrees C. The raw value is a 16-bit number, the 4 lowermost bits being system flags.

Raw Temperature 16-bits:
Xxxx xxxx xxxx rrrr

r's are reserved for flags.
x's are the temperature information.
X is the most significant temperature bit, discussed in step 2.

To convert raw temperature into °C:

  1. Remove/Process the lowermost 4 bits (if non-zero). See flag descriptions below.
  2. Decide if positive or negative by looking at the most significant bit.
    If the MSB is 1, temperature is negative,
    If the MSB is 0, temperature is positive.
  3. (For negative temperature, MSB == 1)
    Subtract 1 from the value.
    Invert every bit of the value (change 0s to 1s, and 1s to 0s).
    Perform a logical right hand shift of the value by 4 bits.
    Multiply the value by -1, to get the sign right.
  4. (For positive temperature, MSB == 0)
    Perform a logical right hand shift of the value by 4 bits.
  5. Multiply the value from step 3 or 4 by the conversion factor: (0.0625 °C/count)

The TMP112 datasheet also explains this process. See page 8: http://www.ti.com/lit/ds/sbos473b/sbos473b.pdf

Invalid Measurement = 32768
If the battery is dead, the TMP112 has failed, or a communication line between the temperature sensor and the microprocessor is damaged. the Digit will return a value of 32768. A value of 32768 converts into -128C, but normal operation will never return -128C, so it's a unique indication of an invalid reading.

Flags in the temperature
bit0 (0x01) = Warning Detected
bit1 (0x02) = Power Failure Detected
bit2 (0x04) = Reset Detected
bit3 (0x08) = 'On USB' flag, to indicate processor heat influence

 

Converting raw light data

Raw light readings are saved as a number of timer counts in memory, ranging from 18-65535.

Raw Light 16-bits:
xxxx xxxx xxxx xxxx

In software the calibrated light value is generated through interpolation along a 3D surface (with some simplification). The temperature (to nearest 1°C) at the time of the light reading is used as an index, then the Digit's raw light value (timer counts) points to a region in-between Lux values, so interpolation is performed between the nearest 2 points in Lux.

Due to the simplification of 1°C resolution, the interpolation is merely done on a 2D surface, the whole 3D surface does not need to be analyzed in software.

To convert raw light into Lux:

If converting raw light readings sounds overwhelming, don't worry too much-just look at the C++ example code attached on this page. The 3D calibration surface is simply a header file[LightCalibration.h] with 3 static arrays. The light conversion code uses temperature as the first lookup index in the header file, which reduces the three large(1792 datapoint) arrays down into two 14 datapoint arrays that represent possible values of calibrated lux and raw light counts at the given temperature.

Next, the raw light reading (DGT_LIGHT_RAW) is compared to each of the raw readings in the 14 datapoint array that contains raw values. Simple linear interpolation between the two nearest raw values will yield a fractional index of where the raw reading resides relative to the available calibration points. Finally, this fractional index is applied to interpolate between the nearest Lux values which yields the light reading in Lux.

Invalid Measurement = 1
If the Digit is plugged/un-plugged from USB during a light reading in-progress, the reading is interrupted, and a 1 is saved instead of the timer value. A value of 1 converts to roughly 12000 Lux, but normal operation will never return a value of 1, so it's a unique indication of an invalid reading.

 

Converting raw humidity data

Humidity readings are performed by an HCH-1000, which is a capacitive humidity sensor. A constant current source and a 10-bit ADC on the Digit-TLH work together to read the capacitance value, which is the raw humidity reading.

Raw Humidity 16-bits:
rrrr xxxx xxxx xxxx

x - measurement of raw capacitance (humidity)
r - reserved.

Humidity variables
Name Start Address Type Access
DGT_HUMIDITY_RAW 22001 UINT16 R
DGT_HUMIDITY_CAL_SLOPE 22236 FLOAT32 R/W
DGT_HUMIDITY_CAL_OFFSET 22232 UINT16 R/W
DGT_HUMIDITY_CAL_T_SLOPE 22238 FLOAT32 R/W
DGT_HUMIDITY_RAW
- Address: 22001
Craw. Get a new humidity reading from HCH-1000. Units are in 100s fF of capacitance.
  • Data type: UINT16  (type index = 0)
  • Read-only
DGT_HUMIDITY_CAL_SLOPE
- Address: 22236
The slope of humidity used in the conversion of raw humidity. Units in %Rh per 100s fF.
  • Data type: FLOAT32  (type index = 3)
  • Readable and writable
DGT_HUMIDITY_CAL_OFFSET
- Address: 22232
A single point offset used in the conversion of raw humidity. Units in 100s fF
  • Data type: UINT16  (type index = 0)
  • Readable and writable
DGT_HUMIDITY_CAL_T_SLOPE
- Address: 22238
The temperature dependent factor used in the conversion of raw humidity. Units in 100s fF per degC
  • Data type: FLOAT32  (type index = 3)
  • Readable and writable

Master Equation

%RH = (DGT_HUMIDITY_RAW - DGT_HUMIDITY_CAL_OFFSET + ( (DGT_HUMIDITY_CAL_T_SLOPE)(DGT_TEMPERATURE_LATEST_RAW) -
 (DGT_HUMIDITY_CAL_T_SLOPE)(-38) )(DGT_HUMIDITY_CAL_SLOPE)

 

To convert raw humidity into %RH:

  1. Read the current temperature DGT_TEMPERATURE_LATEST_RAW*.
  2. Read the values of the CAL registers listed above.
  3. Read DGT_HUMIDITY_RAW.
  4. Use the "Master Equation" to calculate the %RH humidity.

*In the case of downloaded data, use whatever temperature reading happened at the same time as the humidity reading (adjacent in memory).

Invalid Measurement = 1
If the Digit does not have a humidity sensor, or the humidity sensor is broken, the raw humidity reading will be a value of 1. Normal operation will never return a value of 1, so it's a unique indication of an invalid reading.

There is also a command (DGT_HUMIDITY_CAL_I_SOURCE) to initiate calibration of the constant current source, which is used during factory calibration, but it is not recommended to write to this register, unless you plan to re-calibrate the other parameters.

Everything Else

Digit Instantaneous Readings
Name Start Address Type Access
DGT_TEMPERATURE_LATEST_RAW 22000 UINT16 R
DGT_HUMIDITY_RAW 22001 UINT16 R
DGT_LIGHT_RAW 22002 UINT16 R
DGT_TEMPERATURE_LATEST_RAW
- Address: 22000
Get the latest temperature conversion, and begin a new conversion. Starting with FW1.21, temperature conversion is instantaneous. Units are described in TMP112 datasheet.
  • Data type: UINT16  (type index = 0)
  • Read-only
DGT_HUMIDITY_RAW
- Address: 22001
Craw. Get a new humidity reading from HCH-1000. Units are in 100s fF of capacitance.
  • Data type: UINT16  (type index = 0)
  • Read-only
DGT_LIGHT_RAW
- Address: 22002
Counts. Get a new light reading from LED. Units are in counts before reverse leakage complete.
  • Data type: UINT16  (type index = 0)
  • Read-only

Use the _DATASET, and START_TIME parameters to interpret downloaded data. Logged data must always be saved in one of the following sequences: T, TL, TH, THL, so downloading code simply reads the logged items, and interprets data space in segments of unsigned 16s. There are no timestamps saved with the data. Instead, use the DGT_LOG_START_TIME and the DGT_LOG_INTERVAL_INDEX_DATASET to determine when data was collected.

Download Data
Name Start Address Type Access
DGT_LOG_ITEMS_DATASET 22019 UINT16 R
DGT_LOG_INTERVAL_INDEX_DATASET 22039 UINT16 R
DGT_LOG_START_TIME 22042 UINT16 R
DGT_STORED_BYTES 22210 UINT32 R
DGT_pFLASH_READ 22810 UINT32 R/W
DGT_FLASH_READ 22812 UINT16 R
DGT_LOG_ITEMS_DATASET
- Address: 22019
Read what is logged in the dataset. Value is a bitmask. Bit0: 1 = Temperature logged, Bit1: 1 = Light logged, Bit2: 1 = Humidity logged. In memory: T, TL, TH, THL.
  • Data type: UINT16  (type index = 0)
  • Read-only
  • Minimum firmware version: 1.2100
DGT_LOG_INTERVAL_INDEX_DATASET
- Address: 22039
Read time interval between log events in the dataset. Index 0=10s, 1=30s, 2=1m, 3=10m, 4=30m, 5=1h, 6=6h
  • Data type: UINT16  (type index = 0)
  • Read-only
  • Minimum firmware version: 1.2100
DGT_LOG_START_TIME
- Address: 22042
The start time of the logging session: 22042 Year=0 to 99, 22043 Month=1 to 12, 22044 Day=1 to 31, 22045 Weekday=1 to 7, 22046 Hour=0 to 23, 22047 Minutes=0 to 59, 22048 Second=0 to 59
  • Data type: UINT16  (type index = 0)
  • Read-only
DGT_STORED_BYTES
- Address: 22210
Number of bytes of data stored on flash.
  • Data type: UINT32  (type index = 1)
  • Read-only
DGT_pFLASH_READ
- Address: 22810
The read pointer for flash. Auto-incremented, simply initialize with a start address, then use 22812+
  • Data type: UINT32  (type index = 1)
  • Readable and writable
DGT_FLASH_READ
- Address: 22812
Read data from this address and subsequent addresses after pointer is initialized. Used to download data from the Digit.
  • Data type: UINT16  (type index = 0)
  • Read-only

Change the configuration of the Digit with the following registers. Changes are applied when data is erased with DGT_FLASH_bkERASE. It is recommended that the Digit RTC is synchronized with the host computer with DGT_RTCC_TIME immediately prior to applying changes to configuration (calling DGT_FLASH_bkERASE).

Digit Configuration
Name Start Address Type Access
DGT_CHANGE_LOG_ITEMS 22018 UINT16 R/W
DGT_CHANGE_LOG_INTERVAL_INDEX 22038 UINT16 R/W
DGT_RTCC_TIME 22242 UINT16 R/W
DGT_FLASH_bkERASE 22822 UINT16 W
DGT_FLASH_WIP 22804 UINT16 R
DGT_CHANGE_LOG_ITEMS
- Address: 22018
Set the items to log. Value is a bitmask. Bit0: 1 = Log Temperature, Bit1: 1 = Log Light, Bit2: 1 = Log Humidity. All other bits reserved. Change implemented on next erase of dataset.
  • Data type: UINT16  (type index = 0)
  • Readable and writable
  • Minimum firmware version: 1.2100
DGT_CHANGE_LOG_INTERVAL_INDEX
- Address: 22038
Set the time interval between log events. Index 0=10s, 1=30s, 2=1m, 3=10m, 4=30m, 5=1h, 6=6h Change implemented on next erase of dataset.
  • Data type: UINT16  (type index = 0)
  • Readable and writable
  • Minimum firmware version: 1.2100
DGT_RTCC_TIME
- Address: 22242
The current time of the real-time-clock on the Digit. Synchronized with the computer within software. 22242 Year=0 to 99, 22243 Month=1 to 12, 22244 Day=1 to 31, 22245 Weekday=1 to 7, 22246 Hour=0 to 23, 22247 Minutes=0 to 59, 22248 Second=0 to 59
  • Data type: UINT16  (type index = 0)
  • Readable and writable
DGT_FLASH_bkERASE
- Address: 22822
Erase all data on the flash. KEY=Erase, Other=No effect, KEY=37157 Takes 5 seconds to complete, so poll the WIP status flag until =0. After erase, logging will begin immediately.
  • Data type: UINT16  (type index = 0)
  • Write-only
DGT_FLASH_WIP
- Address: 22804
A status flag for the flash(data storage chip) on the Digit. 1=Write in-progress, 0=Idle
  • Data type: UINT16  (type index = 0)
  • Read-only

Alarm thresholds, changing factory settings, and upgrading firmware are not covered in this doc. If you need information about these topics please contact [email protected] for more details.