Button Device URI Management

CoAP URI management for button device. More...

Functions
otapp_coap_uri_t *	ad_btn_uri_getList_clb (void)
	Driver callback to get list of registered CoAP URI handlers.
uint8_t	ad_btn_uri_getListSize (void)
	Get number of registered URI handlers.
void	ad_btn_uri_init (ot_app_devDrv_t *devDrv)
	Initialize URI handlers for button device.

Detailed Description

CoAP URI management for button device.

Overview

This module manages CoAP URI endpoints for the button device, enabling remote control and status queries over the OpenThread network.

The button device exposes a single CoAP endpoint:

• btn/state: Query button state and receive button press notifications

URI Architecture

The URI system uses a callback-based architecture:

1. URI Registration: URI is stored in static array ad_button_uri[] (ad_btn_uri.c)
2. Driver Callback: ad_btn_uri_getList_clb() is registered with the device driver
3. Driver Access: The framework calls the callback to retrieve registered URI
4. Request Handling: CoAP requests to the URI invoke the handler

URI Request Flow

CoAP Request → Driver → ad_btn_uri_getList_clb() → URI List
                   ↓
            Find Matching URI ("btn/state")
                   ↓
         Invoke ad_button_uri_btn_state_CoreHandle()
                   ↓
       processUriRequest() → Parse Message
                   ↓
           Process & Respond

Button State Endpoint

URI Path: btn/state

Type: OTAPP_SWITCH

Supported Operations:

• Observer Mode: Subscribe to button state changes (CoAP Observe)
• Direct Request: Query current button state (CoAP GET)

Use Cases:

• Remote devices can subscribe to receive notifications when button is pressed
• Other devices can query current button state
• Button device can push state updates to subscribed observers

Adding Custom URI Handlers

To add additional URI endpoints:

Step 1: Define URI handler function with CoAP handler signature:

void my_custom_uri_handler(void *aContext, otMessage *aMessage, const otMessageInfo *aMessageInfo)
{
    int8_t result = 0;
    result = drv->api.coap.processUriRequest(aMessage, aMessageInfo, 
                                             OTAPP_CUSTOM_TYPE, 
                                             coapBuffer, 
                                             OAC_URI_OBS_BUFFER_SIZE);
    
    if(result == OTAPP_COAP_OK) {
        // Handle URI request here
        printf("Custom URI payload: %s\n", (char*)coapBuffer);
    } else {
        printf("Custom URI error: %d\n", result);
    }
}

Step 2: Add URI to the array in ad_btn_uri.c:

static otapp_coap_uri_t ad_button_uri[] = {
    {OTAPP_SWITCH, {"btn/state", ad_button_uri_btn_state_CoreHandle, NULL, NULL},},
    // Add your custom URI here
    {OTAPP_CUSTOM_TYPE, {"btn/config", my_custom_uri_handler, NULL, NULL},},
};

Step 3: Size is automatically calculated by AD_BUTTON_URI_SIZE macro:

#define AD_BUTTON_URI_SIZE (sizeof(ad_button_uri) / sizeof(ad_button_uri[0]))

URI Constraints

• Maximum URIs: OTAPP_PAIRED_URI_MAX (defined in ot_app_drv.h)
• Maximum URI name length: OTAPP_COAP_URI_MAX_LENGHT (defined in ot_app_drv.h)
• URI format: Use forward slash separator (e.g., "btn/state", "btn/config")

Usage Example

Initialization

// Initialize device driver
ot_app_devDrv_t *driver = get_device_driver();
 
// Initialize URI handler - registers callback with driver
ad_btn_uri_init(driver);
 
// Driver will call ad_btn_uri_getList_clb() to retrieve URI list

Querying Registered URI

// Get registered URI via driver callback
otapp_coap_uri_t *uri = ad_btn_uri_getList_clb();
uint8_t count = ad_btn_uri_getListSize();
 
printf("Registered URI: %s (count: %d)\n", uri[0].coap_uri.mUriPath, count);
// Output: Registered URI: btn/state (count: 1)

See also

ot_app_drv.h for otapp_coap_uri_t structure definition

ad_button.h for device initialization

Version

0.1

Date

12-11-2025

Author

Jan Łukaszewicz (plhar.nosp@m.eo@g.nosp@m.mail..nosp@m.com)

Copyright

© 2025 MIT LICENCE

Function Documentation

ad_btn_uri_getList_clb()

otapp_coap_uri_t * ad_btn_uri_getList_clb

(

void

)

Driver callback to get list of registered CoAP URI handlers.

This function is a callback registered with the device driver during initialization. The driver framework calls this function to retrieve the button device's CoAP URI and its associated handler.

Callback Flow:

1. ad_btn_uri_init() registers this callback with driver
2. Driver stores callback pointer: driver->uriGetList_clb = ad_btn_uri_getList_clb
3. When needed, driver invokes: otapp_coap_uri_t *list = driver->uriGetList_clb()
4. Driver uses returned URI to route CoAP "btn/state" requests to the handler

Returns

Pointer to static array of otapp_coap_uri_t structures

Return values

ad_button_uri	Array containing single URI: "btn/state"
NULL	Can be returned if URI list is empty (currently not implemented)

Note

This function returns a pointer to a static internal array valid for application lifetime

The returned array contains exactly 1 element (AD_BUTTON_URI_SIZE = 1)

This is a callback function - typically called by driver, not directly by user code

Warning

Do not modify the returned array - it is read-only

See also

ad_btn_uri_getListSize() to get number of URIs in the returned array (returns 1)

ad_btn_uri_init() for callback registration

ad_btn_uri_getListSize()

uint8_t ad_btn_uri_getListSize

(

void

)

Get number of registered URI handlers.

Returns the count of URI endpoints registered in the internal URI list. This corresponds to the size of the array returned by ad_btn_uri_getList_clb().

Returns

Number of URIs in the list

Return values

1	Current implementation registers single URI: "btn/state"
0	Can be returned if no URIs registered (currently not implemented)

Note

Current implementation returns: AD_BUTTON_URI_SIZE = 1

See also

ad_btn_uri_getList_clb()

ad_btn_uri_init()

void ad_btn_uri_init

(

ot_app_devDrv_t *

devDrv

)

Initialize URI handlers for button device.

Parameters

[in]

devDrv

Pointer to device driver structure

This function performs the following initialization steps:

1. Validates device driver pointer
2. Stores driver reference in static variable drv for use by URI handler
3. Registers callback ad_btn_uri_getList_clb() with the driver

After initialization, the driver can:

• Call ad_btn_uri_getList_clb() to retrieve the "btn/state" URI
• Route incoming CoAP "btn/state" requests to the registered handler
• Enable remote devices to query button state or subscribe to button events

Typical initialization sequence:

ot_app_devDrv_t driver;
// ... initialize driver structure ...
 
ad_btn_uri_init(&driver);  // Register URI callback
ad_button_Init();          // Complete device initialization

Note

Must be called after device driver structure allocation

Must be called before ad_button_Init()

Calling with NULL pointer has no effect (safe, but initialization will fail)

Warning

Do not call this function multiple times with different drivers

See also

ad_button_Init() for complete device initialization

ad_btn_uri_getList_clb() for registered callback function