Gecko OS Application Structure
App Functions
A Gecko OS Application (App) has three functions called by Gecko OS:
gos_app_init
void gos_app_init(void)
All Gecko OS applications must implement this function.
This is the starting point of the application.
Here is where an App should prepare the application for its run-time operations, such as:
- configure settings
- register handlers
- enable Gecko OS features/peripherals
gos_app_deinit
void gos_app_deinit(void)
This function is called just before the application terminates.
This function is optional and may be omitted.
Here the application should save any volatile data structures that need to persist through application cycles.
Also, if necessary, external peripherals and components should be properly shutdown in this function.
gos_app_idle
gos_bool_t gos_app_idle(void)
This function is called whenever the App has no more events to execute.
When the function returns, the App can return either
TRUE
or
FALSE
.
If it returns
TRUE
, then Gecko OS idles the application until another event is available to execute.
If it returns
FALSE
, then Gecko OS terminates the application.
The function is optional and may be omitted. If omitted then Gecko OS defaults to
FALSE
: once the application has no more events, the App terminates.
App Operation
An App follows an event driven programming model. Event handlers are registered and then are asynchronously executed based on the state of the system.
When no events are executing the application idles, and Gecko OS and goes into a low power state.
App events typically execute in the App thread. Events and other callbacks may also execute in other threads or contexts. See:
Note : Gecko OS runs multiple background processes. These processes follow a similar event driven model and wake Gecko OS when required.
Example
Consider a simple TCP client App.
On startup the App opens a TCP connection to a remote server and periodically transmits a data packet.
The remote TCP server sends data back to the App.
The App attempts to re-open the connection when it disconnects.
This example is described below. The source code is available in the following SDK directory:
examples/network/tcp_client
See the network/tcp_client example documentation for details. See the tcp_client source code for implementation of the functions discussed below.
This App must respond to the following events:
- TCP disconnected
- TCP data received
- Periodic data transmit
On startup, i.e. in
gos_app_init()
, the App:
-
Sets up a network handler,
wlan_network_event_handler
. -
When the network is up,
wlan_network_event_handler
, in turn, issues the eventtcp_attempt_connect_handler
-
tcp_attempt_connect_handler
attempts to open the TCP connection.-
IF successful,
tcp_attempt_connect_handler
:- Registers TCP disconnect and data received event handlers
-
Registers the periodic data transmit event handler
-
ELSE:
-
tcp_attempt_connect_handler
schedules a TCP connection attempt in the future
-
-
IF successful,
After
gos_app_init()
returns, the App idles and Gecko OS waits until then next event should execute.
The following event handlers asynchronously execute in the App Thread when needed:
tcp_disconnect_handler
This event handler is executed when the TCP connection is closed. When the TCP connection closes, the App should attempt to reopen the connection.
tcp_receive_handler
This event handler is executed when the TCP connection has data to be read. When data is available, the App reads the TCP connection's data.
tcp_transmit_handler
This event handler is periodically called to send data to the remote server.