Cordio Stack and Cordio Profiles  r2p3-02rel0
app_ui.h
Go to the documentation of this file.
1 /*************************************************************************************************/
2 /*!
3  * \file
4  *
5  * \brief Application framework user interface.
6  *
7  * Copyright (c) 2011-2018 Arm Ltd. All Rights Reserved.
8  * ARM Ltd. confidential and proprietary.
9  *
10  * IMPORTANT. Your use of this file is governed by a Software License Agreement
11  * ("Agreement") that must be accepted in order to download or otherwise receive a
12  * copy of this file. You may not use or copy this file for any purpose other than
13  * as described in the Agreement. If you do not agree to all of the terms of the
14  * Agreement do not use this file and delete all copies in your possession or control;
15  * if you do not have a copy of the Agreement, you must contact ARM Ltd. prior
16  * to any use, copying or further distribution of this software.
17  */
18 /*************************************************************************************************/
19 #ifndef APP_UI_H
20 #define APP_UI_H
21 
22 #ifdef __cplusplus
23 extern "C" {
24 #endif
25 
26 /*! \addtogroup APP_FRAMEWORK_UI_API
27  * \{ */
28 
29 /**************************************************************************************************
30  Macros
31 **************************************************************************************************/
32 
33 /*! \brief UI event enumeration */
34 enum
35 {
36  APP_UI_NONE, /*!< \brief No event */
37  APP_UI_RESET_CMPL, /*!< \brief Reset complete */
38  APP_UI_DISCOVERABLE, /*!< \brief Enter discoverable mode */
39  APP_UI_ADV_START, /*!< \brief Advertising started */
40  APP_UI_ADV_STOP, /*!< \brief Advertising stopped */
41  APP_UI_SCAN_START, /*!< \brief Scanning started */
42  APP_UI_SCAN_STOP, /*!< \brief Scanning stopped */
43  APP_UI_SCAN_REPORT, /*!< \brief Scan data received from peer device */
44  APP_UI_CONN_OPEN, /*!< \brief Connection opened */
45  APP_UI_CONN_CLOSE, /*!< \brief Connection closed */
46  APP_UI_SEC_PAIR_CMPL, /*!< \brief Pairing completed successfully */
47  APP_UI_SEC_PAIR_FAIL, /*!< \brief Pairing failed or other security failure */
48  APP_UI_SEC_ENCRYPT, /*!< \brief Connection encrypted */
49  APP_UI_SEC_ENCRYPT_FAIL, /*!< \brief Encryption failed */
50  APP_UI_PASSKEY_PROMPT, /*!< \brief Prompt user to enter passkey */
51  APP_UI_ALERT_CANCEL, /*!< \brief Cancel a low or high alert */
52  APP_UI_ALERT_LOW, /*!< \brief Low alert */
53  APP_UI_ALERT_HIGH, /*!< \brief High alert */
54  APP_UI_ADV_SET_START_IND, /*!< \brief Advertising set(s) started */
55  APP_UI_ADV_SET_STOP_IND, /*!< \brief Advertising set(s) stopped */
56  APP_UI_SCAN_REQ_RCVD_IND, /*!< \brief Scan request received */
57  APP_UI_EXT_SCAN_START_IND, /*!< \brief Extended scanning started */
58  APP_UI_EXT_SCAN_STOP_IND, /*!< \brief Extended scanning stopped */
59  APP_UI_PER_ADV_SET_START_IND, /*!< \brief Periodic advertising set started */
60  APP_UI_PER_ADV_SET_STOP_IND, /*!< \brief Periodic advertising set stopped */
61  APP_UI_PER_ADV_SYNC_EST_IND, /*!< \brief Periodic advertising sync established */
62  APP_UI_PER_ADV_SYNC_LOST_IND, /*!< \brief Periodic advertising sync lost */
63  APP_UI_HW_ERROR /*!< \brief Hardware error */
64 };
65 
66 /*! \brief Button press enumeration */
67 enum
68 {
69  APP_UI_BTN_NONE, /*!< \brief No button press */
70  APP_UI_BTN_1_DOWN, /*!< \brief Button 1 on down press */
71  APP_UI_BTN_1_SHORT, /*!< \brief Button 1 short press */
72  APP_UI_BTN_1_MED, /*!< \brief Button 1 medium press */
73  APP_UI_BTN_1_LONG, /*!< \brief Button 1 long press */
74  APP_UI_BTN_1_EX_LONG, /*!< \brief Button 1 extra long press */
75  APP_UI_BTN_2_DOWN, /*!< \brief Button 2 on down press */
76  APP_UI_BTN_2_SHORT, /*!< \brief Button 2 short press */
77  APP_UI_BTN_2_MED, /*!< \brief Button 2 medium press */
78  APP_UI_BTN_2_LONG, /*!< \brief Button 2 long press */
79  APP_UI_BTN_2_EX_LONG /*!< \brief Button 2 extra long press */
80 };
81 
82 /*! \brief LED values */
83 #define APP_UI_LED_NONE 0x00 /*!< \brief No LED */
84 #define APP_UI_LED_1 0x01 /*!< \brief LED 1 */
85 #define APP_UI_LED_2 0x02 /*!< \brief LED 2 */
86 #define APP_UI_LED_3 0x04 /*!< \brief LED 3 */
87 #define APP_UI_LED_4 0x08 /*!< \brief LED 4 */
88 #define APP_UI_LED_WRAP 0xFF /*!< \brief Wrap to beginning of sequence */
89 
90 /*! \brief Sound tone value for wrap/repeat */
91 #define APP_UI_SOUND_WRAP 0xFFFF
92 
93 /**************************************************************************************************
94  Data Types
95 **************************************************************************************************/
96 
97 /*! \brief Button press callback */
98 typedef void (*appUiBtnCback_t)(uint8_t btn);
99 
100 /*! \brief Action event callback */
101 typedef void (*appUiActionCback_t)(uint8_t event);
102 
103 /*! \brief Button Poll callback */
104 typedef void (*appUiBtnPollCback_t)(void);
105 
106 /*! \brief Sound data structure */
107 typedef struct
108 {
109  uint16_t tone; /*!< \brief Sound tone in Hz. Use 0 for silence. */
110  uint16_t duration; /*!< \brief Sound duration in milliseconds */
111 } appUiSound_t;
112 
113 /*! \brief LED data structure */
114 typedef struct
115 {
116  uint8_t led; /*!< \brief LED to control */
117  uint8_t state; /*!< \brief On or off */
118  uint16_t duration; /*!< \brief duration in milliseconds */
119 } appUiLed_t;
120 
121 /*! \brief Callback structure */
122 typedef struct
123 {
124  appUiBtnCback_t btnCback; /*!< \brief Called when button pressed */
125  appUiActionCback_t actionCback; /*!< \brief Called when action event received */
126  appUiBtnPollCback_t btnPollCback; /*!< \brief Called to poll button hardware */
127 } appUiCback_t;
128 
129 /**************************************************************************************************
130  Function Declarations
131 **************************************************************************************************/
132 
133 /** \name APP User Interface
134  * Commands that may be sent via terminal to the application.
135  */
136 /**@{*/
137 
138 /*************************************************************************************************/
139 /*!
140  * \brief Perform a user interface action based on the event value passed to the function.
141  *
142  * \param event User interface event value.
143  *
144  * \return None.
145  */
146 /*************************************************************************************************/
147 void AppUiAction(uint8_t event);
148 
149 /*************************************************************************************************/
150 /*!
151  * \brief Display a passkey.
152  *
153  * \param passkey Passkey to display.
154  *
155  * \return None.
156  */
157 /*************************************************************************************************/
158 void AppUiDisplayPasskey(uint32_t passkey);
159 
160 /*************************************************************************************************/
161 /*!
162 * \brief Display a confirmation value.
163 *
164 * \param confirm Confirm value to display.
165 *
166 * \return None.
167 */
168 /*************************************************************************************************/
169 void AppUiDisplayConfirmValue(uint32_t confirm);
170 
171 /*************************************************************************************************/
172 /*!
173  * \brief Display an RSSI value.
174  *
175  * \param rssi Rssi value to display.
176  *
177  * \return None.
178  */
179 /*************************************************************************************************/
180 void AppUiDisplayRssi(int8_t rssi);
181 
182 /*************************************************************************************************/
183 /*!
184  * \brief Register a callback function to receive button presses.
185  *
186  * \param btnCback Callback function.
187  *
188  * \return None.
189  *
190  * \note Registered by application to receive button events
191  */
192 /*************************************************************************************************/
193 void AppUiBtnRegister(appUiBtnCback_t btnCback);
194 
195 /*************************************************************************************************/
196 /*!
197  * \brief Register a callback function to receive action events.
198  *
199  * \param actionCback Callback function.
200  *
201  * \return None.
202  *
203  * \note Registered by platform
204  */
205 /*************************************************************************************************/
206 void AppUiActionRegister(appUiActionCback_t actionCback);
207 
208 /*************************************************************************************************/
209 /*!
210  * \brief Register a callback function to receive APP_BTN_POLL_IND events.
211  *
212  * \param btnPollCback Callback function.
213  *
214  * \return None.
215  *
216  * \note Registered by platform
217  */
218 /*************************************************************************************************/
219 void AppUiBtnPollRegister(appUiBtnPollCback_t btnPollCback);
220 
221 /*************************************************************************************************/
222 /*!
223  * \brief Handle a hardware button press. This function is called to handle WSF
224  * event APP_BTN_DOWN_EVT.
225  *
226  * \return None.
227  */
228 /*************************************************************************************************/
229 void AppUiBtnPressed(void);
230 
231 /*************************************************************************************************/
232 /*!
233  * \brief Play a sound.
234  *
235  * \param pSound Pointer to sound tone/duration array.
236  *
237  * \return None.
238  */
239 /*************************************************************************************************/
240 void AppUiSoundPlay(const appUiSound_t *pSound);
241 
242 /*************************************************************************************************/
243 /*!
244  * \brief Stop the sound that is currently playing.
245  *
246  * \return None.
247  */
248 /*************************************************************************************************/
249 void AppUiSoundStop(void);
250 
251 /*************************************************************************************************/
252 /*!
253  * \brief Start LED blinking.
254  *
255  * \param pLed Pointer to LED data structure.
256  *
257  * \return None.
258  */
259 /*************************************************************************************************/
260 void AppUiLedStart(const appUiLed_t *pLed);
261 
262 /*************************************************************************************************/
263 /*!
264  * \brief Stop LED blinking.
265  *
266  * \return None.
267  */
268 /*************************************************************************************************/
269 void AppUiLedStop(void);
270 
271 /*************************************************************************************************/
272 /*!
273  * \brief Button test function-- for test purposes only.
274  *
275  * \param btn button press
276  * \return None.
277  */
278 /*************************************************************************************************/
279 void AppUiBtnTest(uint8_t btn);
280 
281 /**@}*/
282 
283 /*! \} */ /*! APP_FRAMEWORK_UI_API */
284 
285 #ifdef __cplusplus
286 };
287 #endif
288 
289 #endif /* APP_UI_H */
void AppUiBtnTest(uint8_t btn)
Button test function– for test purposes only.
Periodic advertising set stopped.
Definition: app_ui.h:60
void(* appUiBtnPollCback_t)(void)
Button Poll callback.
Definition: app_ui.h:104
Advertising set(s) stopped.
Definition: app_ui.h:55
No button press.
Definition: app_ui.h:69
uint8_t state
On or off.
Definition: app_ui.h:117
Low alert.
Definition: app_ui.h:52
void AppUiBtnPollRegister(appUiBtnPollCback_t btnPollCback)
Register a callback function to receive APP_BTN_POLL_IND events.
void(* appUiBtnCback_t)(uint8_t btn)
Button press callback.
Definition: app_ui.h:98
appUiActionCback_t actionCback
Called when action event received.
Definition: app_ui.h:125
Periodic advertising set started.
Definition: app_ui.h:59
void AppUiBtnPressed(void)
Handle a hardware button press. This function is called to handle WSF event APP_BTN_DOWN_EVT.
Button 1 extra long press.
Definition: app_ui.h:74
Hardware error.
Definition: app_ui.h:63
Advertising stopped.
Definition: app_ui.h:40
Button 1 on down press.
Definition: app_ui.h:70
void AppUiBtnRegister(appUiBtnCback_t btnCback)
Register a callback function to receive button presses.
Button 2 medium press.
Definition: app_ui.h:77
appUiBtnCback_t btnCback
Called when button pressed.
Definition: app_ui.h:124
Button 2 short press.
Definition: app_ui.h:76
Pairing completed successfully.
Definition: app_ui.h:46
High alert.
Definition: app_ui.h:53
Periodic advertising sync established.
Definition: app_ui.h:61
void AppUiDisplayRssi(int8_t rssi)
Display an RSSI value.
Periodic advertising sync lost.
Definition: app_ui.h:62
void AppUiDisplayPasskey(uint32_t passkey)
Display a passkey.
Button 1 short press.
Definition: app_ui.h:71
void AppUiLedStop(void)
Stop LED blinking.
Button 1 long press.
Definition: app_ui.h:73
Extended scanning stopped.
Definition: app_ui.h:58
Advertising set(s) started.
Definition: app_ui.h:54
Prompt user to enter passkey.
Definition: app_ui.h:50
Connection encrypted.
Definition: app_ui.h:48
appUiBtnPollCback_t btnPollCback
Called to poll button hardware.
Definition: app_ui.h:126
void AppUiActionRegister(appUiActionCback_t actionCback)
Register a callback function to receive action events.
unsigned long uint32_t
Unsigned 32-bit value.
Definition: wsf_types.h:71
Scanning started.
Definition: app_ui.h:41
No event.
Definition: app_ui.h:36
Scan data received from peer device.
Definition: app_ui.h:43
void AppUiDisplayConfirmValue(uint32_t confirm)
Display a confirmation value.
Extended scanning started.
Definition: app_ui.h:57
uint16_t duration
Sound duration in milliseconds.
Definition: app_ui.h:110
Encryption failed.
Definition: app_ui.h:49
uint16_t duration
duration in milliseconds
Definition: app_ui.h:118
Sound data structure.
Definition: app_ui.h:107
Connection opened.
Definition: app_ui.h:44
Button 1 medium press.
Definition: app_ui.h:72
Button 2 extra long press.
Definition: app_ui.h:79
void AppUiLedStart(const appUiLed_t *pLed)
Start LED blinking.
Scan request received.
Definition: app_ui.h:56
Advertising started.
Definition: app_ui.h:39
unsigned short uint16_t
Unsigned 16-bit value.
Definition: wsf_types.h:67
Enter discoverable mode.
Definition: app_ui.h:38
uint16_t tone
Sound tone in Hz. Use 0 for silence.
Definition: app_ui.h:109
Reset complete.
Definition: app_ui.h:37
Button 2 on down press.
Definition: app_ui.h:75
Scanning stopped.
Definition: app_ui.h:42
uint8_t led
LED to control.
Definition: app_ui.h:116
LED data structure.
Definition: app_ui.h:114
void AppUiSoundStop(void)
Stop the sound that is currently playing.
void AppUiSoundPlay(const appUiSound_t *pSound)
Play a sound.
Cancel a low or high alert.
Definition: app_ui.h:51
Button 2 long press.
Definition: app_ui.h:78
void(* appUiActionCback_t)(uint8_t event)
Action event callback.
Definition: app_ui.h:101
Pairing failed or other security failure.
Definition: app_ui.h:47
Callback structure.
Definition: app_ui.h:122
unsigned char uint8_t
Unsigned 8-bit value.
Definition: wsf_types.h:63
Connection closed.
Definition: app_ui.h:45
signed char int8_t
Signed 8-bit value.
Definition: wsf_types.h:61
void AppUiAction(uint8_t event)
Perform a user interface action based on the event value passed to the function.