Gateway

Table of Contents

• Allocation
• Sending Data
• Time Measurement
• Advertise Period
• Gateway ID
• Start Operation

The Gateway object is responsible to advertise the gateway presence to all the possible clients on MQTT-SN network. If such advertisement is not needed, there is no need to create or use the Gateway object.

Allocation

When using C++ interface, just instantiate object of cc_mqttsn_gateway::Gateway class. The destruction of the object will clean up all acquired resources.

cc_mqttsn_gateway::Gateway gw;

When using C interface, the allocation is performed using cc_mqttsn_gw_alloc()

CC_MqttsnGatewayHandle gw = cc_mqttsn_gw_alloc();

and de-allocation is performed using cc_mqttsn_gw_free() functions.

cc_mqttsn_gw_free(gw);

Sending Data

As was stated, the Gateway object is responsible to periodically broadcast ADVERTISE messages to all MQTT-SN clients on the network to advertise its presence. The library just generates the binary data, that needs to be sent, and uses a callback function to request the driving code to send this data over I/O link being used. The required callback needs to be provided by the driving code.

C++ interface:

gw.setSendDataReqCb(
    [](const std::uint8_t* buf, std::size_t bufLen)
    {
        ... // Broadcast the requested data
    });

C interface:

void my_advertise_broadcast(void* userData, const unsigned char* buf, unsigned bufLen)
{
    ... /* Broadcast the provided buffer */
}
 
cc_mqttsn_gw_set_advertise_broadcast_req_cb(gw, &my_advertise_broadcast, someUserData);

Time Measurement

As was mentioned earlier there is a need to send ADVERTISE messages periodically. As the result the Gateway object needs to perform some time measurement. It relies on the driving code to provide such service. There is a need to set appropriate callback:

C++ interface:

gw.setNextTickProgramReqCb(
    [](unsigned duration)
    {
        ... // Set timer to expire after duration milliseconds
            // After expiry call gw.tick()
    };

C interface:

void my_tick_req(void* userData, unsigned duration)
{
    ... /* Set timer to expire after duration milliseconds */
    ... /* After expiry call cc_mqttsn_gw_tick() */
}
 
cc_mqttsn_gw_set_tick_req_cb(gw, &my_tick_req, someUserData);

After the requested time expires, the driving code needs to notify the Gateway object. It must call the appropriate tick() function.

C++ interface:

gw.tick();

C interface:

cc_mqttsn_gw_tick(gw); 

Advertise Period

The ADVERTISE message must be sent periodically. The message itself contains information when next ADVERTISE message will be sent. The Gateway object cannot operate without the advertise period being set.

C++ interface:

gw.setAdvertisePeriod(900); // The advertise period is in seconds

C interface:

cc_mqttsn_gw_set_advertise_period(gw, 900); /* The advertise period is in seconds */

It is also possible to retrieve the current configuration:

C++ interface:

std::uint16_t period = gw.getAdvertisePeriod();

C interface:

unsigned short period = cc_mqttsn_gw_get_advertise_period(gw);

Gateway ID

The ADVERTISE message also contain 1 byte of numeric gateway ID. If the actual gateway ID differs from default value 0. It must be provided to the Gateway object.

C++ interface:

gw.setGatewayId(5); 

C interface:

cc_mqttsn_gw_set_id(gw, 5); 

It is also possible to retrieve the current configuration:

C++ interface:

std::uint8_t id = gw.getGatewayId();

C interface:

unsigned char id = cc_mqttsn_gw_get_id(gw);

Start Operation

After all the callbacks have been set and the advertise period was provided, the operation of the Gateway object needs to be properly started.

C++ interface:

if (!gw.start()) {
    ... // Something is not configured properly
} 

C interface:

if (!cc_mqttsn_gw_start(gw) {
    ... /* Something is not configured properly */
} 

If the start is successful, the Gateway object will immediatelly request to send new ADVERTISE message and will request a time measurement for the next time.

If the Gateway's operation needs to be paused for a while, use cc_mqttsn_gateway::Gateway::stop() or cc_mqttsn_gw_stop() functions. The operation can be resumed using cc_mqttsn_gateway::Gateway::start() or cc_mqttsn_gw_start() respectively.

C++ interface:

gw.stop(); 

C interface:

cc_mqttsn_gw_stop(gw);