ble9  2.0.0.0
ble9.h
Go to the documentation of this file.
1 /*
2  * MikroSDK - MikroE Software Development Kit
3  * Copyright© 2020 MikroElektronika d.o.o.
4  *
5  * Permission is hereby granted, free of charge, to any person
6  * obtaining a copy of this software and associated documentation
7  * files (the "Software"), to deal in the Software without restriction,
8  * including without limitation the rights to use, copy, modify, merge,
9  * publish, distribute, sublicense, and/or sell copies of the Software,
10  * and to permit persons to whom the Software is furnished to do so,
11  * subject to the following conditions:
12  *
13  * The above copyright notice and this permission notice shall be
14  * included in all copies or substantial portions of the Software.
15  *
16  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
17  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
19  * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
20  * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
21  * ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE
22  * OR OTHER DEALINGS IN THE SOFTWARE.
23  */
24 
32 #ifndef _BLE9_H_
33 #define _BLE9_H_
34 
35 #ifdef __cplusplus
36 extern "C"{
37 #endif
38 
39 #include "drv_uart.h"
40 
41 // -------------------------------------------------------------- PUBLIC MACROS
51 #define BLE9_MAP_MIKROBUS( cfg, mikrobus ) \
52  cfg.tx_pin = MIKROBUS( mikrobus, MIKROBUS_TX ); \
53  cfg.rx_pin = MIKROBUS( mikrobus, MIKROBUS_RX );
54 
60 #define BLE9_OK 0
61 #define BLE9_ERROR -1
62 
68 #define BLE9_RSP_READY 1
69 #define BLE9_RSP_NOT_READY 0
70 
78 #define BLE9_CMD_SYSTEM_HELLO_ID 0x00010020ul
79 #define BLE9_CMD_SYSTEM_DATA_BUFFER_CLEAR_ID 0x14010020ul
80 #define BLE9_CMD_SYSTEM_RESET_ID 0x01010020ul
81 #define BLE9_CMD_SYSTEM_HALT_ID 0x2001010Cul
82 #define BLE9_CMD_SYSTEM_SET_TX_POWER_ID 0x17010020ul
83 #define BLE9_CMD_SYSTEM_GET_VERSION_ID 0x1B010020ul
84 #define BLE9_CMD_SYSTEM_SET_SOFT_TIMER_ID 0x19010020ul
85 #define BLE9_CMD_SYSTEM_SET_LAZY_SOFT_TIMER_ID 0x1A010020ul
86 #define BLE9_CMD_SYSTEM_SET_IDENTITY_ADDRESS_ID 0x13010020ul
87 #define BLE9_CMD_SYSTEM_GET_IDENTITY_ADDRESS_ID 0x15010020ul
88 #define BLE9_CMD_SYSTEM_DATA_BUFFER_WRITE_ID 0x12010020ul
89 
91 #define BLE9_CMD_GAP_SET_PRIVACY_MODE_ID 0x01020020ul
92 #define BLE9_CMD_GAP_ENABLE_WHITELISTING_ID 0x03020020ul
93 
95 #define BLE9_CMD_ADVERTISER_CREATE_ID 0x01040020ul
96 #define BLE9_CMD_ADVERTISER_DELETE_SET_ID 0x02040020ul
97 #define BLE9_CMD_ADVERTISER_START_ID 0x09040320ul
98 #define BLE9_CMD_ADVERTISER_STOP_ID 0x0A040020ul
99 #define BLE9_CMD_ADVERTISER_SET_TIMING_ID 0x03040020ul
100 #define BLE9_CMD_ADVERTISER_SET_PHY_ID 0x06040020ul
101 #define BLE9_CMD_ADVERTISER_SET_CHANNEL_MAP_ID 0x04040020ul
102 #define BLE9_CMD_ADVERTISER_SET_TX_POWER_ID 0x0B040020ul
103 #define BLE9_CMD_ADVERTISER_SET_REPORT_SCAN_REQUEST_ID 0x05040020ul
104 #define BLE9_CMD_ADVERTISER_SET_CONFIGURATION_ID 0x07040020ul
105 #define BLE9_CMD_ADVERTISER_CLEAR_CONFIGURATION_ID 0x08040020ul
106 #define BLE9_CMD_ADVERTISER_SET_DATA_ID 0x0F040020ul
107 #define BLE9_CMD_ADVERTISER_SET_LONG_DATA_ID 0x0E040020ul
108 #define BLE9_CMD_ADVERTISER_START_PERIODIC_ADVERTISING_ID 0x0C040020ul
109 #define BLE9_CMD_ADVERTISER_STOP_PERIODIC_ADVERTISING_ID 0x0D040020ul
110 
112 #define BLE9_CMD_NULL 0
113 #define BLE9_SYSTEM_RESUME 0
114 #define BLE9_SYSTEM_HALT 1
115 
120 #define DRV_RX_BUFFER_SIZE 100
121 #define DRV_TX_BUFFER_SIZE 100
122  // End group macro
125 // --------------------------------------------------------------- PUBLIC TYPES
129 typedef enum
130 {
137 
139 
142 typedef enum
143 {
151 
153 
154 typedef enum
155 {
157  BLE9_PHY_TYPE_1M = 1,
165  BLE9_PHY_TYPE_ANY = 0xFF
166 
168 
169 typedef enum
170 {
177 
179 
180 typedef enum
181 {
198 
200 
201 typedef enum
202 {
217 
219 
224 typedef struct
225 {
227  uint16_t version_major;
229  uint16_t version_minor;
231  uint16_t version_patch;
233  uint16_t version_build;
237  uint32_t version_hash;
238 
240 
241 typedef struct
242 {
256  uint32_t ble9_timer_time;
259 
260 } ble9_timer_t;
261 
265 typedef struct
266 {
269  // Modules
270  uart_t uart;
271 
272  uint8_t uart_rx_buffer[ DRV_RX_BUFFER_SIZE ];
273  uint8_t uart_tx_buffer[ DRV_TX_BUFFER_SIZE ];
274 
275 } ble9_t;
276 
280 typedef struct
281 {
282  // Communication gpio pins
283  pin_name_t rx_pin;
284  pin_name_t tx_pin;
285 
286  // Static variables
287  uint32_t baud_rate; // Clock speed.
288  bool uart_blocking; // Wait for data or not.
289  uart_data_bits_t data_bit; // Data bits.
290  uart_parity_t parity_bit; // Parity bit.
291  uart_stop_bits_t stop_bit; // Stop bits.
292 
293 } ble9_cfg_t;
294  // End types group
296 // ----------------------------------------------- PUBLIC FUNCTION DECLARATIONS
297 
312 
322 err_t ble9_init ( ble9_t *ctx, ble9_cfg_t *cfg );
323 
332 err_t ble9_sys_hello ( ble9_t *ctx );
333 
354 
376 void ble9_sys_set_id_addr ( ble9_t *ctx, uint8_t *address, uint8_t type );
377 
390 err_t ble9_sys_get_id_address ( ble9_t *ctx, uint8_t *data_buf, uint8_t type );
391 
400 void ble9_sys_reset ( ble9_t *ctx, ble9_dfu_reset_mode_t reset_mode );
401 
422 err_t ble9_sys_halt ( ble9_t *ctx, uint8_t halt );
423 
447 void ble9_sys_set_tx_power ( ble9_t *ctx, int16_t min_power, int16_t max_power );
448 
459 err_t ble9_sys_data_buf_write ( ble9_t *ctx, uint16_t data_len, uint8_t *wr_data );
460 
469 
483 err_t ble9_sys_set_soft_timer ( ble9_t *ctx, ble9_timer_t *ble9_timer );
484 
496 
518 err_t ble9_gap_set_privacy_mode ( ble9_t *ctx, uint8_t privacy, uint8_t interval_in_minutes );
519 
530 err_t ble9_gap_en_wlist ( ble9_t *ctx, uint8_t enable );
531 
540 err_t ble9_adv_create_id ( ble9_t *ctx );
541 
549 err_t ble9_adv_delete_id ( ble9_t *ctx );
550 
578 err_t ble9_adv_set_timing ( ble9_t *ctx, uint16_t interval_min, uint16_t interval_max,
579  uint16_t duration, uint8_t maxevents );
580 
595 err_t ble9_adv_set_phy ( ble9_t *ctx, ble9_phy_type_t primary_phy, ble9_phy_type_t secondary_phy );
596 
610 err_t ble9_adv_set_channel_map ( ble9_t *ctx, ble9_channel_t channel_map );
611 
624 err_t ble9_adv_set_tx_power ( ble9_t *ctx, int16_t power, int16_t *set_power );
625 
636 err_t ble9_adv_set_report_scan_req ( ble9_t *ctx, uint8_t report_scan_req );
637 
654 err_t ble9_adv_set_configuration ( ble9_t *ctx, uint8_t configurations );
655 
667 err_t ble9_adv_clear_configuration ( ble9_t *ctx, uint8_t configurations );
668 
701 err_t ble9_adv_set_data ( ble9_t *ctx, ble9_package_type_t packet_type,
702  uint16_t adv_data_len, uint8_t *adv_data );
703 
731 
749  ble9_adv_mode_connectable_t connect );
750 
760 err_t ble9_adv_stop ( ble9_t *ctx );
761 
790 err_t ble9_adv_start_per_adv ( ble9_t *ctx, uint16_t interval_min, uint16_t interval_max, uint8_t flags );
791 
803 
811 void ble9_generic_write ( ble9_t *ctx, uint8_t *data_buf, uint16_t len );
812 
822 int32_t ble9_generic_read ( ble9_t *ctx, uint8_t *data_buf, uint16_t max_len );
823 
832 void ble9_send_command ( ble9_t *ctx, uint32_t command );
833 
834 #ifdef __cplusplus
835 }
836 #endif
837 #endif // _BLE9_H_
838  // End public_function group
841 
842 // ------------------------------------------------------------------------- END
ble9_t::uart
uart_t uart
Definition: ble9.h:270
DRV_RX_BUFFER_SIZE
#define DRV_RX_BUFFER_SIZE
Definition: ble9.h:120
ble9_sys_halt
err_t ble9_sys_halt(ble9_t *ctx, uint8_t halt)
Force radio to idle state and allow device to sleep. Advertising, scanning, connections,...
ble9_cfg_t::data_bit
uart_data_bits_t data_bit
Definition: ble9.h:289
BLE9_DFU_RESET_MODE_OTA
@ BLE9_DFU_RESET_MODE_OTA
Definition: ble9.h:136
ble9_timer_t
Definition: ble9.h:242
BLE9_ADVERTISER_MODE_CONNECTABLE_NONE
@ BLE9_ADVERTISER_MODE_CONNECTABLE_NONE
Non-connectable non-scannable.
Definition: ble9.h:204
ble9_sys_set_id_addr
void ble9_sys_set_id_addr(ble9_t *ctx, uint8_t *address, uint8_t type)
Set the device's Bluetooth identity address. The address can be a public device address or a static d...
BLE9_CHANNEL_ALL
@ BLE9_CHANNEL_ALL
Definition: ble9.h:150
BLE9_ADVERTISER_MODE_DISCOVERABLE_GENERAL
@ BLE9_ADVERTISER_MODE_DISCOVERABLE_GENERAL
Device is not discoverable in either limited or generic discovery procedure but may be discovered usi...
Definition: ble9.h:189
ble9_cfg_t::stop_bit
uart_stop_bits_t stop_bit
Definition: ble9.h:291
ble9_sys_hello
err_t ble9_sys_hello(ble9_t *ctx)
Verify whether the communication between the host and the device is functional.
ble9_adv_set_phy
err_t ble9_adv_set_phy(ble9_t *ctx, ble9_phy_type_t primary_phy, ble9_phy_type_t secondary_phy)
Set advertising PHYs of the given advertising set. This setting will take effect next time that adver...
BLE9_ADVERTISER_MODE_DISCOVERABLE_USER_DATA
@ BLE9_ADVERTISER_MODE_DISCOVERABLE_USER_DATA
Definition: ble9.h:197
ble9_generic_write
void ble9_generic_write(ble9_t *ctx, uint8_t *data_buf, uint16_t len)
Generic write function.
ble9_sys_get_id_address
err_t ble9_sys_get_id_address(ble9_t *ctx, uint8_t *data_buf, uint8_t type)
Read the Bluetooth identity address used by the device, which can be a public or random static device...
ble9_dfu_reset_mode_t
ble9_dfu_reset_mode_t
Definition: ble9.h:130
ble9_sys_reset
void ble9_sys_reset(ble9_t *ctx, ble9_dfu_reset_mode_t reset_mode)
Reset the system. The command does not have a response but it triggers one of the boot events (normal...
BLE9_ADVERTISER_MODE_CONNECTABLE_SCANNABLE
@ BLE9_ADVERTISER_MODE_CONNECTABLE_SCANNABLE
Undirected scannable (Non-connectable but responds to scan requests)
Definition: ble9.h:210
BLE9_ADVERTISER_MODE_DISCOVERABLE_LIMITED
@ BLE9_ADVERTISER_MODE_DISCOVERABLE_LIMITED
Discoverable using general discovery procedure.
Definition: ble9.h:186
ble9_version_t::version_major
uint16_t version_major
Major release version.
Definition: ble9.h:227
ble9_send_command
void ble9_send_command(ble9_t *ctx, uint32_t command)
Function for transmiting commands.
ble9_gap_set_privacy_mode
err_t ble9_gap_set_privacy_mode(ble9_t *ctx, uint8_t privacy, uint8_t interval_in_minutes)
Enable or disable the privacy feature on all GAP roles. New privacy mode will take effect for adverti...
BLE9_CHANNEL_37_39
@ BLE9_CHANNEL_37_39
Definition: ble9.h:148
ble9_adv_start_per_adv
err_t ble9_adv_start_per_adv(ble9_t *ctx, uint16_t interval_min, uint16_t interval_max, uint8_t flags)
Start periodic advertising on the given advertising set. The stack enables the advertising set automa...
ble9_cfg_setup
void ble9_cfg_setup(ble9_cfg_t *cfg)
Config Object Initialization function.
ble9_cfg_t::parity_bit
uart_parity_t parity_bit
Definition: ble9.h:290
ble9_timer_t::ble9_timer_slack
uint32_t ble9_timer_slack
Definition: ble9.h:258
ble9_version_t::version_bootloader
uint32_t version_bootloader
Version hash.
Definition: ble9.h:235
ble9_generic_read
int32_t ble9_generic_read(ble9_t *ctx, uint8_t *data_buf, uint16_t max_len)
Generic read function.
ble9_version_t::version_build
uint16_t version_build
Bootloader version.
Definition: ble9.h:233
ble9_timer_t::ble9_timer_time
uint32_t ble9_timer_time
Slack time in hardware clock ticks.
Definition: ble9.h:256
BLE9_PHY_TYPE_2M
@ BLE9_PHY_TYPE_2M
(0x4) Coded PHY, 125k (S=8) or 500k (S=2).
Definition: ble9.h:159
BLE9_PHY_TYPE_CODED
@ BLE9_PHY_TYPE_CODED
(0xFF) Any PHYs the device supports.
Definition: ble9.h:162
BLE9_ADVERTISER_MODE_CONNECTABLE_DIRECTED
@ BLE9_ADVERTISER_MODE_CONNECTABLE_DIRECTED
Undirected connectable scannable. This mode can only be used in legacy advertising PDUs.
Definition: ble9.h:207
BLE9_PACKAGE_TYPE_PERIODIC_ADVERTISING
@ BLE9_PACKAGE_TYPE_PERIODIC_ADVERTISING
Definition: ble9.h:176
BLE9_CHANNEL_37
@ BLE9_CHANNEL_37
Definition: ble9.h:144
BLE9_CHANNEL_38
@ BLE9_CHANNEL_38
Definition: ble9.h:145
BLE9_PHY_TYPE_1M
@ BLE9_PHY_TYPE_1M
(0x1) 1M PHY.
Definition: ble9.h:157
ble9_cfg_t
Click configuration structure definition.
Definition: ble9.h:281
ble9_adv_set_tx_power
err_t ble9_adv_set_tx_power(ble9_t *ctx, int16_t power, int16_t *set_power)
Limit the maximum advertising TX power on the given advertising set. The maximum TX power of legacy a...
ble9_t
Click ctx object definition.
Definition: ble9.h:266
ble9_version_t::version_patch
uint16_t version_patch
Build number.
Definition: ble9.h:231
BLE9_PHY_TYPE_ANY
@ BLE9_PHY_TYPE_ANY
Definition: ble9.h:165
BLE9_CHANNEL_39
@ BLE9_CHANNEL_39
Definition: ble9.h:147
ble9_cfg_t::baud_rate
uint32_t baud_rate
Definition: ble9.h:287
ble9_t::ble9_adv_handle
uint8_t ble9_adv_handle
Definition: ble9.h:267
ble9_package_type_t
ble9_package_type_t
Definition: ble9.h:170
BLE9_CHANNEL_37_38
@ BLE9_CHANNEL_37_38
Definition: ble9.h:146
ble9_adv_stop_per_adv
err_t ble9_adv_stop_per_adv(ble9_t *ctx)
Stop the periodic advertising on the given advertising set. Counterpart with ble9_adv_start_per_adv....
ble9_adv_set_report_scan_req
err_t ble9_adv_set_report_scan_req(ble9_t *ctx, uint8_t report_scan_req)
Enable or disable the scan request notification of a given advertising set. This setting will take ef...
ble9_adv_set_channel_map
err_t ble9_adv_set_channel_map(ble9_t *ctx, ble9_channel_t channel_map)
Set the primary advertising channel map of the given advertising set. This setting will take effect n...
ble9_sys_set_lazy_soft_timer
err_t ble9_sys_set_lazy_soft_timer(ble9_t *ctx, ble9_timer_t *ble9_timer)
Start a software timer with slack. The slack parameter allows the stack to optimize wakeups and save ...
ble9_timer_t::ble9_timer_single_shot
uint8_t ble9_timer_single_shot
Frequency interval of events, which indicates how often to send events in hardware clock ticks (1 sec...
Definition: ble9.h:249
ble9_adv_create_id
err_t ble9_adv_create_id(ble9_t *ctx)
Create an advertising ID. The handle of the created advertising ID is returned in response.
ble9_adv_set_data
err_t ble9_adv_set_data(ble9_t *ctx, ble9_package_type_t packet_type, uint16_t adv_data_len, uint8_t *adv_data)
Set user-defined data in advertising packets, scan response packets, or periodic advertising packets....
ble9_adv_set_configuration
err_t ble9_adv_set_configuration(ble9_t *ctx, uint8_t configurations)
Enable advertising configuration flags on the given advertising set. The configuration change will ta...
BLE9_PACKAGE_TYPE_ADVERTISING
@ BLE9_PACKAGE_TYPE_ADVERTISING
Advertising packets.
Definition: ble9.h:172
ble9_sys_data_buf_clear
err_t ble9_sys_data_buf_clear(ble9_t *ctx)
Remove all data from the system data buffer.
BLE9_ADVERTISER_MODE_CONNECTABLE_NONE_SCANABLE
@ BLE9_ADVERTISER_MODE_CONNECTABLE_NONE_SCANABLE
Definition: ble9.h:216
ble9_adv_start
err_t ble9_adv_start(ble9_t *ctx, ble9_adv_mode_discoverable_t discover, ble9_adv_mode_connectable_t connect)
Start advertising of a given advertising set with specified discoverable and connectable modes....
BLE9_CHANNEL_38_39
@ BLE9_CHANNEL_38_39
Definition: ble9.h:149
ble9_cfg_t::tx_pin
pin_name_t tx_pin
Definition: ble9.h:284
ble9_phy_type_t
ble9_phy_type_t
Definition: ble9.h:155
ble9_adv_mode_discoverable_t
ble9_adv_mode_discoverable_t
Definition: ble9.h:181
ble9_version_t::version_hash
uint32_t version_hash
Definition: ble9.h:237
ble9_gap_en_wlist
err_t ble9_gap_en_wlist(ble9_t *ctx, uint8_t enable)
Enable or disable whitelisting. The setting will be effective the next time that scanning is enabled.
ble9_timer_t::ble9_timer_handle
uint8_t ble9_timer_handle
Timer handle to use, which is returned in timeout event.
Definition: ble9.h:244
ble9_cfg_t::rx_pin
pin_name_t rx_pin
Definition: ble9.h:283
ble9_init
err_t ble9_init(ble9_t *ctx, ble9_cfg_t *cfg)
Initialization function.
ble9_sys_set_tx_power
void ble9_sys_set_tx_power(ble9_t *ctx, int16_t min_power, int16_t max_power)
Set the global minimum and maximum radiated TX power levels for Bluetooth. This returns selected powe...
DRV_TX_BUFFER_SIZE
#define DRV_TX_BUFFER_SIZE
Definition: ble9.h:121
ble9_version_t
Definition: ble9.h:225
ble9_sys_set_soft_timer
err_t ble9_sys_set_soft_timer(ble9_t *ctx, ble9_timer_t *ble9_timer)
Start a software timer. Multiple concurrent timers can be running simultaneously. 256 unique timer ha...
ble9_t::ble9_version
ble9_version_t * ble9_version
Definition: ble9.h:268
ble9_adv_set_timing
err_t ble9_adv_set_timing(ble9_t *ctx, uint16_t interval_min, uint16_t interval_max, uint16_t duration, uint8_t maxevents)
Set the advertising timing parameters of the given advertising set. This setting will take effect nex...
ble9_cfg_t::uart_blocking
bool uart_blocking
Definition: ble9.h:288
ble9_adv_clear_configuration
err_t ble9_adv_clear_configuration(ble9_t *ctx, uint8_t configurations)
Disable advertising configuration flags on the given advertising set. The configuration change will t...
ble9_adv_mode_connectable_t
ble9_adv_mode_connectable_t
Definition: ble9.h:202
ble9_sys_get_version
err_t ble9_sys_get_version(ble9_t *ctx)
Get the firmware version information.
ble9_channel_t
ble9_channel_t
Definition: ble9.h:143
BLE9_DFU_RESET_MODE_UART
@ BLE9_DFU_RESET_MODE_UART
Boot to OTA DFU mode.
Definition: ble9.h:134
ble9_version_t::version_minor
uint16_t version_minor
Patch release version.
Definition: ble9.h:229
ble9_adv_set_long_data
err_t ble9_adv_set_long_data(ble9_t *ctx, ble9_package_type_t packet_type)
Set advertising data for a specified packet type and advertising set. Data currently in the system da...
BLE9_ADVERTISER_MODE_DISCOVERABLE_BROADCAST
@ BLE9_ADVERTISER_MODE_DISCOVERABLE_BROADCAST
Send advertising and/or scan response data defined by the user. The limited/general discoverable flag...
Definition: ble9.h:193
ble9_adv_stop
err_t ble9_adv_stop(ble9_t *ctx)
Stop the advertising of the given advertising set. Counterpart with ble9_adv_start....
BLE9_DFU_RESET_MODE_NORMAL
@ BLE9_DFU_RESET_MODE_NORMAL
Boot to normal mode.
Definition: ble9.h:132
BLE9_PACKAGE_TYPE_SCAN_RESPONSE
@ BLE9_PACKAGE_TYPE_SCAN_RESPONSE
Periodic advertising packets.
Definition: ble9.h:174
BLE9_ADVERTISER_MODE_CONNECTABLE_NONE_CONNECTABLE
@ BLE9_ADVERTISER_MODE_CONNECTABLE_NONE_CONNECTABLE
Undirected connectable non-scannable. This mode can only be used in extended advertising PDUs.
Definition: ble9.h:213
ble9_sys_data_buf_write
err_t ble9_sys_data_buf_write(ble9_t *ctx, uint16_t data_len, uint8_t *wr_data)
Write data into the system data buffer. Data will be appended to the end of existing data.
BLE9_ADVERTISER_MODE_DISCOVERABLE_NONE
@ BLE9_ADVERTISER_MODE_DISCOVERABLE_NONE
Not discoverable.
Definition: ble9.h:183
ble9_adv_delete_id
err_t ble9_adv_delete_id(ble9_t *ctx)
Delete an advertising ID.