TUTORIALS GRPC GATEWAY

Working with gRPC Client

For creating grpc-client you need to generate a code for your language from proto files, which are stored at plgd hub. The plgd gRPC Gateway uses TLS. The client needs to have therefore properly configured TLS. Here is a simple example how to create a secured gRPC client communicating with the plgd gRPC Gateway.

import (
    "google.golang.org/grpc"
    "google.golang.org/grpc/credentials"
    "github.com/plgd-dev/hub/v2/grpc-gateway/pb"
    "github.com/plgd-dev/hub/v2/grpc-gateway/client"
)

    ...
    // Create TLS connection to the grpc-gateway.
    gwConn, err := grpc.Dial(
        address,
        grpc.WithTransportCredentials(credentials.NewTLS(tlsConfig)),
    )
    if err != nil {
        panic("cannot connect to grpc-gateway: " + err.Error())
    }
    // Create basic client which was generated from proto files.
    basicClient := pb.NewGrpcGatewayClient(gwConn)

    // Create Extended client which provide us more friendly functions.
    extendedClient := client.NewClient(basicClient)
    ...

Using extended gRPC Client

More info in doc.

API

All requests to the service must contain a valid access token in the grpc metadata.

Get Devices

The GetDevices command supports various filter options. If all of them are unset, all devices of a user identified by the access token are returned.

Example usages of filter options:

  • to retrieve certain devices use GetDevicesRequest.device_id_filter where ids of these devices need to be set
  • to retrieve all offline devices set GetDevicesRequest.status_filter to OFFLINE
  • to retrieve all devices of certain types use GetDevicesRequest.type_filter (e.g. x.com.plgd.light)

To return only ONLINE devices with ids deviceID1 and deviceID2, the following options shall be set: GetDevicesRequest.device_id_filter("[deviceID1, deviceID2]") && GetDevicesRequest.status_filter([ONLINE]).

The GetResourceLinks command supports various filter options. If all of them are unset, all links of all devices user is authorized to use are returned.

Example usages of filter options:

  • to retrieve links of certain devices use GetResourceLinksRequest.device_id_filter where ids of these devices needs to be set
  • to retrieve links of certain types use GetResourceLinksRequest.type_filter (e.g. oic.r.switch.binary)

To return only binary switches resources hosted by devices with ids deviceID1 and deviceID2, the following options shall be set: GetResourceLinksRequest.device_id_filter("[deviceID1, deviceID2]") && GetResourceLinksRequest.type_filter([oic.r.switch.binary]).

Get Resource Content

The GetResources command supports various filter options. If all of them are unset, all resource contents (shadows) of all devices user is authorized to use are returned.

Example usages of filter options:

  • to retrieve of resources identified by their hrefs use GetResourcesRequest.resource_id_filter where combinations deviceID and href is required in format deviceID/href
  • to retrieve resource values of certain devices use GetResourcesRequest.device_id_filter where ids of these devices need to be set
  • to retrieve values from resources of a specific type use GetResourcesRequest.type_filter

To return values of binary switch resources hosted by devices with ids deviceID1 and deviceID2, following options shall be set: GetResources.device_id_filter("[deviceID1, deviceID2]") && GetResources.type_filter([oic.r.switch.binary]).

Subscribe to Events

The SubscribeToEvents command opens the stream, which content is driven by the control message.

To control the content of the stream, send a SubscribeToEvents message with the following options:

  • action.create_subscription.event_filter set to ONLINE to receive devices events which changed their status to ONLINE
  • action.create_subscription.{device_id_filter, event_filter} set to RESOURCE_PUBLISHED to receive device events
  • action.create_subscription.{resource_id_filter, event_filter} set to CONTENT_CHANGED to receive resource events
  • action.create_subscription without any set of filters will receive all devices events from the hub.

The first event returned after the successful subscription is of type OperationProcessed. Property OperationProcessed.error_status.code contains information if the subscription was successful. If it was successful, property subscriptionId is set. All events belonging to a single SubscribeToEvents request are then identified by this subscriptionId.

If the user loses a device (unregistered / no more shared with the user), the client receives an event SubscriptionCanceled with corresponding subscription_id.

Get Resource from Device

The GetResourceFromDevice retrieves resource content directly from the device - resource shadow value is not returned. To define the expiration of command, set GetResourceFromDeviceRequest.time_to_live in nanoseconds(minimal 100ms). If the pending event is expired GetResourceFromDevice.valid_until (Unix timestamp in nanoseconds, 0 means forever), the hub skips it and will be removed by creating a new snapshot event.

This command execution is “expensive” as it has to reach the real device while your client synchronously waits for a response.

Update Resource Content

The UpdateResource command requests resource updates on the device. To define the expiration of command, set UpdateResourceRequest.time_to_live in nanoseconds(minimal 100ms). If the pending event is expired ResourceUpdatePending.valid_until (Unix timestamp in nanoseconds, 0 means forever), the hub skips it and will be removed by creating a new snapshot event.

Create Resource

The Create Resource command requests the creation of a new resource on a specific collection on the device. To define the expiration of command, set CreateResourceRequest.time_to_live in nanoseconds(minimal 100ms). If the pending event is expired ResourceCreatePending.valid_until (Unix timestamp in nanoseconds, 0 means forever), the hub skips it and will be removed by creating a new snapshot event.

Delete Resource

The DeleteResource command requests the device to delete a specific resource. A confirmation message doesn’t mean that the resource was deleted. After successful deletion, the device unpublishes its resource. This information is propagated to the client in the form of a RESOURCE_UNPUBLISHED event. To define the expiration of command, set DeleteResourceRequest.time_to_live in nanoseconds(minimal 100ms). If the pending event is expired ResourceDeletePending.valid_until (Unix timestamp in nanoseconds, 0 means forever), the hub skips it and will be removed by creating a new snapshot event.

Get pending commands

The GetPendingCommands command supports various filter options. If all of them are unset, all pending commands of all devices the user is authorized to use are returned.

Example usages of filter options:

  • to retrieve pending commands of resources identified by their hrefs use GetPendingCommandsRequest.resource_id_filter where combinations deviceID and href is required in format deviceID/href
  • to retrieve pending commands of certain devices use GetPendingCommandsRequest.device_id_filter where ids of these devices need to be set
  • to retrieve pending commands of a specific type of resources use GetPendingCommandsRequest.type_filter
  • to retrieve pending commands of certain commands use GetPendingCommandsRequest.command_filter

To return certain pending commands of binary switch resources hosted by devices with ids deviceID1 and deviceID2, following options shall be set: GetPendingCommandsRequest.device_id_filter("[deviceID1, deviceID2]") && RetrievePendingCommandsRequest.type_filter([oic.r.switch.binary]).

Get devices metadata

The GetDevicesMetadata command supports various filter options. If all of them are unset, all metadata of all devices the user is authorized to use are returned. Metadata contains information about connection status(ONLINE/OFFLINE) and shadow synchronization(ENABLED, DISABLED)

Example usages of filter options:

  • to retrieve metadata of certain devices use GetDevicesMetadataRequest.device_id_filter where ids of these devices need to be set
  • to retrieve metadata a specific type of devices use GetDevicesMetadataRequest.type_filter

Update Device Metadata

The UpdateDeviceMetadata command requests enable/disable shadow synchronization on the device. To define the expiration of command, set UpdateDeviceMetadata.time_to_live in nanoseconds(minimal 100ms). If the pending event is expired DeviceMetadataUpdatePending.valid_until (Unix timestamp in nanoseconds, 0 means forever), the hub skips it and will be removed by creating a new snapshot event.

Get events

The GetEvents command returns events that occurred on a resource. The command supports several filtering options. If all of them are unset all events from resources belonging to given user devices are returned.

Example usages of filter options:

  • to retrieve events for all user resources that occurred after given time use GetEventsRequest.timestamp_filter and set it to Unix timestamp in nanoseconds that represents given time.
  • to retrieve events for resources from selected user device(s) after given time combine GetEventsRequest.device_id_filter and GetEventsRequest.timestamp_filter. To return events from devices with ids deviceID1 and deviceID2 that occurred after given time do the following steps. Set the device filter to GetEventsRequest.device_id_filter("[deviceID1, deviceID2]"), then transform the desired time into Unix timestamp in nanoseconds and set GetEventsRequest.timestamp_filter(timestamp).
  • to retrieve events for selected user resources after given time combine GetEventsRequest.resource_id_filter and GetEventsRequest.timestamp_filter. The required format for resource_id_filter of a given resource is deviceID/href, where deviceID is the id of the device by which the resource is hosted and href is the location of the resource on the host device. To return events from resources deviceID1/href1 and deviceID2/href2 set resource filter to GetEventsRequest.resource_id_filter("[deviceID1/href1, deviceID2/href2]").

Delete devices

The DeleteDevices command requests to delete entries of selected devices in the identity and events databases. The command supports filtering by setting deviceIdFilter value. A list of deleted device ids is returned in the response.

Example usages of filter options:

  • to delete entries for devices owned by the user with ids deviceID1 and deviceID2 use DeleteDevicesRequest.device_id_filter("[deviceID1, deviceID2]").
  • to delete entries for all devices owned by the user, use DeleteDevicesRequest with empty device_id_filter.

Cancel pending commands

Pending command of resource is identified by the correlationId. If a correlationIdFilter is not specified, all pending commands(Create, Get, Update, Delete) will be canceled.

Cancel pending metadata updates

Pending metadata update is identified by correlationId. If a correlationIdFilter is not specified, all pending metadata updates(Set shadow synchronization) will be canceled.

Contracts

“Working with gRPC Client” was last updated: January 17, 2022: update golang examples to github.com/plgd-dev/hub/v2 package (5605f1b)
Improve this page