User Tools

Site Tools


resource_directory_-_programming_guide

Resource Directory - Programming Guide

The Resource Directory is a directory like service which hold the information about the published resources in the network. Any device can act as a resource directory server but it is not intended for constrained device.

Resource directory responds on behalf of the device that has published resource for /oic/res multicast request.

The aim of the resource directory:

  • In local scenario, is to facilitate the low end device to not respond to multicast response and only respond to the unicast response from the device.
  • In remote scenario, it helps the publishing device to publish local resource to the cloud. The resource directory functionality is in the cloud and the client is on the rich device.

There are two components of the resource directory

  1. Resource Directory Server:
    1. Receives published resource
    2. Respond to the search query for the resource directory
    3. Handle update and delete for the published resources.
    4. Handle /oic/res request for the resource that are published in the network.
  2. Resource Directory Client:
    1. Publish resource to resource directory server.
    2. Other device find about device resource via resource directory server.
    3. Once resource is published it does not participate in a multicast request and response.
    4. Device keep updating resource directory server to allow it to continue holding resource information.

Other device in the network does not know about the resource directory. Only thing that changes is device receiving response will use base uri (buri) in the link payload instead of assuming the direct response from the device responding.

The aim of this page is to help get started with resource directory build and running samples.

Build Resource Directory

Resource Directory Server

To build a resource directory server

scons RD_MODE=SERVER

This will compile the resource directory server and creates a resource directory server.

Resource directory server uses sqlite to maintain the published resource.

Resource Directory Client

By default all iotivity build Resource directory client. This option is enabled in all build currently. The below create resource directory client.

scons RD_MODE=CLIENT

This option is enabled by default to enable publishing the resource to the cloud.

Resource Directory Client & Server

To compile both RD server and client, an option all can be used.

scons RD_MODE=all

Run Examples

As part of the above flag, sample code are created in samples directory. The sample code is located in resource/csdk/resource-directory/samples/.

Start RD Server

Start RD Server via calling the rd_server.

cd out/linux/x86_64/debug/resource/csdk/resource-directory/samples
./rd_server 

Start RD Client

After RD server is started (it is required if testing in local scenario.)

cd out/linux/x86_64/debug/resource/csdk/resource-directory/samples
./rd_publishingClient

Use option 1 to first discover local resource directory server. Use option 2, to publish resource. (As part of the client, it creates 2 resource which are then published to the resource directory server.)

Start IoTivity Client

Start any iotivity client, to find the resource published by the resource directory client to the resource directory server. The response will come via resource directory server and not by the publishing device directly.

cd out/linux/x86_64/debug/resource/csdk/resource-directory/samples
./rd_queryClient

rd_queryClient can use baseuri address to communicate with the publishing device directly. From here on the communication with the actual device is as usual.

Resource Directory API

Resource Directory Server API

To create a resource directory server there is an API to start and stop resource directory server.

  1. To create a resource directory resource. This resource is then discoverable to all device in the local network.
/**
* This function creates resource /oic/rd.
*
* @return ::OC_STACK_OK upon success, ::OC_STACK_ERROR in case of error.
*/
OCStackResult OCRDStart();
  1. To delete the resource directory resource OCStop can be called. This can be called if device does not want to be a resource directory server anymore or at time of shutdown.
/**
* Stops resource directory.
* This function will stop the resource directory and removes all published
* resources information.
*
* @return ::OC_STACK_OK upon success, ::OC_STACK_ERROR is returned except
* the case that OC_STACK_SUCCESS is returned.
*/
OCStackResult OCRDStop();

Resource Directory Client API

A Client will use resource directory service to publish its resource to be discoverable in the user network.

  1. Resource directory discovery (Local RD): A RD in the network shall support RD discovery, shall provide the facility to allow devices to publish their resource information to a RD.
  2. Resource publishing (Local RD, Cloud RD)
  3. Delete resource information (Local RD, Cloud RD)

C API

/**
 * Discover Local RD across the network.
 *
 * @param connectivityType Type of connectivity indicating the interface.
 * @param cbBiasFactor Asynchronous callback function that is invoked by the stack when
 *                     response is received. The callback is generated for each response
 *                     received.
 * @param qos Quality of service.
 *
 * @return ::OC_STACK_OK on success, some other value upon failure.
 */
OCStackResult OCRDDiscover(OCConnectivityType connectivityType, OCCallbackData *cbBiasFactor,
                           OCQualityOfService qos);
/**
 * Publish RD resource to Resource Directory.
 *
 * @param host The address of the RD.
 * @param connectivityType Type of connectivity indicating the interface.
 * @param resourceHandles This is the resource handle which we need to register to RD.
 * @param nHandles The counts of resource handle.
 * @param cbData Asynchronous callback function that is invoked by the stack when
 *               response is received. The callback is generated for each response
 *               received.
 * @param qos Quality of service.
 *
 * @return ::OC_STACK_OK on success, some other value upon failure.
 */
OCStackResult OCRDPublish(const char *host, OCConnectivityType connectivityType,
                          OCResourceHandle *resourceHandles, uint8_t nHandles,
                          OCCallbackData *cbData, OCQualityOfService qos);
/**
 * Delete RD resource from Resource Directory.
 *
 * @param host The address of the RD.
 * @param connectivityType Type of connectivity indicating the interface.
 * @param resourceHandles This is the resource handle which we need to delete to RD.
 * @param nHandles The counts of resource handle.
 * @param cbData Asynchronous callback function that is invoked by the stack when
 *               response is received. The callback is generated for each response
 *               received.
 * @param qos Quality of service.
 *
 * @return ::OC_STACK_OK on success, some other value upon failure.
 */
OCStackResult OCRDDelete(const char *host, OCConnectivityType connectivityType,
                         OCResourceHandle *resourceHandles, uint8_t nHandles,
                         OCCallbackData *cbData, OCQualityOfService qos);

C++ API

/**
* API for Resource Publish to Resource Directory.
* @note This API applies to resource server side only.
*
* @param host Host IP Address of a service to direct resource publish query.
* @param connectivityType ::OCConnectivityType type of connectivity.
* @param resourceHandle resource handle of the resource.
* @param callback Handles callbacks, success states and failure states.
*
* @return Returns ::OC_STACK_OK if success.
*/
OCStackResult publishResourceToRD(const std::string& host,
                                  OCConnectivityType connectivityType,
                                  ResourceHandles& resourceHandles,
                                  PublishResourceCallback callback);
/**
* API for published resource delete from Resource Directory.
* @note This API applies to resource server side only.
*
* @param host Host IP Address of a service to direct resource delete query.
* @param connectivityType ::OCConnectivityType type of connectivity.
* @param resourceHandle resource handle of the resource.
* @param callback function to callback with published resources.
* @see publishResourceToRD(const std::string&, OCConnectivityType, OCResourceHandle,
* uint8_t, PublishResourceCallback)
*/
OCStackResult deleteResourceFromRD(const std::string& host,
                                   OCConnectivityType connectivityType,
                                   ResourceHandles& resourceHandles,
                                   DeleteResourceCallback callback);

C++ Sample

ResourceHandles m_publishedResourceHandles;
OCConnectivityType connectivityType = CT_ADAPTER_TCP;

// 1. Create resource.
OCPlatform::registerResource(m_resourceHandle, "/a/liht", "core.light",
                             DEFAULT_INTERFACE,
                             nullptr,
                             OC_DISCOVERABLE);

// 2. Add resource handle.
m_publishedResourceHandles.push_back(m_resourceHandle);

// 3.  Publish Resource of Resource-Server to RD.
void onPublish(const OCRepresentation& rep, const int& eCode)
{
    cout << endl <<"Received Publish Resource Response From RD\n";
}

OCStackResult result = OCPlatform::publishResourceToRD("coap+tcp:10.11.12.13:5683", 
                                                       connectivityType,
                                                       m_publishedResourceHandles,
                                                       &onPublish);
                                                       
// 4.  Delete Resource with Resource Handle.
void onDelete(const int& eCode)
{
    cout << "Received Delete Resource Response From RD\n";
}

/*
* Don't need to include resource handle,
* if resource-server want to delete all resources from RD.
* Ex.) OCPlatform::deleteResourceFromRD(rdAddress, connectivityType, &onDelete);
*/
OCStackResult result = OCPlatform::deleteResourceFromRD("coap+tcp:10.11.12.13:5683",
                                                        connectivityType,
                                                        m_publishedResourceHandles,
                                                        &onDelete);
resource_directory_-_programming_guide.txt · Last modified: 2017/01/03 01:53 by Phil Coval