Appendix B - Low-Level Docs | LabJack

# 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             Craw. Get a new humidity reading from HCH-1000. Units are in 100s fF of capacitance. 22001 UINT16 R DGT_HUMIDITY_CAL_SLOPE             The slope of humidity used in the conversion of raw humidity. Units in %Rh per 100s fF. 22236 FLOAT32 R/W DGT_HUMIDITY_CAL_OFFSET             A single point offset used in the conversion of raw humidity. Units in 100s fF 22232 UINT16 R/W DGT_HUMIDITY_CAL_T_SLOPE             The temperature dependent factor used in the conversion of raw humidity. Units in 100s fF per degC 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.
4. Use the "Master Equation" to calculate the %RH humidity.

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

 Name Start Address Type Access DGT_TEMPERATURE_LATEST_RAW             Get the latest temperature conversion, and begin a new conversion. Starting with FW1.21, temperature conversion is instantaneous. Units are described in TMP112 datasheet. 22000 UINT16 R DGT_HUMIDITY_RAW             Craw. Get a new humidity reading from HCH-1000. Units are in 100s fF of capacitance. 22001 UINT16 R DGT_LIGHT_RAW             Counts. Get a new light reading from LED. Units are in counts before reverse leakage complete. 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.

 Name Start Address Type Access DGT_LOG_ITEMS_DATASET             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. 22019 UINT16 R DGT_LOG_INTERVAL_INDEX_DATASET             Read time interval between log events in the dataset. Index
0=10s,
1=30s,
2=1m,
3=10m,
4=30m,
5=1h,
6=6h 22039 UINT16 R DGT_LOG_START_TIME             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 22042 UINT16 R DGT_STORED_BYTES             Number of bytes of data stored on flash. 22210 UINT32 R DGT_pFLASH_READ             The read pointer for flash. Auto-incremented, simply initialize with a start address, then use 22812+ 22810 UINT32 R/W DGT_FLASH_READ             Read data from this address and subsequent addresses after pointer is initialized. Used to download data from the Digit. 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             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. 22018 UINT16 R/W DGT_CHANGE_LOG_INTERVAL_INDEX             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. 22038 UINT16 R/W DGT_RTCC_TIME             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 22242 UINT16 R/W DGT_FLASH_bkERASE             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. 22822 UINT16 W DGT_FLASH_WIP             A status flag for the flash(data storage chip) on the Digit. 1=Write in-progress, 0=Idle 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.