/** * Copyright (c) 2012 - 2020, Nordic Semiconductor ASA * * All rights reserved. * * Redistribution and use in source and binary forms, with or without modification, * are permitted provided that the following conditions are met: * * 1. Redistributions of source code must retain the above copyright notice, this * list of conditions and the following disclaimer. * * 2. Redistributions in binary form, except as embedded into a Nordic * Semiconductor ASA integrated circuit in a product or a software update for * such product, must reproduce the above copyright notice, this list of * conditions and the following disclaimer in the documentation and/or other * materials provided with the distribution. * * 3. Neither the name of Nordic Semiconductor ASA nor the names of its * contributors may be used to endorse or promote products derived from this * software without specific prior written permission. * * 4. This software, with or without modification, must only be used with a * Nordic Semiconductor ASA integrated circuit. * * 5. Any software provided in binary form under this license must not be reverse * engineered, decompiled, modified and/or disassembled. * * THIS SOFTWARE IS PROVIDED BY NORDIC SEMICONDUCTOR ASA "AS IS" AND ANY EXPRESS * OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES * OF MERCHANTABILITY, NONINFRINGEMENT, AND FITNESS FOR A PARTICULAR PURPOSE ARE * DISCLAIMED. IN NO EVENT SHALL NORDIC SEMICONDUCTOR ASA OR CONTRIBUTORS BE * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE * GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. * */ /** @file * * @defgroup ble_dtm DTM - Direct Test Mode * @{ * @ingroup ble_sdk_lib * @brief Module for testing RF/PHY using DTM commands. */ #ifndef BLE_DTM_H__ #define BLE_DTM_H__ #include #include #include "nrf.h" #ifdef __cplusplus extern "C" { #endif #define DTM_MAX_ANTENNA_CNT 0x13 /**< Maximum supported antenna count. */ /**@brief Configuration parameters. */ #define DTM_BITRATE UARTE_BAUDRATE_BAUDRATE_Baud19200 /**< Serial bitrate on the UART */ #define DEFAULT_TX_POWER RADIO_TXPOWER_TXPOWER_0dBm /**< Default Transmission power using in the DTM module. */ #define DEFAULT_TIMER NRF_TIMER0 /**< Default timer used for timing. */ #define DEFAULT_TIMER_IRQn TIMER0_IRQn /**< IRQ used for timer. NOTE: MUST correspond to DEFAULT_TIMER. */ #define ANOMALY_172_TIMER NRF_TIMER1 /**< Timer used for the workaround for errata 172 on affected nRF5 devices. */ #define ANOMALY_172_TIMER_IRQn TIMER1_IRQn /**< IRQ used for timer. NOTE: MUST correspond to ERRATA_172_TIMER. */ #define ANOMALY_172_TIMER_IRQHandler TIMER1_IRQHandler /**< IRQHandler used for timer. NOTE: MUST correspond to ERRATA_172_TIMER. */ /**@brief BLE DTM command codes. */ typedef uint32_t dtm_cmd_t; /**< DTM command type. */ #define LE_TEST_SETUP 0 /**< DTM command: Set PHY or modulation, configure upper two bits of length, request matrix of supported features or request max values of parameters. */ #define LE_RECEIVER_TEST 1 /**< DTM command: Start receive test. */ #define LE_TRANSMITTER_TEST 2 /**< DTM command: Start transmission test. */ #define LE_TEST_END 3 /**< DTM command: End test and send packet report. */ #define LE_TEST_SETUP_RESET 0 /**< DTM command control: Stop TX/RX, reset the packet length upper bits and set the PHY to 1Mbit. */ #define LE_TEST_SETUP_SET_UPPER 1 /**< DTM command control: Set the upper two bits of the length field. */ #define LE_TEST_SETUP_SET_PHY 2 /**< DTM command control: Select the PHY to be used for packets. */ #define LE_TEST_SETUP_SELECT_MODULATION 3 /**< DTM command control: Select standard or stable modulation index. Stable modulation index is not supported. */ #define LE_TEST_SETUP_READ_SUPPORTED 4 /**< DTM command control: Read the supported test case features. */ #define LE_TEST_SETUP_READ_MAX 5 /**< DTM command control: Read the max supported time and length for packets. */ #define LE_TEST_SETUP_CONSTANT_TONE 6 /**< DTM command control: Constant Tone Extension info. */ #define LE_TEST_SETUP_CONSTANT_TONE_SLOT 7 /**< DTM command control: Constant Tone Extension slot. */ #define LE_TEST_SETUP_ANTENNA_ARRAY 8 /**< DTM command control: Antenna number and switch patern. */ #define LE_TEST_SETUP_TRANSMIT_POWER 9 /**< DTM command control: Transmit power set. */ #define LE_RESET_MIN_RANGE 0x00 /**< DTM command parameter: Reset. Minimum parameter value. */ #define LE_RESET_MAX_RANGE 0x03 /**< DTM command parameter: Reset. Maximum parameter value. */ #define LE_SET_UPER_BITS_MIN_RANGE 0x00 /**< DTM command parameter: Set upper bits. Minimum parameter value. */ #define LE_SET_UPER_BITS_MAX_RANGE 0x0F /**< DTM command parameter: Set upper bits. Maximum parameter value. */ #define LE_PHY_1M_MIN_RANGE 0x04 /**< DTM command parameter: Set PHY for future packets to use 1MBit PHY. Minimum parameter value. */ #define LE_PHY_1M_MAX_RANGE 0x07 /**< DTM command parameter: Set PHY for future packets to use 1MBit PHY. Maximum parameter value. */ #define LE_PHY_2M_MIN_RANGE 0x08 /**< DTM command parameter: Set PHY for future packets to use 2MBit PHY. Minimum parameter value. */ #define LE_PHY_2M_MAX_RANGE 0x0B /**< DTM command parameter: Set PHY for future packets to use 2MBit PHY. Maximum parameter value. */ #define LE_PHY_LE_CODED_S8_MIN_RANGE 0x0C /**< DTM command parameter: Set PHY for future packets to use coded PHY with S=8. Minimum parameter value. */ #define LE_PHY_LE_CODED_S8_MAX_RANGE 0x0F /**< DTM command parameter: Set PHY for future packets to use coded PHY with S=8. Maximum parameter value. */ #define LE_PHY_LE_CODED_S2_MIN_RANGE 0x10 /**< DTM command parameter: Set PHY for future packets to use coded PHY with S=2. Minimum parameter value. */ #define LE_PHY_LE_CODED_S2_MAX_RANGE 0x13 /**< DTM command parameter: Set PHY for future packets to use coded PHY with S=2. Maximum parameter value. */ #define LE_MODULATION_INDEX_STANDARD_MIN_RANGE 0x00 /**< DTM command parameter: Set Modulation index to stadard. Minimum parameter value. */ #define LE_MODULATION_INDEX_STANDARD_MAX_RANGE 0x03 /**< DTM command parameter: Set Modulation index to stadard. Maximum parameter value. */ #define LE_MODULATION_INDEX_STABLE_MIN_RANGE 0x04 /**< DTM command parameter: Set Modulation index to stable. Minimum parameter value. */ #define LE_MODULATION_INDEX_STABLE_MAX_RANGE 0x07 /**< DTM command parameter: Set Modulation index to stable. Maximum parameter value. */ #define LE_TEST_FEATURE_READ_MIN_RANGE 0x00 /**< DTM command parameter: Read test case supported feature. Minimum parameter value. */ #define LE_TEST_FEATURE_READ_MAX_RANGE 0x03 /**< DTM command parameter: Read test case supported feature. Maximum parameter value. */ #define LE_TEST_SUPPORTED_TX_OCTETS_MIN_RANGE 0x00 /**< DTM command parameter: Read maximum supported Tx Octets. Minimum parameter value. */ #define LE_TEST_SUPPORTED_TX_OCTETS_MAX_RANGE 0x03 /**< DTM command parameter: Read maximum supported Tx Octets. Maximum parameter value. */ #define LE_TEST_SUPPORTED_TX_TIME_MIN_RANGE 0x04 /**< DTM command parameter: Read maximum supported Tx Time. Minimum parameter value. */ #define LE_TEST_SUPPORTED_TX_TIME_MAX_RANGE 0x07 /**< DTM command parameter: Read maximum supported Tx Time. Maximum parameter value. */ #define LE_TEST_SUPPORTED_RX_OCTETS_MIN_RANGE 0x08 /**< DTM command parameter: Read maximum supported Rx Octets. Minimum parameter value. */ #define LE_TEST_SUPPORTED_RX_OCTETS_MAX_RANGE 0x0B /**< DTM command parameter: Read maximum supported Rx Octets. Maximum parameter value. */ #define LE_TEST_SUPPORTED_RX_TIME_MIN_RANGE 0x0C /**< DTM command parameter: Read maximum supported Rx Time. Minimum parameter value. */ #define LE_TEST_SUPPORTED_RX_TIME_MAX_RANGE 0x0F /**< DTM command parameter: Read maximum supported Rx Time. Maximum parameter value. */ #define LE_TEST_SUPPORTED_CTE_LENGTH 0x10 /**< DTM command parameter: Read maximum length of the Constant Tone Extension supported. */ #define LE_UPPER_BITS_MASK 0x0C /**< DTM command parameter: Upper bits mask. */ #define LE_UPPER_BITS_POS 0x04 /**< DTM command parameter: Upper bits position. */ #define LE_TRANSMIT_POWER_LVL_MIN -127 /**< DTM command parameter: Minimum supported transmit power level. */ #define LE_TRANSMIT_POWER_LVL_MAX 20 /**< DTM command parameter: Maximum supported transmit power level. */ #define LE_TRANSMIT_POWER_LVL_SET_MIN 0x7E /**< DTM command parameter: Set minimum transmit power level. */ #define LE_TRANSMIT_POWER_LVL_SET_MAX 0x7F /**< DTM command parameter: Set maximum taranmit poer level. */ #define LE_TRANSMIT_POWER_RESPONSE_LVL_POS (0x01) /** Position of power level in the DTM power level set response. */ #define LE_TRANSMIT_POWER_RESPONSE_LVL_MASK (0x1FE) /** Mask of the power level in the DTM power level set respose. */ #define LE_TRANSMIT_POWER_MAX_LVL_BIT (1 << 0x0A) /** Maximum power level bit in the power level set response. */ #define LE_TRANSMIT_POWER_MIN_LVL_BIT (1 << 0x09) /** Minimum power level bit in the power level set response. */ #define LE_CTE_TYPE_MASK 0x03 /** Mask of the CTE type in the CTEInfo. */ #define LE_CTE_TYPE_POS 0x06 /** Position of the CTE type in the CTEInfo. */ #define LE_CTE_CTETIME_MASK 0x1F /** Mask of the CTE Time in the CTEInfo. */ #define LE_CTE_TYPE_AOA 0x00 /** CTE Type Angle of Arrival. */ #define LE_CTE_TYPE_AOD_1US 0x01 /** CTE Type Angle of Departure with 1 us slot. */ #define LE_CTE_TYPE_AOD_2US 0x02 /** CTE Type Angle of Departure with 2 us slot.*/ #define LE_CTE_LENGTH_MIN 0x02 /**< DTM command parameter: Minimum supported CTE length in 8 us units. */ #define LE_CTE_LENGTH_MAX 0x14 /**< DTM command parameter: Maximum supported CTE length in 8 us units. */ #define LE_ANTENNA_NUMBER_MASK 0x3F /**< DTM command parameter: Mask of the Antenna Number. */ #define LE_ANTENA_SWITCH_PATTERN_MASK 0x80 /**< DTM command parameter: Mask of the Antenna switch pattern. */ #define LE_TEST_ANTENNA_NUMBER_MIN 0x01 /**< Minimum antenna number. */ #define LE_TEST_ANTENNA_NUMBER_MAX 0x4B /**< Maximum antenna number. */ // Configuration options used as parameter 2 // when cmd == LE_TRANSMITTER_TEST and payload == DTM_PKT_VENDORSPECIFIC // Configuration value, if any, is supplied in parameter 3 #define CARRIER_TEST 0 /**< Length=0 indicates a constant, unmodulated carrier until LE_TEST_END or LE_RESET */ #define CARRIER_TEST_STUDIO 1 /**< nRFgo Studio uses value 1 in length field, to indicate a constant, unmodulated carrier until LE_TEST_END or LE_RESET */ #define SET_TX_POWER 2 /**< Set transmission power, value -40..+4 dBm in steps of 4 */ #define SELECT_TIMER 3 /**< Select on of the 16 MHz timers 0, 1 or 2 */ #define SET_NRF21540_TX_POWER 4 /**< Set nRF21540 transmission power level. Choose between two predefinied option +20 dBm or +10 dBm. */ #define LE_PACKET_REPORTING_EVENT 0x8000 /**< DTM Packet reporting event, returned by the device to the tester. */ #define LE_TEST_STATUS_EVENT_SUCCESS 0x0000 /**< DTM Status event, indicating success. */ #define LE_TEST_STATUS_EVENT_ERROR 0x0001 /**< DTM Status event, indicating an error. */ #define DTM_PKT_PRBS9 0x00 /**< Bit pattern PRBS9. */ #define DTM_PKT_0X0F 0x01 /**< Bit pattern 11110000 (LSB is the leftmost bit). */ #define DTM_PKT_0X55 0x02 /**< Bit pattern 10101010 (LSB is the leftmost bit). */ #define DTM_PKT_0XFF 0x03 /**< Bit pattern 11111111 (Used only for coded PHY). */ #define DTM_PKT_VENDORSPECIFIC 0x03 /**< Vendor specific PKT field value. Nordic: Continuous carrier test, or configuration. */ #define DTM_PKT_TYPE_VENDORSPECIFIC 0xFF /**< Vendor specific packet type for internal use. */ #define DTM_PKT_CP_BIT 0x20 /**< CTEInfo Preset bit. Indicates whether the CTEInfo field is present in the packet. */ // The pdu payload type for each bit pattern. Identical to the PKT value except pattern 0xFF which is 0x04. #define DTM_PDU_TYPE_PRBS9 0x00 /**< PDU payload type for bit pattern PRBS9. */ #define DTM_PDU_TYPE_0X0F 0x01 /**< PDU payload type for bit pattern 11110000 (LSB is the leftmost bit). */ #define DTM_PDU_TYPE_0X55 0x02 /**< PDU payload type for bit pattern 10101010 (LSB is the leftmost bit). */ #define DTM_PDU_TYPE_0XFF 0x04 /**< PDU payload type for bit pattern 11111111 (Used only for coded PHY). */ /**@brief Return codes from dtm_cmd(). */ #define DTM_SUCCESS 0x00 /**< Indicate that the DTM function completed with success. */ #define DTM_ERROR_ILLEGAL_CHANNEL 0x01 /**< Physical channel number must be in the range 0..39. */ #define DTM_ERROR_INVALID_STATE 0x02 /**< Sequencing error: Command is not valid now. */ #define DTM_ERROR_ILLEGAL_LENGTH 0x03 /**< Payload size must be in the range 0..37. */ #define DTM_ERROR_ILLEGAL_CONFIGURATION 0x04 /**< Parameter out of range (legal range is function dependent). */ #define DTM_ERROR_UNINITIALIZED 0x05 /**< DTM module has not been initialized by the application. */ #define DTM_LE_DATA_PACKET_LEN_EXTENSION 0x02 /**< DTM Status Response: LE Data Packet Length Extension feature supported. */ #define DTM_LE_2M_PHY 0x04 /**< DTM Status Response: LE 2M PHY supported. */ #define DTM_LE_STABLE_MODULATION_INDEX 0x08 /**< DTM Status Response: Transmitter has a Stable Modulation Index. */ #define DTM_LE_CODED_PHY 0x10 /**< DTM Status Response: LE Coded PHY supported. */ #define DTM_LE_CONSTANT_TONE_EXTENSION 0x20 /**< DTM Status Response: Constant Tone Extension Supported. */ #define DTM_LE_ANTENNA_SWITCH 0x40 /**< DTM Status Response: Antenna switching supported. */ #define DTM_LE_AOD_1US_TANSMISSION 0x80 /**< DTM Status Response: 1us switching supported for AoD tansmission. */ #define DTM_LE_AOD_1US_RECEPTION 0x100 /**< DTM Status Response: 1us sampling supported for AoA reception. */ #define DTM_LE_AOA_1US_RECEPTION 0x200 /**< DTM Status Response: 1us switching and sampling supported for AoA reception. */ /**@details The UART poll cycle in micro seconds. * A baud rate of e.g. 19200 bits / second, and 8 data bits, 1 start/stop bit, no flow control, * give the time to transmit a byte: 10 bits * 1/19200 = approx: 520 us. * To ensure no loss of bytes, the UART should be polled every 260 us. */ #if DTM_BITRATE == UARTE_BAUDRATE_BAUDRATE_Baud9600 #define UART_POLL_CYCLE ((uint32_t)(10*1e6/9600/2)) #elif DTM_BITRATE == UARTE_BAUDRATE_BAUDRATE_Baud14400 #define UART_POLL_CYCLE ((uint32_t)(10*1e6/14400/2)) #elif DTM_BITRATE == UARTE_BAUDRATE_BAUDRATE_Baud19200 #define UART_POLL_CYCLE ((uint32_t)(10*1e6/19200/2)) #elif DTM_BITRATE == UARTE_BAUDRATE_BAUDRATE_Baud28800 #define UART_POLL_CYCLE ((uint32_t)(10*1e6/28800/2)) #elif DTM_BITRATE == UARTE_BAUDRATE_BAUDRATE_Baud38400 #define UART_POLL_CYCLE ((uint32_t)(10*1e6/38400/2)) #elif DTM_BITRATE == UARTE_BAUDRATE_BAUDRATE_Baud57600 #define UART_POLL_CYCLE ((uint32_t)(10*1e6/57600/2)) #elif DTM_BITRATE == UARTE_BAUDRATE_BAUDRATE_Baud76800 #define UART_POLL_CYCLE ((uint32_t)(10*1e6/768000/2)) #elif DTM_BITRATE == UARTE_BAUDRATE_BAUDRATE_Baud115200 #define UART_POLL_CYCLE ((uint32_t)(10*1e6/115200/2)) #elif DTM_BITRATE == UARTE_BAUDRATE_BAUDRATE_Baud230400 #define UART_POLL_CYCLE ((uint32_t)(10*1e6/230400/2)) #elif DTM_BITRATE == UARTE_BAUDRATE_BAUDRATE_Baud250000 #define UART_POLL_CYCLE ((uint32_t)(10*1e6/250000/2)) #elif DTM_BITRATE == UARTE_BAUDRATE_BAUDRATE_Baud460800 #define UART_POLL_CYCLE ((uint32_t)(10*1e6/460800/2)) #elif DTM_BITRATE == UARTE_BAUDRATE_BAUDRATE_Baud921600 #define UART_POLL_CYCLE ((uint32_t)(10*1e6/921600/2)) #elif DTM_BITRATE == UARTE_BAUDRATE_BAUDRATE_Baud1M #define UART_POLL_CYCLE ((uint32_t)(10*1e6/1e6/2)) #else // It is possible to find values that work for other baud rates, but the formula above is not // guaranteed to work for all values. Suitable values may have to be found by trial and error. #error "Unsupported baud rate set." #endif // Note: DTM_PKT_VENDORSPECIFIC, is not a packet type #define PACKET_TYPE_MAX DTM_PKT_0XFF /**< Highest value allowed as DTM Packet type. */ /** @brief BLE DTM event type. */ typedef uint32_t dtm_event_t; /**< Type for handling DTM event. */ /** @brief BLE DTM frequency type. */ typedef uint32_t dtm_freq_t; /**< Physical channel, valid range: 0..39. */ /**@brief BLE DTM packet types. */ typedef uint32_t dtm_pkt_type_t; /**< Type for holding the requested DTM payload type.*/ /**@brief BLE DTM nRF21540 power mode. */ typedef enum { NRF21540_POWER_MODE_A = 0x01, /**< Set nRF21540 transmission power level to the A(20 dBm) predefinied value. */ NRF21540_POWER_MODE_B = 0x02 /**< Set nRF21540 transmission power level to the B(10 dBm) predefinied value. */ } dtm_nrf21540_power_mode_t; /**@brief Function for initializing or re-initializing DTM module * * @return DTM_SUCCESS on successful initialization of the DTM module. */ uint32_t dtm_init(void); /**@brief Function for giving control to dtmlib for handling timer and radio events. * Will return to caller at 625us intervals or whenever another event than radio occurs * (such as UART input). Function will put MCU to sleep between events. * * @return Time counter, incremented every 625 us. */ uint32_t dtm_wait(void); /**@brief Function for calling when a complete command has been prepared by the Tester. * * @param[in] cmd received 16-bit complete command from the Tester. * * @return DTM_SUCCESS or one of the DTM_ERROR_ values */ uint32_t dtm_cmd(uint16_t cmd); /**@brief Function for reading the result of a DTM command * * @param[out] p_dtm_event Pointer to buffer for 16 bit event code according to DTM standard. * * @return true: new event, false: no event since last call, this event has been read earlier */ bool dtm_event_get(dtm_event_t * p_dtm_event); /**@brief Function for configuring the timer to use. * * @note Must be called when no DTM test is running. * * @param[in] new_timer Index (0..2) of timer to be used by the DTM library * * @return true: success, new timer was selected, false: parameter error */ bool dtm_set_timer(uint32_t new_timer); /**@brief Function for configuring the transmit power. * * @note Must be called when no DTM test is running. * * @param[in] new_tx_power New output level, +4..-40, in steps of 4. * * @return true: tx power setting changed, false: parameter error */ bool dtm_set_txpower(uint32_t new_tx_power); /**@brief Function for choosing nRF21540 power level. * * @note Must be called when no DTM test is running and nRF21540 is used. * * @param[in] power_mode nRF21540 power mode. * * @return true: tx power mode setting changed, false: parameter error */ bool dtm_set_nrf21450_power_mode(dtm_nrf21540_power_mode_t power_mode); #ifdef __cplusplus } #endif #endif // BLE_DTM_H__ /** @} */