Quick start

Create an IoT Core device registry

This page shows you how to use the ClearBlade IoT Core device registry, register a device, run a sample to connect a device and publish device telemetry events.

Activate ClearBlade IoT from the Google Cloud Marketplace

1. Navigate to the ClearBlade IoT Core offering in the Google Cloud Platform Marketplace.

2. Click Activate.

3. Complete the forms to register your IoT Core Developer account.

4. Click Complete.

Create a Google Cloud Service Account

A service account is required to migrate and run IoT Core. These instructions allow you to create a service account with the necessary permissions:

1. Select your desired project area.

2. Open the IAM & Admin Cloud services from the flyout menu.

image-20240130-213737.png

3. Select Service Accounts in the left menu.

4. Click CREATE SERVICE ACCOUNT from the top menu bar.

5. Complete the account details.

a. Service account name: ClearBlade IoT Core Service Account.

b. Account description: This account is used by ClearBlade IoT Core service to flow MQTT-based device message data into the Google Pub/Sub offering. It integrates with Cloud Logging and Cloud Monitoring services.

6. Click CREATE AND CONTINUE.

7. Grant these roles to the service account:

a. Cloud IoT Viewer: This role is needed to migrate IoT Core registries only. It can be removed once a migration is completed.

b. Pub/Sub Editor:

i. This role is needed to allow ClearBlade IoT Core to publish messages into Google Cloud Pub/Sub topics. This role is needed for normal operations.

ii. This role is needed to allow the ClearBlade IoT Core console to browse and create new topics in Google Pub/Sub to send events and status updates. This role is needed for normal operations.

c. Logs Writer: This role is required for ClearBlade IoT Core to send data directly into the Google Cloud Logging service. This role is needed for normal operations.

d. Monitoring Metric Writer: This role is required for ClearBlade IoT Core to send metrics into the Google Cloud Monitoring service. This role is needed for normal operations.

e. Monitoring Viewer: This role is required for ClearBlade IoT Core to view metrics in the Google Cloud Monitoring service. This role is needed for normal operations.

8. Click CONTINUE.

9. Leave the grant users access to the service account field blank.

10. Click DONE to complete the service account creation.

11. Select the newly created account by clicking the email hyperlink.

12. On the Service Account page, select KEYS from the top button bar.

13. Click ADD KEY → Create new key.

14. Choose JSON as the key type and click CREATE.

15. A new .json key file is downloaded to your device.

Create a project

1. Go to the ClearBlade IoT Core console.

2. Click the dropdown next to the IoT Core logo on the top left of the screen.

3. Click the Create Project button.

Create a device registry

1. Go to the ClearBlade IoT Core console.

2. Click Add registry.

3. Choose Create.

4. Enter my-registry for the Registry ID.

5. If you're in the US, select us-central1 for the Region. If you're outside the US, select your preferred region.

6. Use the Pub/Sub service to create new Pub/Sub topics.

7. Click Create on the ClearBlade IoT Core page.

Create your credentials

Generate a device key pair

Open a terminal window and run this multi-line command to create an RS256 key:

Linux

openssl req -x509 -newkey rsa:2048 -keyout rsa_private.pem -nodes \ -out rsa_cert.pem -subj "/CN=unused"

Windows

openssl req -x509 -newkey rsa:2048 -keyout rsa_private.pem -nodes \ -out rsa_cert.pem -subj "//CN=unused"

Download root credentials

Download Google's CA root certificate and note the location where you downloaded it. You'll need the file path when you run the Node.js command below.

In the following section, you'll add a device to the registry and associate the public key with the device.

Add a device to the registry

1. On the Registries page, select my-registry.

2. Select the Devices tab and click Create a device.

3. Enter my-device for the Device ID.

4. Leave the Device metadata field blank.

5. Click the Communication, Logging, Authentication dropdown.

6. Select Allow for Device communication.

7. Add the public key information to the Authentication fields.

  • Copy the rsa_cert.pem contents to the clipboard. Include the lines that say -----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----.

  • Select RS256_X509 for the Public key format.

  • Paste the public key in the Public key value box.

8. Click Submit.

The RS256_X509 key appears on your device’s details page.

Run a Node.js sample to connect a virtual device and view telemetry

1. Get the ClearBlade IoT Core Node.js samples from GitHub. The ClearBlade IoT Core samples are in the iot directory.

git clone https://github.com/clearblade/nodejs-iot.git

2. In your cloned repository, navigate to the samples/mqtt_example directory.

cd nodejs-iot/samples/mqtt_example

3. Copy the private key you created in the previous section (rsa_private.pem) to this directory (samples/mqtt_example):

cp ../../../rsa_private.pem

4. Install the Node.js dependencies:

npm install

5. Run this command to create a subscription to the registry's Pub/Sub topic, substituting your project ID:

gcloud pubsub subscriptions create \ projects/PROJECT_ID/subscriptions/my-subscription \ --topic=projects/PROJECT_ID/topics/my-device-events

6. Run this command to connect a virtual device to ClearBlade IoT Core using the MQTT bridge, substituting your project ID. Ensure serverCertFile is set to the location where you downloaded Google's root certificate.

node cloudiot_mqtt_example_nodejs.js \ mqttDeviceDemo \ --mqttBridgeHostname=MQTT_HOSTNAME\ --projectId=PROJECT_ID \ --cloudRegion=REGION \ --registryId=my-registry \ --deviceId=my-device \ --privateKeyFile=rsa_private.pem \ --serverCertFile=roots.pem \ --numMessages=25 \ --algorithm=RS256

The output shows that the sample device publishes messages to the telemetry topic. Twenty-five messages are published.

If you're using a Compute Engine VM or Cloud Shell, set the --mqttBridgePort flag to 443 when you run the device code. Please see this page for your hostname.

7. Run this command to read the messages published to the telemetry topic, substituting your project ID:

gcloud pubsub subscriptions pull --auto-ack \ projects/PROJECT_ID/subscriptions/my-subscription

8. Repeat the subscriptions pull command to view additional messages.

Clean up

Follow these steps to avoid incurring charges to your Google Cloud account for the resources used on this page.

1. Go to the Google Cloud Pub/Sub Topics page in the Google Cloud console.

2. Select the checkbox next to your topic in the list, then click Delete at the top of the page.

3. Go to ClearBlade IoT Core.

4. Select your project and go to the ClearBlade IoT Core console’s Registries page.

5. Click your registry’s name in the list.

6. Click your device’s name in the list.

7. At the top of the Device details page, click Delete. To delete a registry, you must first delete all its devices. If you've added any other devices to this registry, delete those too.

8. Go to the ClearBlade IoT Core console’s Registries page.

9. Click your registry’s name in the list.

10. At the top of the Registry details page, click Delete.