1 /* Copyright (c) 2014, Nordic Semiconductor ASA
2  *
3  * Permission is hereby granted, free of charge, to any person obtaining a copy
4  * of this software and associated documentation files (the "Software"), to deal
5  * in the Software without restriction, including without limitation the rights
6  * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
7  * copies of the Software, and to permit persons to whom the Software is
8  * furnished to do so, subject to the following conditions:
9  *
10  * The above copyright notice and this permission notice shall be included in all
11  * copies or substantial portions of the Software.
12  *
13  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
14  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
15  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
16  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
17  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
18  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
19  * SOFTWARE.
20  */
21 
22 /**
23  * @file
24  * @brief Interface for hal_aci_tl.
25  * @ingroup nrf8001
26  */
27 
28 /**
29 @{
30 
31 @brief Module for the ACI Transport Layer interface
32 @details This module is responsible for sending and receiving messages over the ACI interface of the nRF8001 chip.
33  The hal_aci_tl_send_cmd() can be called directly to send ACI commands.
34 
35 
36 The RDYN line is hooked to an interrupt on the MCU when the level is low.
37 The SPI master clocks in the interrupt context.
38 The ACI Command is taken from the head of the command queue is sent over the SPI
39 and the received ACI event is placed in the tail of the event queue.
40 
41 */
42 
43 #ifndef HAL_ACI_TL_H__
44 #define HAL_ACI_TL_H__
45 
46 #include "hal_platform.h"
47 #include "aci.h"
48 #include "boards.h"
49 
50 #include <mraa/aio.h>
51 #include <mraa/gpio.h>
52 #include <mraa/spi.h>
53 
54 #ifndef HAL_ACI_MAX_LENGTH
55 #define HAL_ACI_MAX_LENGTH 31
56 #endif
57 
58 /************************************************************************/
59 /* Unused nRF8001 pin                                                    */
60 /************************************************************************/
61 #define UNUSED          255
62 
63 /** Data type for ACI commands and events */
64 typedef struct {
65   uint8_t status_byte;
66   uint8_t buffer[HAL_ACI_MAX_LENGTH+1];
67 } _aci_packed_ hal_aci_data_t;
68 
69 ACI_ASSERT_SIZE(hal_aci_data_t, HAL_ACI_MAX_LENGTH + 2);
70 
71 /** Datatype for ACI pins and interface (polling/interrupt)*/
72 typedef struct aci_pins_t
73 {
74     mraa_spi_context        m_spi;
75     mraa_gpio_context       m_rdy_ctx;
76     mraa_gpio_context       m_req_ctx;
77     mraa_gpio_context       m_rst_ctx;
78 
79     uint8_t board_name;             //Optional : Use BOARD_DEFAULT if you do not know. See boards.h
80     uint8_t reqn_pin;               //Required
81     uint8_t rdyn_pin;               //Required
82     uint8_t mosi_pin;               //Required
83     uint8_t miso_pin;               //Required
84     uint8_t sck_pin;                //Required
85 
86     uint8_t spi_clock_divider;      //Required : Clock divider on the SPI clock : nRF8001 supports a maximum clock of 3MHz
87 
88     uint8_t reset_pin;              //Recommended but optional - Set it to UNUSED when not connected
89     uint8_t active_pin;             //Optional - Set it to UNUSED when not connected
90     uint8_t optional_chip_sel_pin;  //Optional - Used only when the reqn line is required to be separate from the SPI chip select. Eg. Arduino DUE
91 
92     bool    interface_is_interrupt; //Required - true = Uses interrupt on RDYN pin. false - Uses polling on RDYN pin
93 
94     uint8_t interrupt_number;       //Required when using interrupts, otherwise ignored
95 } aci_pins_t;
96 
97 /** @brief ACI Transport Layer initialization.
98  *  @details
99  *  This function initializes the transport layer, including configuring the SPI, creating
100  *  message queues for Commands and Events and setting up interrupt if required.
101  *  @param a_pins Pins on the MCU used to connect to the nRF8001
102  *  @param bool True if debug printing should be enabled on the Serial.
103  */
104 void hal_aci_tl_init(aci_pins_t *a_pins, bool debug);
105 
106 /** @brief Sends an ACI command to the radio.
107  *  @details
108  *  This function sends an ACI command to the radio. This queue up the message to send and
109  *  lower the request line. When the device lowers the ready line, @ref m_aci_spi_transfer()
110  *  will send the data.
111  *  @param aci_buffer Pointer to the message to send.
112  *  @return True if the data was successfully queued for sending,
113  *  false if there is no more space to store messages to send.
114  */
115 bool hal_aci_tl_send(hal_aci_data_t *aci_buffer);
116 
117 /** @brief Process pending transactions.
118  *  @details
119  *  The library code takes care of calling this function to check if the nRF8001 RDYN line indicates a
120  *  pending transaction. It will send a pending message if there is one and return any receive message
121  *  that was pending.
122  *  @return Points to data buffer for received data. Length byte in buffer is 0 if no data received.
123  */
124 hal_aci_data_t * hal_aci_tl_poll_get(void);
125 
126 /** @brief Get an ACI event from the event queue
127  *  @details
128  *  Call this function from the main context to get an event from the ACI event queue
129  *  This is called by lib_aci_event_get
130  */
131 bool hal_aci_tl_event_get(hal_aci_data_t *p_aci_data);
132 
133 /** @brief Peek an ACI event from the event queue
134  *  @details
135  *  Call this function from the main context to peek an event from the ACI event queue.
136  *  This is called by lib_aci_event_peek
137  */
138 bool hal_aci_tl_event_peek(hal_aci_data_t *p_aci_data);
139 
140 /** @brief Enable debug printing of all ACI commands sent and ACI events received
141  *  @details
142  *  when the enable parameter is true. The debug printing is enabled on the Serial.
143  *  When the enable parameter is false. The debug printing is disabled on the Serial.
144  *  By default the debug printing is disabled.
145  */
146 void hal_aci_tl_debug_print(bool enable);
147 
148 
149 /** @brief Pin reset the nRF8001
150  *  @details
151  *  The reset line of the nF8001 needs to kept low for 200 ns.
152  *  Redbearlab shield v1.1 and v2012.07 are exceptions as they
153  *  have a Power ON Reset circuit that works differently.
154  *  The function handles the exceptions based on the board_name in aci_pins_t
155  */
156 void hal_aci_tl_pin_reset(void);
157 
158 /** @brief Return full status of transmit queue
159  *  @details
160  *
161  */
162  bool hal_aci_tl_rx_q_full(void);
163 
164  /** @brief Return empty status of receive queue
165  *  @details
166  *
167  */
168  bool hal_aci_tl_rx_q_empty(void);
169 
170 /** @brief Return full status of receive queue
171  *  @details
172  *
173  */
174  bool hal_aci_tl_tx_q_full(void);
175 
176  /** @brief Return empty status of transmit queue
177  *  @details
178  *
179  */
180  bool hal_aci_tl_tx_q_empty(void);
181 
182 /** @brief Flush the ACI command Queue and the ACI Event Queue
183  *  @details
184  *  Call this function in the main thread
185  */
186 void hal_aci_tl_q_flush(void);
187 
188 #endif // HAL_ACI_TL_H__
189 /** @} */
190