| STM32L - BlueNRG-1 BLE stack APIs, Events and Constants

- Main Page
- Modules
- Classes
- Files

- File List
- File Members

Functions
bluenrg1_hal_aci.h File Reference

Header file for BlueNRG-1 Bluetooth Low Energy stack APIs. More...

`#include "bluenrg1_types.h"`

Go to the source code of this file.

## Functions

tBleStatus | aci_hal_write_config_data (uint8_t Offset, uint8_t Length, uint8_t Value[])
| This command writes a value to a low level configure data structure. It is useful to setup directly some low level parameters for the system in the runtime. More...
tBleStatus | aci_hal_read_config_data (uint8_t Offset, uint8_t *Data_Length, uint8_t Data[])
| This command requests the value in the low level configure data structure. The number of read bytes changes for different Offset. More...
tBleStatus | aci_hal_set_tx_power_level (uint8_t En_High_Power, uint8_t PA_Level)
| This command sets the TX power level of the device. By controlling the EN_HIGH_POWER and the PA_LEVEL, the combination of the 2 determines the output power level (dBm). When the system starts up or reboots, the default TX power level will be used, which is the maximum value of 8 dBm. Once this command is given, the output power will be changed instantly, regardless if there is Bluetooth communication going on or not. For example, for debugging purpose, the device can be set to advertise all the time. And use this command to observe the signal strength changing. The system will keep the last received TX power level from the command, i.e. the 2nd command overwrites the previous TX power level. The new TX power level remains until another Set TX Power command, or the system reboots. More...
tBleStatus | aci_hal_device_standby (void)
| Put the device in standby mode. Normally the BlueNRG will automatically enter sleep mode to save power. This command puts the device into the Standby mode instead of the sleep mode. The difference is that, in sleep mode, the device can still wake up itself with the internal timer. But in standby mode, this timer is disabled. So the only possibility to wake up the device is by external signals, e.g. a HCI command sent via SPI bus. Based on the measurement, the current consumption under sleep mode is ~2 uA. And this value is ~1.5 uA in standby mode. The command is only accepted when there is no other Bluetooth activity. Otherwise an error code ERR_COMMAND_DISALLOWED will be returned. More...
tBleStatus | aci_hal_le_tx_test_packet_number (uint32_t *Number_Of_Packets)
| This command returns the number of packets sent in Direct Test Mode. When the Direct TX test is started, a 32-bit counter is used to count how many packets have been transmitted. This command can be used to check how many packets have been sent during the Direct TX test. The counter starts from 0 and counts upwards. The counter can wrap and start from 0 again. The counter is not cleared until the next Direct TX test starts. More...
tBleStatus | aci_hal_tone_start (uint8_t RF_Channel)
| This command starts a carrier frequency, i.e. a tone, on a specific channel. The frequency sine wave at the specific channel may be used for debugging purpose only. The channel ID is a parameter from 0x00 to 0x27 for the 40 BLE channels, e.g. 0x00 for 2.402 GHz, 0x01 for 2.404 GHz etc. This command should not be used when normal Bluetooth activities are ongoing. The tone should be stopped by aci_hal_tone_stop command. More...
tBleStatus | aci_hal_tone_stop (void)
| This command is used to stop the previously started aci_hal_tone_start command. More...
tBleStatus | aci_hal_updater_start (void)
| This command is only implemented together with the normal application. The updater does not support this command. If this command is called, the system reboots and enters updater mode. More...
tBleStatus | aci_hal_updater_reboot (void)
| This command reboots the system. This command does not set the BLUE flag, which must be done by another command. More...
tBleStatus | aci_hal_get_updater_version (uint8_t *Version)
| This command returns the version of the Updater. More...
tBleStatus | aci_hal_get_updater_bufsize (uint8_t *Buffer_Size)
| Return the maximum buffer size. This value limits the size of the data blocks that could be used on the command aci_hal_updater_prog_data_blk. More...
tBleStatus | aci_hal_updater_erase_blue_flag (void)
| This command erases the BLUE flag in the Flash. After this operation, the updater cannot jump to the firmware until the BLUE flag is set to a valid value with ACI_HAL_UPDATER_RESET_BLUE_FLAG. This command is strongly recommended when the updater wants to upgrade the firmware application. More...
tBleStatus | aci_hal_updater_reset_blue_flag (void)
| Reset the BLUE flag to its proper value. This command must be called when the firmware upgrade is finished. So that after reboot, the update may jump to the firmware application. More...
tBleStatus | aci_hal_updater_erase_sector (uint32_t Address)
| This command erases one sector of the Flash memory. One sector is 2 KB. After erasing, the sector will be all 0xFF. More...
tBleStatus | aci_hal_updater_prog_data_blk (uint32_t Address, uint16_t Data_Length, uint8_t Data[])
| This command writes a block of data to the Flash, starting from the given base address. More...
tBleStatus | aci_hal_updater_read_data_blk (uint32_t Address, uint16_t Data_Length, uint8_t Data[])
| This command reads a block of data from the Flash, starting from the given base address. For it is only allowed to read from the IFR flash. So the Base Address must be bigger than 0x10020000. More...
tBleStatus | aci_hal_updater_calc_crc (uint32_t Address, uint8_t Num_Of_Sectors, uint32_t *crc)
| It calculates the CRC32 of one or more Flash sectors. One Flash sector is 2 KB. More...
tBleStatus | aci_hal_updater_hw_version (uint8_t *HW_Version)
| TBD. More...
tBleStatus | aci_hal_set_radio_activity_mask (uint16_t Radio_Activity_Mask)
| This command set the bitmask associated to aci_hal_end_of_radio_activity_event. Only the radio acitivities enabled in the mask will be reported to application by aci_hal_end_of_radio_activity_event. More...
tBleStatus | aci_hal_get_link_status (uint8_t Link_Status[8], uint16_t Link_Connection_Handle[16/2])
| This command returns the status of the 8 Bluetooth low energy links managed by the device. More...
tBleStatus | aci_hal_get_fw_build_number (uint16_t *Build_Number)
| This command returns the build number associated with the firmware version currently running. More...
tBleStatus | aci_hal_get_anchor_period (uint32_t *Anchor_Period, uint32_t *Max_Free_Slot)
| This command returns information about the Anchor Period to help application in selecting slot timings when operating in multi-link scenarios. More...

## Detailed Description

Header file for BlueNRG-1 Bluetooth Low Energy stack APIs.

Author
  AMS - VMA RF Application team

Version
  V1.0.0

Date
  21-Sept-2015

Attention

THE PRESENT FIRMWARE WHICH IS FOR GUIDANCE ONLY AIMS AT PROVIDING CUSTOMERS WITH CODING INFORMATION REGARDING THEIR PRODUCTS IN ORDER FOR THEM TO SAVE TIME. AS A RESULT, STMICROELECTRONICS SHALL NOT BE HELD LIABLE FOR ANY DIRECT, INDIRECT OR CONSEQUENTIAL DAMAGES WITH RESPECT TO ANY CLAIMS ARISING FROM THE CONTENT OF SUCH FIRMWARE AND/OR THE USE MADE BY CUSTOMERS OF THE CODING INFORMATION CONTAINED HEREIN IN CONNECTION WITH THEIR PRODUCTS.

##
© COPYRIGHT 2015 STMicroelectronics

Definition in file bluenrg1_hal_aci.h.

## Function Documentation

tBleStatus aci_hal_device_standby | ( | void |  | ) |

Put the device in standby mode. Normally the BlueNRG will automatically enter sleep mode to save power. This command puts the device into the Standby mode instead of the sleep mode. The difference is that, in sleep mode, the device can still wake up itself with the internal timer. But in standby mode, this timer is disabled. So the only possibility to wake up the device is by external signals, e.g. a HCI command sent via SPI bus. Based on the measurement, the current consumption under sleep mode is ~2 uA. And this value is ~1.5 uA in standby mode. The command is only accepted when there is no other Bluetooth activity. Otherwise an error code ERR_COMMAND_DISALLOWED will be returned.

Return values

  Value | indicating success or error code.

tBleStatus aci_hal_get_anchor_period | ( | uint32_t * | Anchor_Period,
|  | uint32_t * | Max_Free_Slot
| ) |  |

This command returns information about the Anchor Period to help application in selecting slot timings when operating in multi-link scenarios.

Parameters

  [out] | Anchor_Period | Current anchor period. T = N * 0.625 ms.
  [out] | Max_Free_Slot | Maximum available time that can be allocated for a new slot. T = N * 0.625 ms.

Return values

  Value | indicating success or error code.

tBleStatus aci_hal_get_fw_build_number | ( | uint16_t * | Build_Number | ) |

This command returns the build number associated with the firmware version currently running.

Parameters

  [out] | Build_Number | Build number of the firmware.

Return values

  Value | indicating success or error code.

tBleStatus aci_hal_get_link_status | ( | uint8_t | Link_Status[8],
|  | uint16_t | Link_Connection_Handle[16/2]
| ) |  |

This command returns the status of the 8 Bluetooth low energy links managed by the device.

Parameters

  [out] | Link_Status | Array of link status (8 links). Each link status is 1 byte. 0x00:Idle, 0x01:Advertising, 0x02:Connected in slave role, 0x03:Scanning, 0x04:Reserved, 0x05:Connected in master role, 0x06:TX test mode, 0x07:RX test mode
  [out] | Link_Connection_Handle | Array of connection handles (2 bytes) for 8 links.

Return values

  Value | indicating success or error code.

tBleStatus aci_hal_get_updater_bufsize | ( | uint8_t * | Buffer_Size | ) |

Return the maximum buffer size. This value limits the size of the data blocks that could be used on the command aci_hal_updater_prog_data_blk.

Parameters

  [out] | Buffer_Size | Not available

Return values

  Value | indicating success or error code.

tBleStatus aci_hal_get_updater_version | ( | uint8_t * | Version | ) |

This command returns the version of the Updater.

Parameters

  [out] | Version | Not available

Return values

  Value | indicating success or error code.

tBleStatus aci_hal_le_tx_test_packet_number | ( | uint32_t * | Number_Of_Packets | ) |

This command returns the number of packets sent in Direct Test Mode. When the Direct TX test is started, a 32-bit counter is used to count how many packets have been transmitted. This command can be used to check how many packets have been sent during the Direct TX test. The counter starts from 0 and counts upwards. The counter can wrap and start from 0 again. The counter is not cleared until the next Direct TX test starts.

Parameters

  [out] | Number_Of_Packets | Number of packets sent during the last Direct TX test.

Return values

  Value | indicating success or error code.

tBleStatus aci_hal_read_config_data | ( | uint8_t | Offset,
|  | uint8_t * | Data_Length,
|  | uint8_t | Data[]
| ) |  |

This command requests the value in the low level configure data structure. The number of read bytes changes for different Offset.

Parameters

  Offset | Offset of the element in the configuration data structure which has to be read. The valid offsets are:

0x00: Bluetooth public address, Value length returned: 6 bytes 0x06: DIV used to derive CSRK, Value length returned: 2 bytes 0x08: Encryption root key used to derive LTK and CSRK, Value length returned: 16 bytes 0x18: Identity root key used to derive LTK and CSRK, Value length returned: 16 bytes 0x2C: Link layer without host (for certification purposes), Value length returned: 1 byte

0x2F: Disable watchdog (1=disabled, 0=enablee). Value length returned: 1 byte 0x80: Static random address. Value length returned: 6 bytes (read-only)

Parameters

  [out] | Data_Length | Length of Data in octets
  [out] | Data | Data field associated with Offset parameter

Return values

  Value | indicating success or error code.

tBleStatus aci_hal_set_radio_activity_mask | ( | uint16_t | Radio_Activity_Mask | ) |

This command set the bitmask associated to aci_hal_end_of_radio_activity_event. Only the radio acitivities enabled in the mask will be reported to application by aci_hal_end_of_radio_activity_event.

Parameters

  Radio_Activity_Mask | Bitmask of radio events

Return values

  Value | indicating success or error code.

tBleStatus aci_hal_set_tx_power_level | ( | uint8_t | En_High_Power,
|  | uint8_t | PA_Level
| ) |  |

This command sets the TX power level of the device. By controlling the EN_HIGH_POWER and the PA_LEVEL, the combination of the 2 determines the output power level (dBm). When the system starts up or reboots, the default TX power level will be used, which is the maximum value of 8 dBm. Once this command is given, the output power will be changed instantly, regardless if there is Bluetooth communication going on or not. For example, for debugging purpose, the device can be set to advertise all the time. And use this command to observe the signal strength changing. The system will keep the last received TX power level from the command, i.e. the 2nd command overwrites the previous TX power level. The new TX power level remains until another Set TX Power command, or the system reboots.

Parameters

  En_High_Power | Enable High Power mode
  PA_Level | PA Level. If En_High_Power=0 0 = -18 dBm, 1 = -15 dBm, 2 = -12 dBm, 3 = -9 dBm, 4 = -6 dBm, 5 = -2 dBm, 6 = 0 dBm, 7 = 5 dBm. If En_High_Power=1 0 = -14 dBm, 1 = -11 dBm, 2 = -8 dBm, 3 = -5 dBm, 4 = -2 dBm, 5 = 2 dBm, 6 = 4 dBm, 7 = 8 dBm

Return values

  Value | indicating success or error code.

tBleStatus aci_hal_tone_start | ( | uint8_t | RF_Channel | ) |

This command starts a carrier frequency, i.e. a tone, on a specific channel. The frequency sine wave at the specific channel may be used for debugging purpose only. The channel ID is a parameter from 0x00 to 0x27 for the 40 BLE channels, e.g. 0x00 for 2.402 GHz, 0x01 for 2.404 GHz etc. This command should not be used when normal Bluetooth activities are ongoing. The tone should be stopped by aci_hal_tone_stop command.

Parameters

  RF_Channel | BLE Channel ID, from 0x00 to 0x27 meaning (2.402 + 2*0xXX) GHz Device will continuously emit 0s, that means that the tone will be at the channel center frequency less the maximum frequency deviation (250kHz).

Return values

  Value | indicating success or error code.

tBleStatus aci_hal_tone_stop | ( | void |  | ) |

This command is used to stop the previously started aci_hal_tone_start command.

Return values

  Value | indicating success or error code.

tBleStatus aci_hal_updater_calc_crc | ( | uint32_t | Address,
|  | uint8_t | Num_Of_Sectors,
|  | uint32_t * | crc
| ) |  |

It calculates the CRC32 of one or more Flash sectors. One Flash sector is 2 KB.

Parameters

  | Address | Not available
  | Num_Of_Sectors | Not available
  [out] | crc | Not available

Return values

  Value | indicating success or error code.

tBleStatus aci_hal_updater_erase_blue_flag | ( | void |  | ) |

This command erases the BLUE flag in the Flash. After this operation, the updater cannot jump to the firmware until the BLUE flag is set to a valid value with ACI_HAL_UPDATER_RESET_BLUE_FLAG. This command is strongly recommended when the updater wants to upgrade the firmware application.

Return values

  Value | indicating success or error code.

tBleStatus aci_hal_updater_erase_sector | ( | uint32_t | Address | ) |

This command erases one sector of the Flash memory. One sector is 2 KB. After erasing, the sector will be all 0xFF.

Parameters

  Address | Not available

Return values

  Value | indicating success or error code.

tBleStatus aci_hal_updater_hw_version | ( | uint8_t * | HW_Version | ) |

TBD.

Parameters

  [out] | HW_Version | Not available

Return values

  Value | indicating success or error code.

tBleStatus aci_hal_updater_prog_data_blk | ( | uint32_t | Address,
|  | uint16_t | Data_Length,
|  | uint8_t | Data[]
| ) |  |

This command writes a block of data to the Flash, starting from the given base address.

Parameters

  Address | Not available
  Data_Length | Length of Data in octets
  Data | Not available

Return values

  Value | indicating success or error code.

tBleStatus aci_hal_updater_read_data_blk | ( | uint32_t | Address,
|  | uint16_t | Data_Length,
|  | uint8_t | Data[]
| ) |  |

This command reads a block of data from the Flash, starting from the given base address. For it is only allowed to read from the IFR flash. So the Base Address must be bigger than 0x10020000.

Parameters

  | Address | Not available
  | Data_Length | Not available
  [out] | Data | Not available

Return values

  Value | indicating success or error code.

tBleStatus aci_hal_updater_reboot | ( | void |  | ) |

This command reboots the system. This command does not set the BLUE flag, which must be done by another command.

Return values

  Value | indicating success or error code.

tBleStatus aci_hal_updater_reset_blue_flag | ( | void |  | ) |

Reset the BLUE flag to its proper value. This command must be called when the firmware upgrade is finished. So that after reboot, the update may jump to the firmware application.

Return values

  Value | indicating success or error code.

tBleStatus aci_hal_updater_start | ( | void |  | ) |

This command is only implemented together with the normal application. The updater does not support this command. If this command is called, the system reboots and enters updater mode.

Return values

  Value | indicating success or error code.

tBleStatus aci_hal_write_config_data | ( | uint8_t | Offset,
|  | uint8_t | Length,
|  | uint8_t | Value[]
| ) |  |

This command writes a value to a low level configure data structure. It is useful to setup directly some low level parameters for the system in the runtime.

Parameters

  Offset | Offset of the element in the configuration data structure which has to be written. The valid offsets are:

- 0x00: Bluetooth public address, Value length to be writtten: 6 bytes
- 0x06: DIV used to derive CSRK, Value length to be written: 2 bytes
- 0x08: Encryption root key used to derive LTK and CSRK, Value length to be written: 16 bytes
- 0x18: Identity root key used to derive LTK and CSRK, Value length to be written: 16 bytes
- 0x2C: Link layer without host (for certification purposes), Value length to be written: 1 byte
- 0x2F: Disable watchdog (1=disable, 0=enable). Value length to be written: 1 byte
  Parameters

    Length | Length of data to be written
    Value | Data to be written

  Return values

    Value | indicating success or error code.