ZentriOS Application Structure

ZAP Functions

A ZentriOS Application (ZAP) has three functions called by ZentriOS:

zn_app_init

void zn_app_init(void)

All ZentriOS application must implement this function.

This is the starting point of the application.

Here is where a ZAP should prepare the application for its run-time operations, such as:

zn_app_deinit

void zn_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.

zn_app_idle

zos_bool_t zn_app_idle(void)

This function is called whenever the ZAP has no more events to execute.

When the function returns, the ZAP can return either ZOS_TRUE or ZOS_FALSE.

If it returns ZOS_TRUE, then ZentriOS idles the application until another event is available to execute.

If it returns ZOS_FALSE, then ZentriOS terminates the application.

The function is optional and may be omitted. If omitted then ZentriOS defaults to ZOS_FALSE: once the application has no more events, the ZAP terminates.

ZAP Operation

A ZAP 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 ZentriOS and goes into a low power state.

ZAP events typically execute in the ZAP thread. Events and other callbacks may also execute in other threads or contexts. See Execution Contexts.

Note: ZentriOS runs multiple background processes. These processes follow a similar event driven model and wake ZentriOS when required.

Example

Consider a simple TCP client ZAP.

On startup the ZAP opens a TCP connection to a remote server and periodically transmits a data packet.

The remote TCP server sends data back to the ZAP.

The ZAP 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.c source code for implementation of the functions discussed below.

This ZAP must respond to the following events:

On startup, i.e. in zn_app_init(), the ZAP:

After zn_app_init() returns, the ZAP idles and ZentriOS waits until then next event should execute.

The following event handlers asynchronously execute in the ZAP Thread when needed:

tcp_disconnect_handler

This event handler is executed when the TCP connection is closed. When the TCP connection closes, the ZAP 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 ZAP reads the TCP connection's data.

tcp_transmit_handler

This event handler is periodically called to send data to the remote server.