Events, Callbacks, Event Handlers and Execution Contexts

Events and Contexts

Gecko OS is an event driven system. See App 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.

Gecko OS 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.

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

Event handlers for TCP events are executed in the App 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 gos_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

Gecko OS commands and custom commands execute in the Command thread context. Custom commands cannot call any of the gos_cmd_issue functions, as it would create a deadlock. The Gecko OS API explicitly prevents a deadlock: a call to gos_cmd_issue* from within the Command thread fails automatically with a GOS_NESTED_CMD result code. See gos_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

Issued Events

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

Timed Events

For more detail see Timed Events.

Event API

• Event API
  • Registering and Unregistering Events
  • gos_event_register_periodic
    • Trigger: specified period expires
    • Callback context: Execution context in which event registered
  • gos_event_register_timed
    • Trigger: specified time occurs
    • Callback context: Execution context in which event registered
  • gos_event_unregister

RTOS Timer

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

File System Events

• File System
  • gos_file_list with callback specified in gos_file_list_parameters_t
    • 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
  • gos_gpio_irq_enable
    • Trigger: Specified gos_gpio_irq_trigger_t GPIO edge event
    • Callback context: IRQ

UART Events

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

HTTP/S Server Events

• HTTP Server
  • gos_hs_register_authorize_callback
    • Trigger: a remote client attempts to connect when authorization is enabled
    • Callback context: HTTP server thread
  • gos_hs_register_header_callback
    • Trigger: corresponding header key is found in a HTTP request.
    • Callback context: HTTP server thread
  • gos_hs_register_not_found_callback
    • Trigger: HTTP request results in a 404 response
    • Callback context: HTTP server thread
  • gos_hs_register_dynamic_page
    • Callback context: HTTP server thread
  • Custom Dynamic HTTP Pages
    • GOS_HTTP_SERVER_REGISTER_DYNAMIC_PAGES

Network Events

• Network events
  • gos_network_register_event_handler
    • Triggers:
      • network up
      • network down
      • Event handler context: App
  • gos_network_register_softap_event_handler
    • Triggers: softap client
      • softap client connect
      • softap client disconnect
      • Event handler context: App
    • Examples:
      • network/softap_tcp_server

Unregistering a Network Event

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

gos_network_register_event_handler(WLAN, NULL)

gos_network_register_softap_event_handler(NULL)

Periodic Broadcast Events

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

System

System Functions, Miscellaneous

• System IRQ Callbacks
  • gos_system_set_irq_callback
    • Callback context: IRQ
    • Deregister:
  • gos_system_set_system_tick_callback
    This is triggered on the ARM SystemTick IRQ every 1ms.
    • Callback context: IRQ

System Monitor Events

• System Monitor
  • gos_register_system_monitor
    • No callback: - Before specified delay, call gos_update_system_monitor, or gos_unregister_system_monitor, otherwise watchdog fault triggers, resulting in software reset.
    • Deregister: gos_unregister_system_monitor

TCP Events

• TCP
  • gos_tcp_register_client_event_handlers
    • Triggers:
      • gos_stream_event_handler_t disconnect: Client disconnects
        • Event handler context: App
      • gos_stream_event_handler_t receive: Data received from client
        • Event handler context: App
  • gos_tcp_register_server_event_handlers
    • Triggers:
      • gos_stream_event_handler_t connect: Client connects
        • Event handler context: App
      • gos_stream_event_handler_t disconnect: Client disconnects
        • Event handler context: App
      • gos_stream_event_handler_t receive: Data recieved from client
        • Event handler context: App
    • Examples:
      • network/softap_tcp_server

UDP Events

• UDP server
  • gos_udp_register_receive_event_handler
    • Trigger: UDP client or server has data to be read
    • Event handler context: App
    • Examples:
      • network/udp_client

Button Events

• Utilities/Button API
  • gos_button_init
    • Triggers (callbacks specified in gos_button_config_t parameter):
      • gos_event_handler_t click
        • Event handler context: Specify in gos_button_config_t button_execution_context_t: App, System Event, or IRQ
      • gos_event_handler_t toggle
        • Event handler context:
      • gos_event_handler_t change
        • Event handler context: Specify in gos_button_config_t button_execution_context_t: App, System Event, or IRQ
      • unregister: gos_button_deinit
    • Example: peripheral/button

Web Setup Events

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

WebSocket Events

• Web socket
  • gos_websocket_register_client_event_handlers
    • Triggers
      • gos_stream_event_handler_t disconnect: client disconnects
        • Event handler context: App
      • gos_stream_event_handler_t receive: data received from client
        • Event handler context: App
  • gos_websocket_register_server_event_handlers
    • Triggers
      • gos_stream_event_handler_t connect: client connects
        • Event handler context: App
      • gos_stream_event_handler_t disconnect: client disconnects
        • Event handler context: App
      • gos_stream_event_handler_t receive: data received from client
        • Event handler context: App