Back to main page: Leveraging TAG4 to better understand the WICED Smart Programming Environment
When programming on the WICED Smart platform you are operating on our kernel. The kernel is responsible for the timing and handling of all processes related to the chip. The terms that you hear used commonly in embedded coding—timers, interrupts, BLE events, handlers, callbacks, etc.—are all interactions with the kernel. Not surprisingly, they’re the only way to interact with the kernel—and, some interaction with the kernel must take place in order for any of your code to be executed outside of the create function.
Because you’re operating on a kernel, there is no main function. Instead, there is a “create” function which executes once on every power-up. Also embedded in the kernel is a watchdog timer. If any statement in one of your callbacks (explained below) takes more than 2 seconds to execute, the kernel will reset the chip to terminate the process—your code is sure to fail with an infinite loop in there.
Before you embark on creating your own applications, it’s important to have a feeling for the layout of a basic application and how to interact with the kernel at a basic level.
Registering for callbacks
There are three very important callbacks that will be utilized in almost every single application you create. They are almost always registered in the create function. For all of the following callback functions, you must do three things:
- Declare the function
- Define the function
- Register the function as a callback
The “connection_up” callback is called every time the device establishes a connection with a master device. Upon connection, one will generally want to stop advertisements. Additionally, you may wish to initialize a sensor or carry out other tasks that are only performed when in connection.
//register the callback in create fx
bleprofile_regAppEvtHandler(BLECM_APP_EVT_LINK_UP, called_on_conn_up);
The “connection_down” callback is called every time the device disconnects from its master device. Generally, you will restart advertisements in this function. Additionally, you may wish to de-initialize sensors or anything else that may conserve power while you are not in a connection in not in need of.
//register the callback in create fx
bleprofile_regAppEvtHandler(BLECM_APP_EVT_LINK_DOWN, called_on_conn_down);
The “advertisement_stopped” callback is called when the device has been advertising and has surpassed its set advertisement period without having entered a connection (advertisement period customized below). Without this callback function, the app will go dead once advertisements stop because the app never sets up a process to reinitiate them (there are ways around this: interrupts, timers, etc.). Naturally, we then want to put something in this function which restarts advertisements under some circumstance.
//register the callback in create fx
bleprofile_regAppEvtHandler(BLECM_APP_EVT_ADV_TIMEOUT, called_on_adv_stopped);
Registering Timers
The timers are very important when you are first learning the use the WICED platform. They provide an extremely easy approach to interacting with the kernel without having to deal with interrupts (which will be explained in a later post).
The timers, which must be instantiated together, call two respective functions every time the timer completes a cycle. The regular timeout always calls its function once per second. On the other hand, the “fine timeout” calls its function however frequently you wish (within reason). If you set the fine timeout to be called in the range of microseconds (below 5ms) it will significantly inhibit the timing of the kernel and likely disable all BLE transmissions.
The timers can be started and stopped at your will using the WICED API.
Add to your create function:
bleprofile_regTimerCb(fine_timeout, one_sec_timeout);
Define and declare the callback functions:
static void one_sec_timeout( UINT32 count );
static void fine_timeout( UINT32 finecount );
Altering fine timer:
const BLE_PROFILE_CFG hello_sensor_cfg = {
/*.fine_timer_interval =*/ 1000, // ms
}
Start/Stop APIs:
bleprofile_StartTimer();
bleprofile_KillTimer();
Customizing Advertising Interval and Timeout
This won’t come in handy until the completion of your first app, when you will be attempting to optimize your power consumption. The WICED platform allows you to customize the duration of “high” advertising (more frequent/powerful transmissions) as well as the subsequent “low” advertisements (less powerful, less frequent transmissions). At the end of both of these durations, if we have registered for an “advertisement_stopped” callback, it will be called.
const BLE_PROFILE_CFG hello_sensor_cfg = {
/*.fine_timer_interval =*/ 1000, // ms
/*.default_adv =*/ 4, // HIGH_UNDIR
/*.button_adv_toggle =*/ 0, // pairing button
/*.high_undirect_adv_interval =*/ 32, // slots
/*.low_undirect_adv_interval =*/ 1024, // slots
/*.high_undirect_adv_duration =*/ 30, // seconds
/*.low_undirect_adv_duration =*/ 300, // seconds
}
For further reading, refer toHow to Write WICED Smart Applications. You will find longer lists of event callbacks that are at your disposal.
Jacob W. Torres
Back to main page: Leveraging TAG4 to better understand the WICED Smart Programming Environment
