« Close

Datasheets and User Guides

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    

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    

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    

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    

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.