nrf_dm.h

Go to the documentation of this file.

/*
 * Copyright (c) 2022 Nordic Semiconductor ASA
 *
 * SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
 */
 
#ifndef __NRF_DM_H_
#define __NRF_DM_H_
 
#include <stdint.h>
#include "nrf.h"
#include "nrf_dm_version.h"
 
#ifdef __cplusplus
extern "C" {
#endif
 
typedef enum {
        NRF_DM_QUALITY_OK = 0,
        NRF_DM_QUALITY_POOR = 1,
        NRF_DM_QUALITY_DO_NOT_USE = 2,
        NRF_DM_QUALITY_CRC_FAIL = 3,
} nrf_dm_quality_t;
 
typedef enum {
        NRF_DM_SINR_INDICATOR_HIGH     = 0,
        NRF_DM_SINR_INDICATOR_MEDIUM   = 1,
        NRF_DM_SINR_INDICATOR_LOW      = 2,
        NRF_DM_SINR_INDICATOR_VERY_LOW = 3,
} nrf_dm_sinr_indicator_t;
 
typedef enum {
        NRF_DM_ROLE_NONE = 0,
        NRF_DM_ROLE_INITIATOR = 1,
        NRF_DM_ROLE_REFLECTOR = 2,
} nrf_dm_role_t;
 
typedef enum {
        NRF_DM_STATUS_SUCCESS = 0,
        NRF_DM_STATUS_FAIL_SYNC = 1,
        NRF_DM_STATUS_EVENT_FAIL_TIMEOUT = 2,
        NRF_DM_STATUS_CONF_INVALID = 3
} nrf_dm_status_t;
 
typedef enum {
        NRF_DM_RANGING_MODE_RTT,
        NRF_DM_RANGING_MODE_MCPD,
} nrf_dm_ranging_mode_t;
 
typedef struct {
        float i_local[80];
        float q_local[80];
        float i_remote[80];
        float q_remote[80];
} nrf_dm_iq_tones_t;
 
typedef struct {
        nrf_dm_sinr_indicator_t sinr_indicator_local[80];
        nrf_dm_sinr_indicator_t sinr_indicator_remote[80];
} nrf_dm_iq_tones_sinr_indicator_t;
 
typedef union {
        struct _mcpd {
                float ifft;
                float phase_slope;
                float rssi_openspace;
                float best;
        } mcpd;
 
        struct _rtt {
                float rtt;
        } rtt;
} nrf_dm_dist_estimates_t;
 
typedef enum {
        NRF_DM_ANTENNA_COMP_1_1,
        NRF_DM_ANTENNA_COMP_2_1,
        NRF_DM_ANTENNA_COMP_3_1,
        NRF_DM_ANTENNA_COMP_4_1,
        NRF_DM_ANTENNA_COMP_1_2,
        NRF_DM_ANTENNA_COMP_1_3,
        NRF_DM_ANTENNA_COMP_1_4,
        NRF_DM_ANTENNA_COMP_2_2,
} nrf_dm_antenna_composition_t;
 
typedef struct {
        nrf_dm_iq_tones_t iq_tones[NRF_DM_MAX_NUM_ANT];
 
        nrf_dm_iq_tones_sinr_indicator_t tone_sinr_indicators;
 
        nrf_dm_ranging_mode_t ranging_mode;
        nrf_dm_dist_estimates_t distance_estimates;
 
        nrf_dm_status_t status;
 
        uint8_t link_loss;
 
        uint8_t rssi_local;
        uint8_t rssi_remote;
 
        int8_t txpwr_local;
        int8_t txpwr_remote;
 
        nrf_dm_quality_t quality;
 
        int32_t rtt_accumulated_ns;
 
        uint8_t rtt_count;
} nrf_dm_report_t;
 
typedef struct {
        uint8_t gpio;
        uint8_t gpio_te;
} nrf_dm_antenna_gpio_t;
 
typedef struct {
        uint8_t antenna_gpios_count;
        nrf_dm_antenna_gpio_t *antenna_gpios;
        uint8_t switch_pattern_count;
        uint32_t *switch_pattern;
} nrf_dm_antenna_config_t;
 
#define NRF_DM_DEFAULT_SINGLE_ANTENNA_CONFIG                                               \
        ((nrf_dm_antenna_config_t){                                                        \
                .antenna_gpios_count = 0,                                                  \
                .antenna_gpios = NULL,                                                     \
                .switch_pattern_count = 0,                                                 \
                .switch_pattern = NULL,                                                    \
        })
 
typedef struct {
        uint8_t ppi_chan_count;
        uint8_t *ppi_chan;
} nrf_dm_ppi_config_t;
 
typedef struct {
        nrf_dm_role_t role;
        nrf_dm_ranging_mode_t ranging_mode;
        uint32_t rng_seed;
        uint32_t tx_power_dbm;
        nrf_dm_antenna_composition_t ant_comp;
} nrf_dm_config_t;
 
#if defined(RADIO_TXPOWER_TXPOWER_Pos8dBm)
#define NRF_DM_DEFAULT_TX_POWER RADIO_TXPOWER_TXPOWER_Pos8dBm
#elif defined(RADIO_TXPOWER_TXPOWER_Pos4dBm)
#define NRF_DM_DEFAULT_TX_POWER RADIO_TXPOWER_TXPOWER_Pos4dBm
#elif defined(RADIO_TXPOWER_TXPOWER_Pos1dBm)
#define NRF_DM_DEFAULT_TX_POWER RADIO_TXPOWER_TXPOWER_Pos1dBm
#elif defined(RADIO_TXPOWER_TXPOWER_0dBm)
#define NRF_DM_DEFAULT_TX_POWER RADIO_TXPOWER_TXPOWER_0dBm
#endif
 
#define NRF_DM_DEFAULT_ANTENNA_COMP (NRF_DM_ANTENNA_COMP_1_1)
#define NRF_DM_DEFAULT_CONFIG                                                          \
        ((nrf_dm_config_t){                                                            \
                .role = NRF_DM_ROLE_NONE,                                              \
                .ranging_mode = NRF_DM_RANGING_MODE_MCPD,                              \
                .rng_seed = 0,                                                         \
                .tx_power_dbm = NRF_DM_DEFAULT_TX_POWER,                               \
                .ant_comp = NRF_DM_DEFAULT_ANTENNA_COMP,                               \
        })
 
 
void nrf_dm_init(const nrf_dm_ppi_config_t *ppi_cfg, const nrf_dm_antenna_config_t *antenna_cfg,
                 NRF_TIMER_Type * timer);
 
nrf_dm_status_t nrf_dm_configure(const nrf_dm_config_t *config);
 
uint32_t nrf_dm_get_duration_us(const nrf_dm_config_t *config);
 
#define NRF_DM_PROC_EXECUTE_DURATION_OVERHEAD_US (200)
 
 
nrf_dm_status_t nrf_dm_proc_execute(uint32_t timeout_us);
 
void nrf_dm_populate_report(nrf_dm_report_t *p_report);
 
#define NRF_DM_CHANNEL_MAP_LEN 75
 
void nrf_dm_get_hopping_sequence(const nrf_dm_config_t *config,
                                 uint8_t hopping_sequence[NRF_DM_CHANNEL_MAP_LEN]);
 
nrf_dm_quality_t nrf_dm_calc(nrf_dm_report_t *p_report);
 
float nrf_dm_high_precision_calc(nrf_dm_report_t *p_report);
 
const char *nrf_dm_version_string_get(void);
 
#ifdef __cplusplus
}
#endif
 
#endif // __NRF_DM_H_