UDMI / Docs / Tools / Registrar
The registrar
is a utility program that registers and updates devices in Cloud IoT.
Running bin/registrar
will validate local metadata and (optionally) register devices
in a cloud project.
See the setup docs for common setup required for running this tool.
The site model documentation covers the basic structure of the site-specific configuration. Ideally, this directory would be placed under source control as a site-specific repo.
_{site_path}_/devices/
.The expected model of a device is defined by a device metadata file,
along with a public key for that device (required for communication with the cloud).
Devices (that aren’t proxied by a gateway) that do not auto-generate a public key
can use the bin/keygen
utility to create a proper public/private key pair.
The registrar tool can be run locally to just validate the metadata, or with an optional
project_id
to specify a target GCP project. Additional command-line arguments can
be used to specific specific device(s) to register (rather than all).
Usage:
bin/registrar site_path [project_id] [options] [devices...]
bin/registrar config_file
config_file
: Path to a configuration file which contains configuration options;site_path
: The directory containing the site model, or a model-with-project file directly.project_id
: The project ID that contains the target registry. The project ID can be prepended with iot_provider:
//clearblade/PROJECT_ID
for a public ClearBlade project.//gbos/PROJECT_ID
for a Google operated ClearBlade project.options
: Various options to impact behavior:
-u
Update.-d
Delete all device in the site model from the registry (combine with -x
to delete all devices from the registry)-b
Block unknown devices.-x
Delete unknown devices from the registry.-n
Number of thread counts.devices
: Multiple device entries for limited registration. Can be just the device name
(AHU-12
), or path to device (site/devices/AHU-12
) for use with file-name glob.Examples:
bin/registrar sites/UK-LON-ABC //gbos/bos-platform-testing
bin/registrar sites/UK-LON-ABC/cloud_iot_config.json
Running the tool will create some output files for each device, and also a top-level
registration_summary.json
file with summary results. Detailed error reports (if any)
for individual devices will be in their respective device directories.
~/udmi$ cat test_site/cloud_iot_config.json { "cloud_region": "us-central1", "site_name": "ZZ-TRI-FECTA", "registry_id": "registrar_test" } ~/udmi$ bin/registrar test_site/ Building validator... Note: Some input files use or override a deprecated API. Note: Recompile with -Xlint:deprecation for details. Note: /home/user/udmi/validator/src/main/java/com/google/daq/mqtt/validator/Validator.java uses unchecked or unsafe operations. Note: Recompile with -Xlint:unchecked for details. Running tools version 1.0.0-2-ga413c4e Using gcloud auth: Your active configuration is: [udmi-test] user@google.com Using cloud project -- Using site config dir test_site/ Using schema root dir bin/../schema Using device filter java args -- test_site/ bin/../schema Reading Cloud IoT config from /home/user/udmi/test_site/cloud_iot_config.json Initializing with default credentials... Jul 30, 2020 4:02:12 PM com.google.auth.oauth2.DefaultCredentialsProvider warnAboutProblematicCredentials WARNING: Your application has authenticated using end user credentials from Google Cloud SDK. We recommend that most server applications use service accounts instead. If your application continues to use end user credentials from Cloud SDK, you might receive a "quota exceeded" or "API not enabled" error. For more information about service accounts, see https://cloud.google.com/docs/authentication/. Created service for project projects/--/locations/us-central1 Working with project -- registry us-central1/registrar_test Loading local device GAT-123 Loading local device AHU-22 Loading local device SNS-4 Loading local device AHU-1 Skipping remote registry fetch Processed 4 devices Removing test_site/devices/GAT-123/errors.map Removing test_site/devices/AHU-1/errors.map Removing test_site/devices/AHU-22/errors.map Removing test_site/devices/SNS-4/errors.map Summary: Device Clean: 4 Out of 4 total. Done with PubSubPusher Registrar complete, exit 0 ~/udmi$ cat test_site/registration_summary.json { "Clean" : { "AHU-1" : "True", "AHU-22" : "True", "GAT-123" : "True", "SNS-4" : "True" } }
Expected workflow to configure a registry using Registrar:
Device
: Target IoT DeviceLocal
: Local clone of site configuration repoRegistrar
: This utility programRegistry
: Target Cloud IoT Core registryRepo
: Remote site configuration repoAll operations are manual except those involving the Registrar
tool.
+---------+ +-------+ +-----------+ +-----------+ +-------+ | Device | | Local | | Registrar | | Registry | | Repo | +---------+ +-------+ +-----------+ +-----------+ +-------+ | | | | | | | | Pull repo locally | | |<--------------------------------------------------------------------| | | ---------------------\ | | | | | | Run Registrar tool |-| | | | | |--------------------| | | | | | | | | | | Read device configs | | | | |-------------------------->| | | | | | | | | | | Read device list | | | | |<----------------------------| | | | | | | | | Write auth keys | | | | |<--------------------------| | | | | | | | | | | Update device entries | | | | |---------------------------->| | | | ----------------------\ | | | | | | Registrar tool done |-| | | | | |---------------------| | | | | | | | | | Install private key | | | | |<------------------------| | | | | | | | | | | Push changes | | | | |-------------------------------------------------------------------->| | | | | |
Use with ASCII Sequence Diagram Creator
object Device Local Registrar Registry Repo Repo -> Local: Pull repo locally note left of Registrar: Run Registrar tool Local -> Registrar: Read device configs Registry -> Registrar: Read device list Registrar -> Local: Write auth keys Registrar -> Registry: Update device entries note left of Registrar: Registrar tool done Local -> Device: Install private key Local -> Repo: Push changes