Field Reference

Comprehensive reference documentation for LoRaWAN payload data types, units, and encoding formats used across all Truvami tracking devices.

Data Types

All payload fields use specific data types that define how binary data should be interpreted. Understanding these types is essential for proper payload decoding.

Integer Types

Unsigned integers (uint8, uint16, uint32) can only represent positive values and zero. They are commonly used for:

• Counters and identifiers
• Sensor readings that are always positive
• Timestamps and durations

Signed integers (int8, int16, int32) can represent both positive and negative values. They are used for:

• Temperature readings (which can be negative)
• Relative positions or offsets
• Difference calculations

Floating Point Types

Float and double types follow the IEEE 754 standard for representing decimal numbers. They are used for:

• High-precision sensor readings
• Calculated values requiring decimal precision
• Geographic coordinates requiring sub-degree precision

Boolean Type

Boolean values represent simple true/false states and are typically used for:

• Device status flags
• Configuration enable/disable settings
• Sensor threshold alerts

Unit Scales and Prefixes

Many field values include unit scaling to optimize payload size while maintaining precision. The scale indicates how to convert the raw integer value to the actual physical unit.

Common Unit Examples

Geographic Coordinates:

• latitude and longitude fields often use microdegrees (μ°)
• Raw value 45123456 with micro scale = 45.123456°

Voltage Measurements:

• Battery voltage often uses millivolts (mV)
• Raw value 3300 with milli scale = 3.3V

Distance and Altitude:

• Altitude may use decimeters (dm) for precision
• Raw value 1234 with deci scale = 123.4m

Common Field Patterns

Timestamps

Most devices use Unix epoch timestamps for time representation:

• Type: uint32
• Unit: second
• Description: Seconds since January 1, 1970 (Unix epoch)
• Example: 1697788800 = October 20, 2023, 08:00:00 UTC

Geographic Data

GPS coordinates are typically encoded with high precision:

• Latitude/Longitude: int32 with microdegree scale
• Altitude: uint16 with decimeter scale
• Accuracy/PDOP: uint8 with various scales

Battery and Power

Battery information commonly uses:

• Voltage: uint16 with millivolt scale
• Current: int16 with milliampere scale
• Percentage: uint8 (0-100%)

Sensor Data

Environmental sensors typically encode:

• Temperature: int16 with centi scale (°C × 100)
• Humidity: uint8 (0-100%)
• Pressure: uint32 with pascal scale

Bit Fields and Flags

Some fields pack multiple boolean values into a single byte using bit manipulation:

Status Field (uint8): 0b10110010
├─ Bit 0: Moving flag (0 = stationary)
├─ Bit 1: GPS fix (1 = valid fix)
├─ Bit 2: Reserved (0)
├─ Bit 3: Reserved (0)
├─ Bit 4: Low battery (1 = low)
├─ Bit 5: Alert active (1 = active)
├─ Bit 6: Reserved (0)
└─ Bit 7: Configuration changed (1 = changed)

Reading Bit Fields

To extract individual bits from a byte value:

• Bit 0 (LSB): value & 0x01
• Bit 1: (value >> 1) & 0x01
• Bit 7 (MSB): (value >> 7) & 0x01

Enumerated Values

Some fields use predefined enumeration values instead of direct numeric interpretation:

Mode Field (uint8):
├─ 0 = Sleep mode
├─ 1 = Active mode
├─ 2 = GPS acquisition mode
└─ 3 = Emergency mode

Enumerated values provide meaningful interpretation of numeric codes and are clearly documented in each device's payload specification.

Byte Order (Endianness)

All multi-byte integer values follow little-endian byte ordering unless explicitly specified otherwise:

• uint16 value 0x1234 is transmitted as [0x34, 0x12]
• uint32 value 0x12345678 is transmitted as [0x78, 0x56, 0x34, 0x12]

This convention ensures consistent interpretation across different platforms and programming languages.

This reference applies to all Truvami device protocols. For device-specific field definitions, see the individual device documentation.