Events, Callbacks, Event Handlers and Execution Contexts

Events and Contexts

ZentriOS is an event driven system. See ZAP Operation.

There are several types of event, grouped according to the triggers for the event and the context in which the event executes. See Native API Event Types below.

In this documentation we distinguish between the terms callback and event handler, according to the execution context:

• A callback executes in the same execution context as the associated event registration.

• An event handler executes in a different execution context to the associated event registration.

ZentriOS can respond to events with callbacks or event handlers that execute in a particular execution contexts. An Execution Context is a thread, except in the cases of the IRQ Execution Context and the RTOS Timer Context.

Execution contexts are listed below. These are covered in more detail in Execution Contexts.

• ZAP
• Hardware IRQ
• RTOS Timer
• Network
• System Event
• HTTP Server
• Command

Event handlers for TCP events are executed in the ZAP context.

Special Context Considerations

Some execution contexts have limited resources. To switch processing to another execution context, you can issue an event with an event handler that executes in another context. For example, you can issue an event with zn_event_issue.

Limited resource contexts include RTOS Timer, IRQ and System Event Thread.

System Event Context

Events executing in the System event thread MUST NOT block as no other events can execute until it completes.

Command Context

ZentriOS commands and custom commands execute in the Command thread context. Custom commands cannot call any of the zn_issue_command functions, as it would create a deadlock. The ZentriOS API explicitly prevents a deadlock: a call to zn_issue_command from within the Command thread fails automatically with a ZOS_NESTED_CMD result code. See zos_result_t.

Native API Event Types

In this section, events are listed according to type, with details of:

• how to register the event
• what triggers the event
• the callback or event handler context
• how to unregister the event

Commands

• Custom Commands
  • zn_cmd_register_commands
  • zn_cmd_unregister_commands
  • Command Macros
    • ZOS_CMD_REGISTER_COMMANDS
      • Commands are defined with ZOS_ADD_COMMAND and ZOS_DEFINE_COMMAND macros
      • Trigger: Activity on any command interface:
        • bus.data_bus
        • bus.log_bus (if bus.log_bus = log)
        • REST API
        • remote terminal
        • DMS command console (if enabled)
      • Callback context: Command thread
    • ZOS_CMD_UNREGISTER_COMMANDS

Issued Events

• Event API
  • zn_event_issue - immediately issue an event then automatically unregister
    • Event handler: By default the event handler executes in the ZAP thread. Use the ZOS_EVENT_FLAG_SYS_EVENT_THREAD flag to have the handler execute in the system event thread.

Timed Events

For more detail see Timed Events.

Event API

• Event API
  • Registering and Unregistering Events
  • zn_event_register_periodic
    • Trigger: specified period expires
    • Callback context: Execution context in which event registered
  • zn_event_register_timed
    • Trigger: specified time occurs
    • Callback context: Execution context in which event registered
  • zn_event_unregister

RTOS Timer

• RTOS Timer
  • zn_rtos_timer_init
    • Trigger: Called each time the timer expires
    • Callback context: RTOS

File System Events

• File System
  • zn_file_list_with_callback
    • Trigger: call returns with list of files
    • Callback context: Synchronous with API - same context. Callback is invoked for each listed file.

Hardware IRQ Events

• Hardware/GPIO API
  • zn_gpio_irq_enable
    • Trigger: Specified zos_gpio_irq_trigger_t GPIO edge event
    • Callback context: IRQ

UART Events

• Hardware/UART
  • zn_uart_register_rx_callback
    • Trigger: character received on UART
    • Callback context: IRQ

HTTP/S Server Events

• HTTP Server
  • zn_hs_register_authorize_callback
    • Trigger: a remote client attempts to connect when authorization is enabled
    • Callback context: HTTP server thread
  • zn_hs_register_header_callback
    • Trigger: corresponding header key is found in a HTTP request.
    • Callback context: HTTP server thread
  • zn_hs_register_not_found_callback
    • Trigger: HTTP request results in a 404 response
    • Callback context: HTTP server thread
  • zn_hs_register_dynamic_page
    • Callback context: HTTP server thread
  • Custom Dynamic HTTP Pages
    • HTTP_SERVER_REGISTER_DYNAMIC_PAGES

HTTP/S Server Stream Events

• HTTP Server Stream
  • zn_hs_stream_register_callback
    • Trigger: remote client issues request
    • Callback context:
      • REST implementation: HTTP server
      • websocket implementation: ZAP
  • zn_hs_register_websocket_callbacks
    • Triggers:
      • zos_hs_ws_connect_callback_t handler: websocket client connects
        • Callback context: HTTP server
      • zos_hs_ws_disconnect_callback_t handler: websocket client disconnects
        • Callback context: ZAP
  • zn_hs_stream_unregister_callbacks

Network Events

• Network events
  • zn_network_register_event_handler
    • Triggers:
      • network up
      • network down
      • Event handler context: ZAP
  • zn_network_register_softap_event_handler
    • Triggers: softap client
      • softap client connect
      • softap client disconnect
      • Event handler context: ZAP
    • Examples:
      • Basic/SoftAP TCP Server

Unregistering a Network Event

There is only one network event. To unregister it, pass a NULL to the register API:

zn_network_register_event_handler(WLAN, NULL)

zn_network_register_softap_event_handler(NULL)

Periodic Broadcast Events

• Periodic Broadcast
  • zn_broadcast_set_callback
  • Trigger: broadcast period expires. See command API broadcast.interval
  • Callback context: Network
  • Deregister: zn_broadcast_set_callback(NULL) - See Network Events above. Ensure this is deregistered in zos_deinit()

System

System Functions, Miscellaneous

• System IRQ Callbacks
  • zn_system_register_irq_callback
    • Callback context: IRQ
    • Deregister: zn_unregister_system_monitor(zos_system_monitor_t * system_monitor)
  • zn_system_register_system_tick_callback
    This is triggered on the ARM SystemTick IRQ every 1ms.
    • Callback context: IRQ

System Monitor Events

• System Monitor
  • zn_register_system_monitor
    • No callback: - Before specified delay, call zn_update_system_monitor, or zn_unregister_system_monitor, otherwise watchdog fault triggers, resulting in software reset.
    • Deregister: zn_unregister_system_monitor

TCP Events

• TCP
  • zn_tcp_register_client_event_handlers
    • Triggers:
      • zos_stream_event_handler_t disconnect: Client disconnects
        • Event handler context: ZAP
      • zos_stream_event_handler_t receive: Data received from client
        • Event handler context: ZAP
  • zn_tcp_register_server_event_handlers
    • Triggers:
      • zos_stream_event_handler_t connect: Client connects
        • Event handler context: ZAP
      • zos_stream_event_handler_t disconnect: Client disconnects
        • Event handler context: ZAP
      • zos_stream_event_handler_t receive: Data recieved from client
        • Event handler context: ZAP
    • Examples:
      • Basic/SoftAP TCP Server

UDP Events

• UDP server
  • zn_udp_register_receive_event_handler
    • Trigger: UDP client or server has data to be read
    • Event handler context: ZAP
    • Examples:
      • basic/udp-client

Button Events

• Utilities/Button API
  • button_init
    • Triggers (callbacks specified in button_config_t parameter):
      • zos_event_handler_t click
        • Event handler context: Specify in button_config_t button_execution_context_t: ZAP, System Event, or IRQ
      • zos_event_handler_t toggle
        • Event handler context:
      • zos_event_handler_t change
        • Event handler context: Specify in button_config_t button_execution_context_t: ZAP, System Event, or IRQ
      • unregister: button_deinit
    • Example: basic/button

Web Setup Events

• Web Setup Events
  • zn_setup_register_client_event_handler
    • Trigger: Client connects to the setup softap AND client connects to the HTTP server
    • Event handler context: ZAP
  • zn_setup_register_finished_event_handler
    • Trigger: Web setup completed by
      • Manual stop
      • Idle timeout
      • Client completes device setup
    • Event handler context: ZAP

WebSocket Events

• Web socket
  • zn_websocket_register_client_event_handlers
    • Triggers
      • zos_stream_event_handler_t disconnect: client disconnects
        • Event handler context: ZAP
      • zos_stream_event_handler_t receive: data received from client
        • Event handler context: ZAP
  • zn_websocket_register_server_event_handlers
    • Triggers
      • zos_stream_event_handler_t connect: client connects
        • Event handler context: ZAP
      • zos_stream_event_handler_t disconnect: client disconnects
        • Event handler context: ZAP
      • zos_stream_event_handler_t receive: data received from client
        • Event handler context: ZAP

Library Event Functions

• S2C Library
  • s2c_register_listener
    • Trigger: the corresponding stream receives data from either the cloud or local client.
  • s2c_unregister_listener
• LED Matrix 8x8 Library
  • led_matrix8x8_animate
    • Trigger: frame period expires
• base64_writer_callback
• json_token_callback_t
• error_status_callback