ZentriOS Application Structure
A ZentriOS Application (ZAP) has three functions called by ZentriOS:
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:
- configure settings
- register handlers
- enable ZentriOS features/peripherals
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.
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.
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:
Note: ZentriOS runs multiple background processes. These processes follow a similar event driven model and wake ZentriOS when required.
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:
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:
- TCP disconnected
- TCP data received
- Periodic data transmit
On startup, i.e. in
zn_app_init(), the ZAP:
- Sets up a network handler,
- When the network is up,
wlan_network_event_handler, in turn, issues the event
tcp_attempt_connect_handlerattempts to open the TCP connection.
- IF successful,
- Registers TCP disconnect and data received event handlers
- Registers the periodic data transmit event handler
tcp_attempt_connect_handlerschedules a TCP connection attempt in the future
- IF successful,
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:
This event handler is executed when the TCP connection is closed. When the TCP connection closes, the ZAP should attempt to reopen the connection.
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.
This event handler is periodically called to send data to the remote server.