Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 17 Next »

This documentation is still in development - use at your own risk

Creating or editing a gateway

After you create a gateway, you can't change it to a non-gateway device. Ensure you've created a registry and a device key pair before completing the steps in this section.

Console

To create a new gateway:

  1. Go to the Registries page in the Google Cloud console.

    Click the ID of the registry for the gateway.

  2. On the Registry details page, click Gateways and Add gateway to create a new gateway.

  3. Enter a Gateway ID that briefly describes the gateway and helps you identify it (this field can't be edited later).

  4. For Gateway communication, select Allow or Block. The latter allows you to block communication when needed, such as when a gateway or one or more devices bound to it are not functioning properly. You’ll most likely want to allow communication when first creating the gateway. When a gateway is blocked, all devices bound to it are blocked from communicating with ClearBlade IoT Core.

  5. Select the Public key format that matches the key pair for this gateway. Paste the certificate or key in the Public key value field. You can also set an expiration date for the key.

  6. Select the authentication method to use for devices bound to the gateway.

  7. Use the Key and Value fields to add optional gateway metadata, such as a serial number.

  8. Under Stackdriver Logging, select an activity log level for the gateway. The gateway's log level overrides its registry's log level.

  9. Click Create to create the gateway or Update to save changes to an existing gateway.

To edit an existing gateway:

  1. Go to the Registries page.

  2. Click the ID of the registry for the gateway.

  3. Click Registry details.

  4. Click Gateways.

  5. Click the ID of the gateway you want to edit.

  6. Click Edit at the top of the page.

To add a key to an existing gateway, click Add public key on the Device details page.

API

Use the following methods to create or edit a gateway:

  • Device create method to add gateways to registries

  • Device patch method to edit existing gateways

Creating or editing a gateway code samples

Node.js
// const cloudRegion = 'us-central1';
// const deviceId = 'my-unauth-device';
// const gatewayId = 'my-gateway';
// const projectId = 'adjective-noun-123';
// const registryId = 'my-registry';
// const gatewayAuthMethod = 'ASSOCIATION_ONLY';
import { DeviceManagerClient } from '@clearblade/iot';

const iotClient = new DeviceManagerClient({
  // optional auth parameters.
});

async function createDevice() {
  // Construct request
  const regPath = iotClient.registryPath(projectId, cloudRegion, registryId);

  console.log('Creating gateway:', gatewayId);

  let credentials = [];

  // if public key format and path are specified, use those
  if (publicKeyFormat && publicKeyFile) {
    credentials = [
      {
        publicKey: {
          format: publicKeyFormat,
          key: readFileSync(publicKeyFile).toString()
        }
      }
    ];
  }

  const device = {
    id: gatewayId,
    credentials: credentials,
    gatewayConfig: {
      gatewayType: 'GATEWAY',
      gatewayAuthMethod: gatewayAuthMethod
    }
  };

  const request = {
    parent: regPath,
    device
  };

  const [response] = await iotClient.createDevice(request);
  console.log('Created device:', response);
}

createDevice();

C#
{
    logger.LogInformation("Create a new gateway");

    string id = "Sample-New-Gateway";
    string name = "projects/developmentenv/locations/us-central1/registries/Sample-New-Registry/Devices/Sample-New-Gateway";

    String keyText = File.ReadAllText("path/to/key");

    var credentials = new List<DeviceCredential>
    {
        new DeviceCredential()
        {
            PublicKey = new PublicKeyCredential()
            {
                Key = keyText,
                Format = "ES256_PEM"
            },
        }
    };

    var gatewayConfig = new GatewayConfig()
    {
        GatewayType = "GATEWAY",
        GatewayAuthMethod = "ASSOCIATION_ONLY"
    };

    var result = await mClient.CreateDevice(4, id, name, credentials, gatewayConfig);
    if (!result.Item1 || (result.Item2 == null))
        logger.LogError("Failed to create new device");
    else
    {
        logger.LogInformation("Successfully created new device");

        // The result.Item2 object can be used to refer to newly created device
    }
}

See Creating or editing a device to learn how to create the devices you'll use with the gateway.

Configuring the gateway and getting state

With ClearBlade IoT Core, you can control a gateway by modifying its configuration, like any other device. See Configuring Devices to learn how to configure a gateway over the MQTT or HTTP bridge.

After a configuration has been applied to a gateway, the gateway can report its state to ClearBlade IoT Core. You can compare the gateway's state and its most recent configuration to ensure it’s functioning properly.

Binding or unbinding a device

You can authenticate non-gateway devices to ClearBlade IoT Core by binding them to the gateway. Binding creates an association between the devices and the gateway that ClearBlade IoT Core checks to authenticate the devices.

Note: Binding is required when using the HTTP bridge.

Console

  1. Go to the Registries page.

  2. Click the ID of the registry for the gateway.

  3. Click Gateways, then click the gateway's ID.

  4. On the Gateway details page, click Bound devices.

  5. Click Bind device.

  6. Select the devices you want to bind to the gateway, then click Bind.

  7. To unbind a device, select the device in the Gateway details page, click Unbind device and Unbind to confirm.

API

Use the following methods to bind a device to or unbind a device from a gateway:

Binding a device to or unbinding a device from a gateway code samples

Node.js
// const cloudRegion = 'us-central1';
// const deviceId = 'my-unauth-device';
// const gatewayId = 'my-gateway';
// const projectId = 'adjective-noun-123';
// const registryId = 'my-registry';
import { DeviceManagerClient } from '@clearblade/iot';

const iotClient = new DeviceManagerClient({
  // optional auth parameters.
});

async function bindDeviceToGateway() {
  // Construct request
  const regPath = iotClient.registryPath(projectId, cloudRegion, registryId);

  const bindRequest = {
    parent: regPath,
    deviceId: deviceId,
    gatewayId: gatewayId
  };

  console.log(`Binding device: ${deviceId}`);

  await iotClient.bindDeviceToGateway(bindRequest);

  console.log(`Bound ${deviceId} to`, gatewayId);
}

bindDeviceToGateway();

C#
if (bBindUnBindDevice)
{
    logger.LogInformation("Get configuration of a device");

    // While running this sample, it is assumed that, device with name
    // "Sample-New-Device" exists and Gateway with name "TestGateway" exists
    // "Sample-New-Registry" is the registry name

    // Sample - Bind Device
    var result = await mClient.BindDeviceToGateway(4, "projects/developmentenv/locations/us-central1/registries/Sample-New-Registry", "TestGateway", "Sample-New-Device");
    if (!result)
    {
        logger.LogError("Failed To Bind Device");
    }
    else
    {
        // Actual test - UnBind Device
        result = await mClient.UnBindDeviceFromGateway(4, "projects/developmentenv/locations/us-central1/registries/Sample-New-Registry", "TestGateway", "Sample-New-Device");
        if (!result)
            logger.LogError("Failed to unbind a device");
        else
            logger.LogInformation("Successfully bind device");

    }
}

Listing all devices bound to a gateway

Console

  1. Go to the Registries page.

    Click the ID of the registry for the gateway.

  2. Click Gateways, then click the gateway's ID.

  3. On the Gateway details page, click Bound devices.

API

Use the Devices list method and specify a gateway ID to list all devices bound to the gateway.

Listing all devices bound to the gateway code samples

Node.js
// const cloudRegion = 'us-central1';
// const gatewayId = 'my-gateway';
// const projectId = 'adjective-noun-123';
// const registryId = 'my-registry';
import { DeviceManagerClient } from '@clearblade/iot';
const iotClient = new DeviceManagerClient({
  // optional auth parameters.
});

async function listDevices() {
  // Construct request
  const parentName = iotClient.registryPath(projectId, cloudRegion, registryId);
  const [response] = await iotClient.listDevices({
    parent: parentName,
    gatewayListOptions: { associationsGatewayId: gatewayId }
  });
  const devices = response;

  if (devices.length > 0) {
    console.log('Current devices bound to gateway: ', gatewayId);
  } else {
    console.log('No devices bound to this gateway.');
  }

  for (let i = 0; i < devices.length; i++) {
    const device = devices[i];
    console.log(`\tDevice: ${device.numId}: ${device.id}`);
  }
}

listDevices();

C#
{
    logger.LogInformation("Obtain list of devices for a particular registry and gateway");

    // While running this sample, it is assumed that, gateway with name
    // "associated-gateway" exists

    GatewayListOptionsModel gatewayListOptions = new GatewayListOptionsModel()
    {
        AssociationsGatewayId = "associated-gateway",
    };
    var result = await mClient.GetDevicesList(4, "projects/developmentenv/locations/us-central1/registries/Sample-New-Registry", gatewayListOptions);
    if (!result.Item1)
        logger.LogError("Failed to get list of devices");
    else
    {
        logger.LogInformation("Succeeded in getting the list of Devices");

        // Use the list
    }
}

Listing all gateways in a registry

Console

  1. Go to the Registries page.

  2. Click the ID of the registry for the gateway.

  3. On the Registry details page, click Gateways to see a list of all gateways in that registry.

API

Use the Device list method to list all gateways in a registry.

Listing all gateways in a registry code samples

Node.js
// const cloudRegion = 'us-central1';
// const projectId = 'adjective-noun-123';
// const registryId = 'my-registry';
import { DeviceManagerClient } from '@clearblade/iot';
const iotClient = new DeviceManagerClient({
  // optional auth parameters.
});

async function listDevices() {
  // Construct request
  const registryPath = iotClient.registryPath(projectId, cloudRegion, registryId);

  console.log('Current gateways in registry:');
  const [response] = await iotClient.listDevices({
    parent: registryPath,
    fieldMask: { paths: ['config', 'gateway_config'] },
    gatewayListOptions: {
      gatewayType: 'GATEWAY'
    }
  });
  const devices = response;

  devices.forEach((device) => {
    console.log('----\n', device);
  });
}

listDevices();

C#
{
    logger.LogInformation("Obtain list of gateways in a registry");

    GatewayListOptionsModel gatewayListOptions = new GatewayListOptionsModel()
    {
        GatewayType = core.Enums.GatewayTypeEnum.GATEWAY,
    };

    var result = await mClient.GetDevicesList(4, "projects/developmentenv/locations/us-central1/registries/Sample-New-Registry", gatewayListOptions);
    if (!result.Item1)
        logger.LogError("Failed to get list of devices");
    else
    {
        logger.LogInformation("Succeeded in getting the list of gateways");

        // Use the list
    }
}

Deleting devices bound to a gateway

To delete a device bound to a gateway, you first unbind the device from all gateways it's bound to, then delete it from the registry.

Console

  1. Unbind the device from every gateway it's bound to.

  2. In the Device details page, click Delete.

  3. Enter the device ID to confirm and click Delete.

API

After unbinding the device from all gateways it's bound to, use the Device delete method to delete the device.

Deleting a device bound to a gateway code samples

Node.js
// const cloudRegion = 'us-central1';
// const projectId = 'adjective-noun-123';
// const registryId = 'my-registry';
import { DeviceManagerClient } from '@clearblade/iot';

const iotClient = new DeviceManagerClient({
  // optional auth parameters.
});

async function deleteDevice() {
  // Construct request
  const devPath = iotClient.devicePath(projectId, cloudRegion, registryId, deviceId);

  const [responses] = await iotClient.deleteDevice({ name: devPath });
  console.log('Successfully deleted device', responses);
}

deleteDevice();

C#
{
    logger.LogInformation("Unbind the device");

    var unbindResult = await mClient.UnBindDeviceFromGateway(4, "projects/developmentenv/locations/us-central1/registries/Sample-New-Registry", "TestGateway", "Sample-New-Device");
    if (!unbindResult)
        logger.LogError("Failed to unbind a device");
    else
        logger.LogInformation("Successfully unbind device");

    logger.LogInformation("Delete the device");

    string id = "Sample-New-Device";
    string name = "projects/developmentenv/locations/us-central1/registries/Sample-New-Registry/Devices/Sample-New-Device";

    var deleteResult = await mClient.DeleteDevice(4, id, name);
    if (!deleteResult.Item1 || (deleteResult.Item2 == null))
        logger.LogError("Failed to delete device");
    else
    {
        logger.LogInformation("Successfully deleted the device");
    }
}

Deleting a gateway

To delete a gateway, you first unbind its devices and then delete the gateway from the registry.

Console

  1. Unbind all devices from the gateway.

  2. Go back to the Gateway details page and click Delete.

  3. Enter the gateway's name to confirm, then click Delete.

API

After unbinding all devices from the gateway, use the Device delete method to delete the gateway, specifying the ID of the gateway you want to delete.

Delete a gateway code samples

Node.js
// const cloudRegion = 'us-central1';
// const projectId = 'adjective-noun-123';
// const registryId = 'my-registry';
import { DeviceManagerClient } from '@clearblade/iot';

const iotClient = new DeviceManagerClient({
  // optional auth parameters.
});

async function deleteDevice() {
  // Construct request
  const devPath = iotClient.devicePath(projectId, cloudRegion, registryId, deviceId);

  const [responses] = await iotClient.deleteDevice({ name: devPath });
  console.log('Successfully deleted device', responses);
}

deleteDevice();

C#
{
    logger.LogInformation("Unbind the device");

    var unbindResult = await mClient.UnBindDeviceFromGateway(4, "projects/developmentenv/locations/us-central1/registries/Sample-New-Registry", "TestGateway", "Sample-New-Device");
    if (!unbindResult)
        logger.LogError("Failed to unbind a device");
    else
        logger.LogInformation("Successfully unbind device");

    logger.LogInformation("Delete the device");

    string id = "Sample-New-Device";
    string name = "projects/developmentenv/locations/us-central1/registries/Sample-New-Registry/Devices/Sample-New-Device";

    var deleteResult = await mClient.DeleteDevice(4, id, name);
    if (!deleteResult.Item1 || (deleteResult.Item2 == null))
        logger.LogError("Failed to delete device");
    else
    {
        logger.LogInformation("Successfully deleted the device");
    }
}

What's next

  • Use the MQTT or HTTP bridge to relay messages and configuration data between the devices and ClearBlade IoT Core.

  • No labels