Xpress Connect And User Functions Demo
Starting with firmware version
1.2.2045.0, BGX is capable of an advertising
mode called Xpress Advertising. In Xpress Advertising, the peripheral BGX
advertises in Limited Discoverable mode. The central can distinguish this
peripheral BGX device from other BGX devices in its vicinity by scanning for
BGXs that are in a Limited Discoverable Mode only. This allows for a quick,
easy, and reliable method to connect to a BGX. The central can then be commanded
to connect and disconnect to the advertising BGX. When Xpress connect
functionality is combined with ufu command execution, the BGX can advertise,
connect, and communicate autonomously, without any intervention from an embedded
host controller. The example that follows combines Xpress Connect functionality
with ufu control, and does not require an embedded host for operation.
This demo connects two BGXs via Xpress Connect and allows messages to be sent in both directions. When first plugged in or reset, the two BGXs will be idle. This means there is no advertising and no LEDs blinking. Short-pressing BTN0 will enable Xpress Advertising on that BGX for 5 seconds. The connection status LED will blink to indicate the BGX is Xpress Advertising. During these 5 seconds, the other BGX can long-press BTN0 to establish a connection. Note, a long-press is a press over 2 seconds. Both LEDs will stay on once connected. At this point, both BGXs can send the messages "Hello" and "Hi" to each other by short-pressing BTN1. "Hello" and "Hi" will alternate because both commands are programmed to BTN1 as a short-press. The ufu state machine will cycle through commands that are triggered the same way. The messages can be seen through serial terminals on a PC. Long-pressing BTN1 will disconnect the 2 BGXs and return them back to an idle state.
The demo requires a Wireless Xpress BGX13P Starter Kit.
Wireless Xpress BGX13P Starter Kit
This Wireless Xpress Starter Kit includes the Bluetooth Xpress BGX13P module and serves as a starting point to build applications for BGX. The BGX demo makes use of the starter kit's expansion header allowing for communication between the two starter kits. More guidance on this starter kit can be found in the User Guide, the BGX13P Data Sheet, and the BGX Development App Note.
To set up the demo, connect both BGXs to serial terminal on a PC and send the commands below to manually set up each BGX. The commands can be split into 5 categories:
- Connection Status LED
- User Functions
- Button Debouncing
- Power Management
- Save Configuration
Connection Status LED
An LED displaying the connection status is important to visualize the state of the BGX. Here an LED will be programmed to be full off when not connected, full on when connected, and a 1.25 Hz blink rate when advertising.
First, set GPIO0 (LED0) to a connection status LED. (Uses gfu)
> gfu 0 con_status_led Success
Then, set GPIO0 (LED0) to an open-drain output initialized to a high value. (Uses gdi)
> gdi 0 ohi od Success
Finally, set the blink pattern as described above. (Uses sy i s)
> set sy i s 00017F000404 Success
BGX commands can be run in a few ways. These include a PC's serial terminal, the BGX Commander mobile app, or through user functions. User function must be given an event trigger in the form of an input pin asserted high or low - buttons are perfect for this. This demo will use 2 buttons to call 5 user functions as seen below.
|Short Press||send Hello|
|Long Press||dct||con xpr|
For a pin (in this case a button) to be a trigger for a user function, it must be set to a ufu_level with the gfu command. Here is how to set GPIO2 (BTN0) and GPI03 (BTN1) to ufu_level. (Uses gfu)
> gfu 2 ufu_level Success > gfu 3 ufu_level Success
Now that the buttons have been enabled for user functions, it is time to make a list of all the functions that will be called. (Uses ufu)
Set "adv xpr" to user function 0.
> ufu 0 adv xpr Success
Set "con xpr" to user function 1.
> ufu 1 con xpr Success
Set "dct" to user function 2.
> ufu 2 dct Success
Set "send Hello" to user function 3.
> ufu 3 send "Hello\r\n" Success
Set "send Hi" to user function 4.
> ufu 4 send "Hi\r\n" Success
Finally, it is time to map user functions and GPIOs together. This is also where the event trigger is configured. The types of user event triggers are displayed below. The press has to be at least 2 seconds to register a long-press. 2 seconds is the default time for the BGX. This time comes from (uf l p) * 100 milliseconds where the default uf l p is 20.
|Event Trigger||User function will run...|
|lo||On a falling edge of a ufu_level pin|
|lo_short||When the ufu_level pin is low < 2 seconds|
|lo_long||When the ufu_level pin is low >= 2 seconds|
|hi||On a rising edge of a ufu_level pin|
|hi_short||When the ufu_level pin is high < 2 seconds|
|hi_long||When the ufu_level pin is high >= 2 seconds|
|boot||Every time the device boots up (power-on, pin reset, software reset)|
|con||After a BLE connection is successfully established|
|dct||After a BLE connection is killed|
Event Trigger Use Cases
This demo takes advantage of the ufu_level event triggers which include lo, lo_short, lo_long, hi, hi_short, and hi_long. Some use cases for these triggers can be to use a:
- Button to send a message
- Button to establish a connection
- Button to disconnect
- Button to begin BLE advertising
- Slider to turn on/off an LED
The user function will run every time the device boots up. Any reset (power-on, pin, software, etc) triggers it. After reset, the BGX will do all its initialization, and then, if there is a boot event, it will run that function. After it executes, it will not execute again until the next reset. Some use cases for this trigger can be to:
- Issue a connect out of reset
- Issue a "sleep" command so the device is in sleep mode after booting up
- Issue a "str" command if command mode isn't desired and the device just needs to be in stream mode. This could also be accomplished by tying a stream mode selecting pin to high, but it uses an extra pin in the process.
- Drive GPIOs low or high out of reset to turn on LEDs or enable external components
con / dct
The user function will run after a BLE connection is successfully established or killed, depending on which trigger is chosen. Some use cases for these triggers can be to:
- Issue a "sleep" command upon disconnect
- Issue a "str" command upon disconnect
- Drive GPIOs low or high out of a connect/disconnect to turn on LEDs or enable external components
Assign GPIO2 (BTN0) to trigger user function 0 (adv xpr) on a short press to set up the Xpress Advertise button. (Uses uevt)
> uevt 0 lo_short 2 Success
Assign GPIO2 (BTN0) to trigger user function 1 (con xpr) on a long press to set up the Xpress Connect button.
> uevt 1 lo_long 2 Success
Assign GPIO3 (BTN1) to trigger user function 2 (dct) on a long press to set up the disconnect button.
> uevt 2 lo_long 3 Success
Assign GPIO3 (BTN1) to trigger user function 3 (send Hello) on a short press to set up the first send message button.
> uevt 3 lo_short 3 Success
Assign GPIO3 (BTN1) to trigger user function 4 (send Hi) on a short press to set up the second send message button.
> uevt 4 lo_short 3 Success
It's important to debounce the buttons so that bounces don't occur during the press or release of a button. This step will prevent 1 button press from showing up as multiple button presses. (Uses gdi)
First, BTN0 needs to be debounced for ~20 ms.
> gdi 2 inw db1 Success
Similarly, BTN1 needs to be debounced for ~20 ms.
> gdi 3 inw db1 Success
The BGX should be initialized to not advertise. This allows the radio to completely shut off when it is idle. This is done by setting the BLE advertising preference to off. (Uses bl v p)
> set bl v p off Success
Only after BTN0 is pressed, does the BGX begin to Xpress Advertise. The advertising duration should be reduced from 30 seconds to 5 seconds to further reduce power consumption. Set advertising Xpress mode duration to 5 seconds. (Uses bl v x d)
> set bl v x d 5 Success
The BGX has a default baud rate of 115200. The UART cannot be disabled and is always on. This isn't a power consumption problem because BGX has a low power mode that is activated when the baud rate is set to 9600 or lower. Active mode current consumption is greatly reduced by reducing the baud rate to 9600. (Uses ua b and uartu)
> set ua b 9600 Success > uartu Success
The serial terminal program on the PC may still use 115200 baud to communicate to the BGX so it is important to update the serial terminal program to 9600. Do NOT unplug the BGX. The BGX will return to its default state if it is unplugged before a save.
The entire configuration above should be saved to prevent needing to set up all the variables again. Otherwise, a reset would bring the BGX back to a default state. All the commands have been provided below to allow an easy copy and paste to a serial terminal. (Uses save)
> save Success
Reset the BGX after a successful save. The BGX is now ready to demo.
All Configuration Commands
The text below can be used to program all the functions listed above in a quick and easy way. Simply copy and paste the text into a serial terminal and send the commands to the connected BGX. Be sure to verify that all commands result in SUCCESS.
gfu 0 con_status_led gdi 0 ohi od set sy i s 00017F000404 gfu 2 ufu_level gfu 3 ufu_level ufu 0 adv xpr ufu 1 con xpr ufu 2 dct ufu 3 send Hello ufu 4 send Hi uevt 0 lo_short 2 uevt 1 lo_long 2 uevt 2 lo_long 3 uevt 3 lo_short 3 uevt 4 lo_short 3 gdi 2 inw db1 gdi 3 inw db1 set bl v p off set bl v x d 5 set ua b 9600 save uartu