Cloud IoT step-by-step: Quality of life tip - The command line
In this post, I want to cover a quality of life topic for working with Google Cloud Platform. I’ve mentioned in my previous posts, using the Google Cloud SDK on the command line as a way to quickly check out if your messages are correctly sending their telemetry to Pub/Sub from your device. For some of this work (most of it really), using the command line is faster than using the UI/console.
For this quickie, I just want to walk you through commands on the command line to do what we did in the previous two tutorials: Getting a device connected and sending telemetry, sending messages back down to your device, and deploying a Cloud Function.
If you’re totally comfortable with the UI, that’s fine too, that’s why we have both. But it’s generally faster to work with the command line, and all of the work you do on command line can be scripted so if you’re an automation loving sort of person, it’s good to know this stuff. Hopefully, by following on my previous tutorials this gives you a familiar context around what we’re going to do with the command line.
Table of Contents:
- Installing and configuring GCloud SDK
- Creating Pub/Sub and IoT Core objects in GCP
- Sending messages to you device and deploying Cloud Functions
Installing and configuring GCloud SDK
First step, is install the gcloud SDK. It requires Python, so if you don’t have Python yet, install that first. It also requires a Google Cloud Project, so if you haven’t got one, set one up. Don’t need to do anything beyond just creating the project. Then follow the instructions here for installation. The last step asks you to run
gcloud init and kind of leaves you to handle that. Real quick, the options it’ll ask you:
Pick a configuration to use. If you’ve never done this before, this may not appear, it may just drop you into creating a new configuration.
Choose account to perform operations. Pick the email associated with the Google Cloud Platform account/project you created. This step may pop out to a browser window to ask you to log in to that account if you haven’t logged in lately. Otherwise you should see a message that says
You are logged in as: [email].
- The next message kind of depends on how much you use GCP. It might be
This account has lots of projects! Listing them all can take a while. In which the options will be to enter the project ID (you can get this from the console), create a new project, or list them all. Otherwise, you should just see the projects you own listed. Pick the one you created. As you noticed, you can also create a project from here, but I find it’s still useful to have the project open in the console anyway.
Do you want to configure a default Compute Region and Zone?I do because I don’t do multi-zone in my projects generally, and it cuts down on flags needed to run things. Hitting
Yspits out all the regions. Pick one closest to where you are. Generally, which sub-area doesn’t matter. So, e.g.
us-central1-awill, for all intents and purposes be the same as
us-central1-bfor this. For production you’d want to be a bit more careful about using a default region, but for this it’s fine. NOTE: Not all regions support all Cloud products, so you may find the region you picked won’t work for IoT stuff. For example, the only valid regions for IoT Core (currently) are
After picking (or not) your default region you should see a bunch of output that ends with
Some things to try next and some things to try. Just to confirm it all installed properly, run
gcloud --version and you should see included in the output
Google Cloud SDK nnn.n.n along with a bunch of other stuff. If you don’t see that, something didn’t install properly, be sure you have permissions to install things on your machine.
Now we’re ready to go! At any point, if you want to explore a bit, you can always pass the
--help flag to see what groups or commands are available.
Creating Pub/Sub and IoT Core objects in GCP
From my first IoT tutorial, we got a device from nothing to talking to the internet. Going over the command line commands you need in order to setup and test:
- Create a Pub/Sub topic for our telemetry data.
gcloud pubsub topics create telemetry-topic
- Create a Pub/Sub subscription so we can confirm telemetry getting written to our topic.
gcloud pubsub subscriptions create telemetry-subscription —-topic=telemetry-topic
- Create an IoT Core registry to hold your devices
gcloud iot registries create device-registry —-region=us-central1 —-event-notification-config=topic=telemetry-topic
- Create your IoT device itself (need openSSL installed)
openssl req -x509 -newkey rsa:2048 -keyout demo_private.pem -nodes -out demo.pub -subj “/CN=unused”
gcloud iot devices create device-first --region=us-central1 --registry=device-registry --public-key=path=./demo.pub,type=rsa-x509-pem
- Publishing a test message to a Pub/Sub topic
gcloud pubsub topics publish telemetry-topic --message=red
- Reading messages published to a Pub/Sub subscription
gcloud pubsub subscriptions pull --auto-ack telemetry-subscription
And you’re all set! The first four sections replace all the Cloud Project setup pieces from my first tutorial. I added the last two for Pub/Sub interaction because they’re really helpful for testing any downstream stuff you have in place without needing to turn your devices on and off.
Don’t forget, you still need to put the
demo_private.pem and fetch the
roots.pem from Google and get those two on the device to actually have anything actually working from the device.
Sending messages to your device and deploying Cloud Functions
For the second tutorial, we did a few things from the console that we could just as (or more) easily do from command line.
- Send a config message to a specific device
gcloud iot devices configs update --config-data=”red” --device=device-first --region=us-central1 --registry=device-registry
- Send a command to a specific device
gcloud iot devices commands send — command-data=”red” --device=device-first --region=us-central1 --registry=device-registry
Note about this, if the device is offline, or if online but not subscribed to the command MQTT topic (
/devices/device-first/commands/#) then you’ll get an error message (doesn’t hurt anything, it’s just letting you know it didn’t get to the device). You won’t get an error with the config message because configs are stored, and sent to the device when it connects to IoT Core.
- Deploy a Google Cloud Function. In the directory where you’ve created the package.json and the index.js:
gcloud functions deploy test-function --region=us-central1 --entry-point=updateDevice --trigger-http
Now there’s a LOT to unpack here. Topic for another blog post. This just executes what we did in the tutorial in the console, but from the command line.
- Call a Cloud Function
Technically we didn’t do this, because we’re using an HTTP function you can just open the target URL for it. But if you WANTED to, you could do…
gcloud functions call test-function --region=us-central1
Be aware that depending on what your function does, it may crash or do unexpected things because of what it expects as the input. Calling functions from the command line assume that you’re sending the data in the body of the request. For example, the one we wrote in my second blog uses GET variables instead, which you can’t do from command line.
So there we have it! Getting familiar with the command line will speed up development in particular. Being able to pop up a new device to test something clean, or push up a new version of the Cloud Function (in particular keeping your local disk version in sync with whatever you have in the console UI) is hugely valuable.
Obviously as I’ve mentioned previously, there’s a lot more, I’ve just listed out what we’ve done in the previous tutorials but using command line. In future tutorials I’ll try to call out when there’s an easy command line to whatever I’m talking about deploying or calling.
One last note, is if you start to get comfy on command line, but hate doing the init thing over and over, you can also use the Cloud Shell. In the console, upper right, look for the Cloud Shell icon (it’s the icon on the left). It opens a shell in the console that’s pre-configured to the environment of your project. VERY handy. There’s a whole post’s worth of stuff on that as well, and as luck would have it, you can find it here, written by my teammate.
Let me know what you think of these tutorials, and what you’d like to see next, either in a comment below, or follow me on Twitter. My DMs are open!