ble_dtm.h

00001 /* Copyright (c) 2012 Nordic Semiconductor. All Rights Reserved.
00002  *
00003  * The information contained herein is property of Nordic Semiconductor ASA.
00004  * Terms and conditions of usage are described in detail in NORDIC
00005  * SEMICONDUCTOR STANDARD SOFTWARE LICENSE AGREEMENT.
00006  *
00007  * Licensees are granted free, non-transferable use of the information. NO
00008  * WARRANTY of ANY KIND is provided. This heading must NOT be removed from
00009  * the file.
00010  *
00011  */
00012 
00013 /** @file
00014  *
00015  * @defgroup ble_sdk_dtmlib_dtm DTM - Direct Test Mode
00016  * @{
00017  * @ingroup ble_sdk_lib
00018  * @brief Module for testing RF/PHY using DTM commands.
00019  */
00020 
00021 #ifndef BLE_DTM_H__
00022 #define BLE_DTM_H__
00023 
00024 #include <stdint.h>
00025 #include <stdbool.h>
00026 #include "nordic_global.h"
00027 
00028 
00029 /**@brief Configuration parameters. */
00030 #define DEFAULT_TX_POWER                RADIO_TXPOWER_TXPOWER_Pos4dBm   /**< Default Transmission power using in the DTM module. */
00031 #define DEFAULT_TIMER                   NRF_TIMER0                      /**< Default timer used for timing. */
00032 #define DEFAULT_TIMER_IRQn              TIMER0_IRQn                     /**< IRQ used for timer. NOTE: MUST correspond to DEFAULT_TIMER. */
00033 
00034 /**@brief BLE DTM command codes. */
00035 typedef uint32_t dtm_cmd_t;                                             /**< DTM command type. */
00036 
00037 #define LE_RESET                        0                               /**< DTM command: Reset device. */
00038 #define LE_RECEIVER_TEST                1                               /**< DTM command: Start receive test. */
00039 #define LE_TRANSMITTER_TEST             2                               /**< DTM command: Start transmission test. */
00040 #define LE_TEST_END                     3                               /**< DTM command: End test and send packet report. */
00041 
00042 // Configuration options used as parameter 2
00043 // when cmd == LE_TRANSMITTER_TEST and payload == DTM_PKT_VENDORSPECIFIC
00044 // Configuration value, if any, is supplied in parameter 3
00045 
00046 #define CARRIER_TEST                    0                               /**< Length=0 indicates a constant, unmodulated carrier until LE_TEST_END or LE_RESET */
00047 #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 */
00048 #define SET_TX_POWER                    2                               /**< Set transmission power, value -40..+4 dBm in steps of 4 */
00049 #define SELECT_TIMER                    3                               /**< Select on of the 16 MHz timers 0, 1 or 2 */
00050 
00051 #define LE_PACKET_REPORTING_EVENT       0x8000                          /**< DTM Packet reporting event, returned by the device to the tester. */
00052 #define LE_TEST_STATUS_EVENT_SUCCESS    0x0000                          /**< DTM Status event, indicating success. */
00053 #define LE_TEST_STATUS_EVENT_ERROR      0x0001                          /**< DTM Status event, indicating an error. */
00054 
00055 #define DTM_PKT_PRBS9                   0x00                            /**< Bit pattern PRBS9. */
00056 #define DTM_PKT_0X0F                    0x01                            /**< Bit pattern 11110000 (LSB is the leftmost bit). */
00057 #define DTM_PKT_0X55                    0x02                            /**< Bit pattern 10101010 (LSB is the leftmost bit). */
00058 #define DTM_PKT_VENDORSPECIFIC          0xFFFFFFFF                      /**< Vendor specific. Nordic: Continuous carrier test, or configuration. */
00059 
00060 /**@brief Return codes from dtm_cmd(). */
00061 #define DTM_SUCCESS                     0x00                            /**< Indicate that the DTM function completed with success. */
00062 #define DTM_ERROR_ILLEGAL_CHANNEL       0x01                            /**< Physical channel number must be in the range 0..39. */
00063 #define DTM_ERROR_INVALID_STATE         0x02                            /**< Sequencing error: Command is not valid now. */
00064 #define DTM_ERROR_ILLEGAL_LENGTH        0x03                            /**< Payload size must be in the range 0..37. */
00065 #define DTM_ERROR_ILLEGAL_CONFIGURATION 0x04                            /**< Parameter out of range (legal range is function dependent). */
00066 #define DTM_ERROR_UNINITIALIZED         0x05                            /**< DTM module has not been initialized by the application. */
00067 
00068 // Note: DTM_PKT_VENDORSPECIFIC, is not a packet type
00069 #define PACKET_TYPE_MAX                 DTM_PKT_0X55                    /**< Highest value allowed as DTM Packet type. */
00070 
00071 /** @brief BLE DTM event type. */
00072 typedef uint32_t dtm_event_t;                                           /**< Type for handling DTM event. */
00073 
00074 /** @brief BLE DTM frequency type. */
00075 typedef uint32_t dtm_freq_t;                                            /**< Physical channel, valid range: 0..39. */
00076 
00077 /**@brief BLE DTM packet types. */
00078 typedef uint32_t dtm_pkt_type_t;                                        /**< Type for holding the requested DTM payload type.*/
00079 
00080 
00081 /**@brief Function for initializing or re-initializing DTM module
00082  *     
00083  * @return DTM_SUCCESS on successful initialization of the DTM module.
00084 */
00085 uint32_t dtm_init(void);
00086 
00087 
00088 /**@brief Function for giving control to dtmlib for handling timer and radio events.
00089  *        Will return to caller at 625us intervals or whenever another event than radio occurs
00090  *        (such as UART input). Function will put MCU to sleep between events.
00091  *
00092  * @return      Time counter, incremented every 625 us.
00093  */
00094 uint32_t dtm_wait(void);
00095 
00096 
00097 /**@brief Function for calling when a complete command has been prepared by the Tester.
00098  *
00099  * @param[in]   cmd       One of the DTM_CMD values (bits 14:15 in the 16-bit UART format).
00100  * @param[in]   freq      Phys. channel no - actual frequency = (2402 + freq * 2) MHz (bits 8:13 in
00101  *                        the 16-bit UART format).
00102  * @param[in]   length    Payload length, 0..37 (bits 2:7 in the 16-bit UART format).
00103  * @param[in]   payload   One of the DTM_PKT values (bits 0:1 in the 16-bit UART format).
00104  *
00105  * @return      DTM_SUCCESS or one of the DTM_ERROR_ values
00106  */
00107 uint32_t dtm_cmd(dtm_cmd_t cmd, dtm_freq_t freq, uint32_t length, dtm_pkt_type_t payload);
00108 
00109 
00110 /**@brief Function for reading the result of a DTM command
00111  *
00112  * @param[out]  p_dtm_event   Pointer to buffer for 16 bit event code according to DTM standard.
00113  * 
00114  * @return      true: new event, false: no event since last call, this event has been read earlier
00115  */
00116 bool dtm_event_get(dtm_event_t * p_dtm_event);
00117 
00118 
00119 /**@brief Function for configuring the timer to use.
00120  *
00121  * @note        Must be called when no DTM test is running. 
00122  * 
00123  * @param[in]   new_timer   Index (0..2) of timer to be used by the DTM library
00124  *
00125  * @return      true: success, new timer was selected, false: parameter error 
00126  */
00127 bool dtm_set_timer(uint32_t new_timer); 
00128 
00129 
00130 /**@brief Function for configuring the transmit power.
00131  *
00132  * @note        Must be called when no DTM test is running.
00133  * 
00134  * @param[in]   new_tx_power   New output level, +4..-40, in steps of 4.
00135  *
00136  * @return      true: tx power setting changed, false: parameter error
00137  */
00138 bool dtm_set_txpower(uint32_t new_tx_power);
00139 
00140 #endif // BLE_DTM_H__
00141 
00142 /** @} */