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:

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:

apps/basic/tcp_client

See the basic/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:

On startup, i.e. in gos_app_init(), the App:

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.