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_RETVAL uint8_t
61 
62 #define BLE9_OK 0
63 #define BLE9_ERROR 1
64 
70 #define BLE9_RSP_READY 1
71 #define BLE9_RSP_NOT_READY 0
72 
80 #define BLE9_CMD_SYSTEM_HELLO_ID 0x00010020
81 #define BLE9_CMD_SYSTEM_DATA_BUFFER_CLEAR_ID 0x14010020
82 #define BLE9_CMD_SYSTEM_RESET_ID 0x01010020
83 #define BLE9_CMD_SYSTEM_HALT_ID 0x2001010C
84 #define BLE9_CMD_SYSTEM_SET_TX_POWER_ID 0x17010020
85 #define BLE9_CMD_SYSTEM_GET_VERSION_ID 0x1B010020
86 #define BLE9_CMD_SYSTEM_SET_SOFT_TIMER_ID 0x19010020
87 #define BLE9_CMD_SYSTEM_SET_LAZY_SOFT_TIMER_ID 0x1A010020
88 #define BLE9_CMD_SYSTEM_SET_IDENTITY_ADDRESS_ID 0x13010020
89 #define BLE9_CMD_SYSTEM_GET_IDENTITY_ADDRESS_ID 0x15010020
90 #define BLE9_CMD_SYSTEM_DATA_BUFFER_WRITE_ID 0x12010020
91 
93 #define BLE9_CMD_GAP_SET_PRIVACY_MODE_ID 0x01020020
94 #define BLE9_CMD_GAP_ENABLE_WHITELISTING_ID 0x03020020
95 
97 #define BLE9_CMD_ADVERTISER_CREATE_ID 0x01040020
98 #define BLE9_CMD_ADVERTISER_DELETE_SET_ID 0x02040020
99 #define BLE9_CMD_ADVERTISER_START_ID 0x09040320
100 #define BLE9_CMD_ADVERTISER_STOP_ID 0x0A040020
101 #define BLE9_CMD_ADVERTISER_SET_TIMING_ID 0x03040020
102 #define BLE9_CMD_ADVERTISER_SET_PHY_ID 0x06040020
103 #define BLE9_CMD_ADVERTISER_SET_CHANNEL_MAP_ID 0x04040020
104 #define BLE9_CMD_ADVERTISER_SET_TX_POWER_ID 0x0B040020
105 #define BLE9_CMD_ADVERTISER_SET_REPORT_SCAN_REQUEST_ID 0x05040020
106 #define BLE9_CMD_ADVERTISER_SET_CONFIGURATION_ID 0x07040020
107 #define BLE9_CMD_ADVERTISER_CLEAR_CONFIGURATION_ID 0x08040020
108 #define BLE9_CMD_ADVERTISER_SET_DATA_ID 0x0F040020
109 #define BLE9_CMD_ADVERTISER_SET_LONG_DATA_ID 0x0E040020
110 #define BLE9_CMD_ADVERTISER_START_PERIODIC_ADVERTISING_ID 0x0C040020
111 #define BLE9_CMD_ADVERTISER_STOP_PERIODIC_ADVERTISING_ID 0x0D040020
112 
114 #define BLE9_CMD_NULL 0
115 #define BLE9_SYSTEM_RESUME 0
116 #define BLE9_SYSTEM_HALT 1
117 
122 #define DRV_RX_BUFFER_SIZE 100
123 #define DRV_TX_BUFFER_SIZE 100
124  // End group macro
127 // --------------------------------------------------------------- PUBLIC TYPES
131 typedef enum
132 {
140 
143 typedef enum
144 {
153 
154 typedef enum
155 {
157  BLE9_PHY_TYPE_1M = 1,
165  BLE9_PHY_TYPE_ANY = 0xFF
167 
168 typedef enum
169 {
177 
178 typedef enum
179 {
197 
198 typedef enum
199 {
215 
220 typedef struct
221 {
223  uint16_t version_major;
225  uint16_t version_minor;
227  uint16_t version_patch;
229  uint16_t version_build;
233  uint32_t version_hash;
235 
236 typedef struct
237 {
251  uint32_t ble9_timer_time;
254 } ble9_timer_t;
255 
259 typedef struct
260 {
263  // Modules
264  uart_t uart;
265 
266  char uart_rx_buffer[ DRV_RX_BUFFER_SIZE ];
267  char uart_tx_buffer[ DRV_TX_BUFFER_SIZE ];
268 } ble9_t;
269 
273 typedef struct
274 {
275  // Communication gpio pins
276  pin_name_t rx_pin;
277  pin_name_t tx_pin;
278 
279  // Static variables
280  uint32_t baud_rate; // Clock speed.
281  bool uart_blocking; // Wait for data or not.
282  uart_data_bits_t data_bit; // Data bits.
283  uart_parity_t parity_bit; // Parity bit.
284  uart_stop_bits_t stop_bit; // Stop bits.
285 } ble9_cfg_t;
286  // End types group
288 // ----------------------------------------------- PUBLIC FUNCTION DECLARATIONS
289 
304 
315 
325 
346 
368 void ble9_system_set_identity_address( ble9_t *ctx, uint8_t *address, uint8_t type );
369 
382 BLE9_RETVAL ble9_system_get_identity_address( ble9_t *ctx, uint8_t *data_buf, uint8_t type );
383 
393 
414 BLE9_RETVAL ble9_system_halt( ble9_t *ctx, uint8_t halt );
415 
439 void ble9_system_set_tx_power( ble9_t *ctx, int16_t min_power, int16_t max_power);
440 
451 BLE9_RETVAL ble9_system_data_buffer_write( ble9_t *ctx, size_t data_len, const uint8_t *wr_data );
452 
461 
476 
488 
510 BLE9_RETVAL ble9_gap_set_privacy_mode( ble9_t *ctx, bool privacy, uint8_t interval_in_minutes );
511 
523 
533 
542 
570 BLE9_RETVAL ble9_advertiser_set_timing( ble9_t *ctx, uint16_t interval_min,
571  uint16_t interval_max, uint16_t duration,
572  uint8_t maxevents );
573 
589 
604 
617 BLE9_RETVAL ble9_advertiser_set_tx_power( ble9_t *ctx, int16_t power, int16_t *set_power );
618 
630 
647 BLE9_RETVAL ble9_advertiser_set_configuration( ble9_t *ctx, uint8_t configurations );
648 
661 
695  size_t adv_data_len, const uint8_t *adv_data );
696 
724 
743 
754 
784  uint16_t interval_max, uint8_t flags );
785 
797 
804 void ble9_generic_write ( ble9_t *ctx, char *data_buf );
805 
815 int32_t ble9_generic_read ( ble9_t *ctx, char *data_buf, uint16_t max_len );
816 
826 void ble9_send_command ( ble9_t *ctx, char *command, uint8_t buf_length );
827 
828 #ifdef __cplusplus
829 }
830 #endif
831 #endif // _BLE9_H_
832  // End public_function group
835 
836 // ------------------------------------------------------------------------- END
ble9_t::uart
uart_t uart
Definition: ble9.h:264
DRV_RX_BUFFER_SIZE
#define DRV_RX_BUFFER_SIZE
Definition: ble9.h:122
ble9_cfg_t::data_bit
uart_data_bits_t data_bit
Definition: ble9.h:282
BLE9_DFU_RESET_MODE_OTA
@ BLE9_DFU_RESET_MODE_OTA
Definition: ble9.h:138
ble9_timer_t
Definition: ble9.h:237
ble9_advertiser_set_data
BLE9_RETVAL ble9_advertiser_set_data(ble9_t *ctx, ble9_package_type_t packet_type, size_t adv_data_len, const uint8_t *adv_data)
Set user-defined data in advertising packets, scan response packets, or periodic advertising packets....
ble9_system_get_identity_address
BLE9_RETVAL ble9_system_get_identity_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_system_halt
BLE9_RETVAL ble9_system_halt(ble9_t *ctx, uint8_t halt)
Force radio to idle state and allow device to sleep. Advertising, scanning, connections,...
ble9_advertiser_set_long_data
BLE9_RETVAL ble9_advertiser_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_CHANNEL_ALL
@ BLE9_CHANNEL_ALL
Definition: ble9.h:151
ble9_cfg_t::stop_bit
uart_stop_bits_t stop_bit
Definition: ble9.h:284
ble9_advertiser_start_periodic_advertising
BLE9_RETVAL ble9_advertiser_start_periodic_advertising(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_dfu_reset_mode_t
ble9_dfu_reset_mode_t
Definition: ble9.h:132
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:191
ble9_advertiser_mode_discoverable_t
ble9_advertiser_mode_discoverable_t
Definition: ble9.h:179
ble9_version_t::version_major
uint16_t version_major
Major release version.
Definition: ble9.h:223
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:187
ble9_advertiser_set_timing
BLE9_RETVAL ble9_advertiser_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_system_set_lazy_soft_timer
BLE9_RETVAL ble9_system_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_CHANNEL_37_39
@ BLE9_CHANNEL_37_39
Definition: ble9.h:149
ble9_advertiser_delete_id
BLE9_RETVAL ble9_advertiser_delete_id(ble9_t *ctx)
Delete an advertising ID.
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:283
ble9_timer_t::ble9_timer_slack
uint32_t ble9_timer_slack
Definition: ble9.h:253
ble9_advertiser_set_channel_map
BLE9_RETVAL ble9_advertiser_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_system_set_tx_power
void ble9_system_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...
ble9_advertiser_set_phy
BLE9_RETVAL ble9_advertiser_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_version_t::version_bootloader
uint32_t version_bootloader
Version hash.
Definition: ble9.h:231
ble9_init
BLE9_RETVAL ble9_init(ble9_t *ctx, ble9_cfg_t *cfg)
Initialization function.
ble9_advertiser_start
BLE9_RETVAL ble9_advertiser_start(ble9_t *ctx, ble9_advertiser_mode_discoverable_t discover, ble9_advertiser_mode_connectable_t connect)
Start advertising of a given advertising set with specified discoverable and connectable modes....
ble9_system_get_version
BLE9_RETVAL ble9_system_get_version(ble9_t *ctx)
Get the firmware version information.
ble9_advertiser_mode_connectable_t
ble9_advertiser_mode_connectable_t
Definition: ble9.h:199
ble9_version_t::version_build
uint16_t version_build
Bootloader version.
Definition: ble9.h:229
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:204
ble9_timer_t::ble9_timer_time
uint32_t ble9_timer_time
Slack time in hardware clock ticks.
Definition: ble9.h:251
BLE9_PHY_TYPE_2M
@ BLE9_PHY_TYPE_2M
(0x4) Coded PHY, 125k (S=8) or 500k (S=2).
Definition: ble9.h:159
BLE9_RETVAL
#define BLE9_RETVAL
Definition: ble9.h:60
BLE9_PHY_TYPE_CODED
@ BLE9_PHY_TYPE_CODED
(0xFF) Any PHYs the device supports.
Definition: ble9.h:162
BLE9_PACKAGE_TYPE_PERIODIC_ADVERTISING
@ BLE9_PACKAGE_TYPE_PERIODIC_ADVERTISING
Definition: ble9.h:175
BLE9_CHANNEL_37
@ BLE9_CHANNEL_37
Definition: ble9.h:145
BLE9_CHANNEL_38
@ BLE9_CHANNEL_38
Definition: ble9.h:146
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:274
ble9_system_hello
BLE9_RETVAL ble9_system_hello(ble9_t *ctx)
Verify whether the communication between the host and the device is functional.
BLE9_ADVERTISER_MODE_CONNECTABLE_NONE_SCANABLE
@ BLE9_ADVERTISER_MODE_CONNECTABLE_NONE_SCANABLE
Definition: ble9.h:213
ble9_system_data_buffer_write
BLE9_RETVAL ble9_system_data_buffer_write(ble9_t *ctx, size_t data_len, const uint8_t *wr_data)
Write data into the system data buffer. Data will be appended to the end of existing data.
ble9_t
Click ctx object definition.
Definition: ble9.h:260
ble9_advertiser_create_id
BLE9_RETVAL ble9_advertiser_create_id(ble9_t *ctx)
Create an advertising ID. The handle of the created advertising ID is returned in response.
BLE9_ADVERTISER_MODE_CONNECTABLE_NONE
@ BLE9_ADVERTISER_MODE_CONNECTABLE_NONE
Non-connectable non-scannable.
Definition: ble9.h:201
ble9_advertiser_set_configuration
BLE9_RETVAL ble9_advertiser_set_configuration(ble9_t *ctx, uint8_t configurations)
Enable advertising configuration flags on the given advertising set. The configuration change will ta...
ble9_version_t::version_patch
uint16_t version_patch
Build number.
Definition: ble9.h:227
BLE9_PHY_TYPE_ANY
@ BLE9_PHY_TYPE_ANY
Definition: ble9.h:165
BLE9_CHANNEL_39
@ BLE9_CHANNEL_39
Definition: ble9.h:148
ble9_cfg_t::baud_rate
uint32_t baud_rate
Definition: ble9.h:280
ble9_package_type_t
ble9_package_type_t
Definition: ble9.h:169
BLE9_CHANNEL_37_38
@ BLE9_CHANNEL_37_38
Definition: ble9.h:147
ble9_advertiser_set_report_scan_request
BLE9_RETVAL ble9_advertiser_set_report_scan_request(ble9_t *ctx, bool report_scan_req)
Enable or disable the scan request notification of a given advertising set. This setting will take ef...
ble9_gap_set_privacy_mode
BLE9_RETVAL ble9_gap_set_privacy_mode(ble9_t *ctx, bool 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_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:244
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:210
BLE9_PACKAGE_TYPE_ADVERTISING
@ BLE9_PACKAGE_TYPE_ADVERTISING
Advertising packets.
Definition: ble9.h:171
ble9_generic_write
void ble9_generic_write(ble9_t *ctx, char *data_buf)
Generic write function.
ble9_t::ble9_advertiser_handle
uint8_t ble9_advertiser_handle
Definition: ble9.h:261
BLE9_CHANNEL_38_39
@ BLE9_CHANNEL_38_39
Definition: ble9.h:150
BLE9_ADVERTISER_MODE_DISCOVERABLE_NONE
@ BLE9_ADVERTISER_MODE_DISCOVERABLE_NONE
Not discoverable.
Definition: ble9.h:181
ble9_cfg_t::tx_pin
pin_name_t tx_pin
Definition: ble9.h:277
ble9_advertiser_clear_configuration
BLE9_RETVAL ble9_advertiser_clear_configuration(ble9_t *ctx, uint8_t configurations)
Disable advertising configuration flags on the given advertising set. The configuration change will t...
ble9_phy_type_t
ble9_phy_type_t
Definition: ble9.h:155
ble9_version_t::version_hash
uint32_t version_hash
Definition: ble9.h:233
ble9_timer_t::ble9_timer_handle
uint8_t ble9_timer_handle
Timer handle to use, which is returned in timeout event.
Definition: ble9.h:239
BLE9_ADVERTISER_MODE_DISCOVERABLE_USER_DATA
@ BLE9_ADVERTISER_MODE_DISCOVERABLE_USER_DATA
Definition: ble9.h:195
ble9_advertiser_stop
BLE9_RETVAL ble9_advertiser_stop(ble9_t *ctx)
Stop the advertising of the given advertising set. Counterpart with ble9_advertiser_start....
ble9_cfg_t::rx_pin
pin_name_t rx_pin
Definition: ble9.h:276
DRV_TX_BUFFER_SIZE
#define DRV_TX_BUFFER_SIZE
Definition: ble9.h:123
ble9_version_t
Definition: ble9.h:221
ble9_send_command
void ble9_send_command(ble9_t *ctx, char *command, uint8_t buf_length)
Function for transmiting commands.
ble9_system_set_soft_timer
BLE9_RETVAL ble9_system_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_generic_read
int32_t ble9_generic_read(ble9_t *ctx, char *data_buf, uint16_t max_len)
Generic read function.
ble9_t::ble9_version
ble9_version_t * ble9_version
Definition: ble9.h:262
BLE9_ADVERTISER_MODE_CONNECTABLE_SCANNABLE
@ BLE9_ADVERTISER_MODE_CONNECTABLE_SCANNABLE
Undirected scannable (Non-connectable but responds to scan requests)
Definition: ble9.h:207
ble9_cfg_t::uart_blocking
bool uart_blocking
Definition: ble9.h:281
ble9_gap_enable_whitelisting
BLE9_RETVAL ble9_gap_enable_whitelisting(ble9_t *ctx, bool enable)
Enable or disable whitelisting. The setting will be effective the next time that scanning is enabled.
ble9_channel_t
ble9_channel_t
Definition: ble9.h:144
ble9_system_reset
void ble9_system_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_DFU_RESET_MODE_UART
@ BLE9_DFU_RESET_MODE_UART
Boot to OTA DFU mode.
Definition: ble9.h:136
ble9_version_t::version_minor
uint16_t version_minor
Patch release version.
Definition: ble9.h:225
BLE9_ADVERTISER_MODE_DISCOVERABLE_LIMITED
@ BLE9_ADVERTISER_MODE_DISCOVERABLE_LIMITED
Discoverable using general discovery procedure.
Definition: ble9.h:184
BLE9_DFU_RESET_MODE_NORMAL
@ BLE9_DFU_RESET_MODE_NORMAL
Boot to normal mode.
Definition: ble9.h:134
BLE9_PACKAGE_TYPE_SCAN_RESPONSE
@ BLE9_PACKAGE_TYPE_SCAN_RESPONSE
Periodic advertising packets.
Definition: ble9.h:173
ble9_advertiser_stop_periodic_advertising
BLE9_RETVAL ble9_advertiser_stop_periodic_advertising(ble9_t *ctx)
Stop the periodic advertising on the given advertising set. Counterpart with ble9_advertiser_start_pe...
ble9_system_set_identity_address
void ble9_system_set_identity_address(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_advertiser_set_tx_power
BLE9_RETVAL ble9_advertiser_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_system_data_buffer_clear
BLE9_RETVAL ble9_system_data_buffer_clear(ble9_t *ctx)
Remove all data from the system data buffer.