Hello, it sounds like we work in incredibly similar fields actually. My company makes radiation detectors.
The documentation for the DWM3001CDK isn’t always the best, but you can find what information you need through looking at the code, however tedious that is. In fira_app.c (contained in ~/DW3_QM33_SDK_1.0.2/SDK/Firmware/DW3_QM33_SDK_1.0.2.zip/Src/Apps/Src/fira), it contains a function called fira_session_info_ntf_twr_cb(), which formats the SESSION_INFO_NTF messages.
Based on the source code from fira_app.c, here’s the complete documentation for parsing SESSION_INFO_NTF messages:
Message Structure
SESSION_INFO_NTF: {session_handle=<uint32>, sequence_number=<uint32>, block_index=<uint32>, n_measurements=<int>
[mac_address=0x<hex>, status="<status_string>"<conditional_fields>]<additional_measurements>
}
Always Present Fields
These fields are always included in every message:
- session_handle (uint32) - Session identifier
- sequence_number (uint32) - Sequence number of the ranging round
- block_index (uint32) - Block index within the session
- n_measurements (int) - Number of measurement blocks that follow
- mac_address (hex 0xXXXX) - Short MAC address of the measured device
- status (string) - Ranging result status (see status values below)
Status Values
The status field indicates the success/failure of the ranging attempt:
- “SUCCESS” - Ranging completed successfully
- “TX_FAILED” - Transmission failed
- “RX_TIMEOUT” - Reception timeout occurred
- “RX_PHY_DEC_FAILED” - Physical layer decoding failed
- “RX_PHY_TOA_FAILED” - Time of Arrival calculation failed
- “RX_PHY_STS_FAILED” - STS (Scrambled Timestamp Sequence) failed
- “RX_MAC_DEC_FAILED” - MAC layer decoding failed
- “RX_MAC_IE_DEC_FAILED” - MAC Information Element decoding failed
- “RX_MAC_IE_MISSING” - MAC Information Element missing
- “Unknown” - Unrecognised status code
Conditional Fields (Only When status=“SUCCESS”)
These fields are only present when ranging was successful (status="SUCCESS"):
Always Present on Success
- distance[cm] (int) - Distance in centimeters
Conditionally Present on Success
- loc_az_pdoa (float) - Local azimuth PDOA in degrees
- Condition:
local_aoa_measurements[0].aoa_fom_100 > 0
- loc_az (float) - Local azimuth AOA in degrees
- Condition:
local_aoa_measurements[0].aoa_fom_100 > 0
- loc_el_pdoa (float) - Local elevation PDOA in degrees
- Condition:
local_aoa_measurements[1].aoa_fom_100 > 0
- loc_el (float) - Local elevation AOA in degrees
- Condition:
local_aoa_measurements[1].aoa_fom_100 > 0
- rmt_az (float) - Remote azimuth AOA in degrees
- Condition:
remote_aoa_azimuth_fom_100 > 0
- rmt_el (float) - Remote elevation AOA in degrees
- Condition:
remote_aoa_elevation_fom_100 > 0
- RSSI[dBm] (float) - Received Signal Strength Indicator in dBm
Data Formats
- Angles: All angle measurements are converted from Q16 fixed-point format to degrees using the formula:
degrees = (360.0 * value_q16 / 65536)
- RSSI: Converted from Q7 fixed-point format to dBm using:
dBm = (-1.0 * value_q7 / 2)
- Distance: Integer value in centimeters
- MAC Address: 16-bit hexadecimal value prefixed with
0x
Multiple Measurements
When n_measurements > 1, measurement blocks are separated by semicolons (;):
SESSION_INFO_NTF: {session_handle=123, sequence_number=45, block_index=6, n_measurements=2
[mac_address=0x1234, status="SUCCESS", distance[cm]=150, RSSI[dBm]=-45.5];
[mac_address=0x5678, status="RX_TIMEOUT"]
}
Example Messages
Successful Ranging (Single Antenna)
SESSION_INFO_NTF: {session_handle=42, sequence_number=123, block_index=5, n_measurements=1
[mac_address=0x1234, status="SUCCESS", distance[cm]=150, RSSI[dBm]=-45.5]
}
Failed Ranging
SESSION_INFO_NTF: {session_handle=42, sequence_number=124, block_index=5, n_measurements=1
[mac_address=0x1234, status="RX_TIMEOUT"]
}
Successful Ranging with AOA (Multi-Antenna)
SESSION_INFO_NTF: {session_handle=42, sequence_number=125, block_index=5, n_measurements=1
[mac_address=0x1234, status="SUCCESS", distance[cm]=150, loc_az_pdoa=25.30, loc_az=27.45, loc_el_pdoa=-5.20, loc_el=-3.10, RSSI[dBm]=-45.5]
}
Parsing Notes
- Error Handling: Always check the
status field first. Only parse distance and other measurements when status="SUCCESS"
- Field Presence: Don’t assume optional fields will be present. Check for their existence before parsing
- Single vs Multi-Antenna: Single antenna setups will never have AOA fields (
loc_az_pdoa, loc_az, etc.)
- Message Boundaries: Use curly braces
{} to identify complete message blocks
- Measurement Boundaries: Use square brackets
[] to identify individual measurement data within a message
Additional Messages
The system also generates other message types:
SESSION_STATUS_NTF
Reports session state changes:
SESSION_STATUS_NTF: {state="ACTIVE", reason="State change with session management commands"}
RANGE_DIAGNOSTICS_NTF
Provides detailed frame-level diagnostics (when enabled):
RANGE_DIAGNOSTICS_NTF: {n_reports=3
[msg_id=RANGING_INITIATION, action=TX, antenna_set=0, frame_status={SUCCESS: 1, WIFI_COEX: 0, GRANT_DURATION_EXCEEDED: 0}, cfo_present=1, cfo_ppm=15.23, nb_aoa=2
tdoa=1234, pdoa=5678, aoa=9012, fom=85, type=1
tdoa=2345, pdoa=6789, aoa=0123, fom=78, type=1];
[msg_id=RANGING_RESPONSE, action=RX, antenna_set=0, frame_status={SUCCESS: 1, WIFI_COEX: 0, GRANT_DURATION_EXCEEDED: 0}, cfo_present=0, nb_aoa=0]
}
Hopefully that’s complete enough for you.