Documentation update and add spell checker (#578)

.gencode_hash.txt

@@ -1,17 +1,17 @@
 b35646a2f3d7c30fd34e3ea6ab6a1070b39c469fd1de49cab1093ff32faaf06d  gencode/docs/command_discovery.html
-3e292717e9b220403c250eebcfb4132becb6f59546f0bd3c3ec3042c31986d48  gencode/docs/command_mapping.html
+f3846531d40263e0c66fe6c2f24153b275aa2fad0ec9071cd27e4c94d853901b  gencode/docs/command_mapping.html
 64bafb080b454189b7b64a95e049c3427fd1cca70cf0809a31150610f40e9525  gencode/docs/config.html
-73b3beb740f5bc3ff26d173c356b2d3bf3b9892be83a704d3eeee7c9ff030230  gencode/docs/config_mapping.html
+3c3c69f9044a27a5ec9e7756eea3168784ed307e8c9576f19504f78aff4e9c24  gencode/docs/config_mapping.html
 cc4bb19794042f88f3a72b197b4d21736e5cebf6ec47ffac560430e9f580181f  gencode/docs/configuration_endpoint.html
 4da8ddd26aed7428171e1cbc6d134b37e30a958d09ce0f255bbb22b130d26f77  gencode/docs/configuration_execution.html
 fa89df05f3db9b27f96b65d89d3fef4aa3c8ad8e758fcfc123627f88bf600d00  gencode/docs/configuration_pubber.html
 0f0355e343cb8197dfbae1481c0eca3a0566d73181bc968e33fd469a1c94d1e6  gencode/docs/envelope.html
-92da453dec3e27493216f8c3672b6203be9eb9b3086741c22fda9432c22504b7  gencode/docs/event.html
-e81e06349dd9d88a57d7f6119da1fee2832b07fe8190b6df139e26777e7e76bc  gencode/docs/event_discovery.html
-9497b83603d537e11e264ee2d8056b298f5a5178e2c6aa435a6c9c0a051414b4  gencode/docs/event_mapping.html
+1bbe9f9cfe0d8d29a483e7ddd3f4924a0ca6245198f0c1fe7517c27bff30c8ef  gencode/docs/event.html
+8629172f3e1db2ebfb7e04f82ad977bca528a3f70cceca2da36e8925791efeea  gencode/docs/event_discovery.html
+7f0048d23d6f5a93d40520e7d5fd4ce4fbe76a7713ae2b2e5256be6dda3effb2  gencode/docs/event_mapping.html
 71fe25d3b17d1dc87b52c049a3235c20527f73e12ffa53fa4800a15e53f73732  gencode/docs/event_pointset.html
-c601733d04b0d389d7800a801b0862da41567d1f1fa63d9529a462b8269f0462  gencode/docs/event_system.html
-301d174a945f82816c9640450e072c55abdcb37383b76428e6d37dfbc6aa9dfe  gencode/docs/event_validation.html
+78e70a483842f51b09b077f397343c9a73264c9112e0aac2bd9c95cbf68877a0  gencode/docs/event_system.html
+fff8f5649bae6b8a789dd9e708ad7dd6ff06fb64b8e62776d3d39484210ae28f  gencode/docs/event_validation.html
 9ae793a641f2e053c5af734bf813cd2637a675330acb8d9e903ef03b4286e007  gencode/docs/metadata.html
 9300480de06d728cfe366304b4a06ad1fc135cd27fa5fd3f1bc59e33703044a5  gencode/docs/persistent_device.html
 5d039d607af9ec75ee552dfe36b16c702687ea16f5663f41fc49b4533b86e00d  gencode/docs/properties.html
@@ -21,9 +21,9 @@ f46367beaab5886ef87ce70b542611134c3565daa53e367de4f49dab51214f12  gencode/docs/r
 741b880216be3743f6747800a042f2dbd89f3b0344c6b0a965f4bc010f03a930  gencode/docs/schema_doc.css
 878ea88206c974f40643c3cc430875f9c4e8c5e3fd6bcd6358bd3eb6d48699a9  gencode/docs/schema_doc.min.js
 7ed934930aee763e0beebc349725ba3909115e8d346bb762f28bcbe745bb163a  gencode/docs/schema_extras.js
-63cd94346f634ca2945982c147546cb1103fcfea4c42eac04b065ca838f5217f  gencode/docs/state.html
-f10172c9b4cd350cae1f673077b07b1362168599b966a78d4ec4ef19b7bbf441  gencode/docs/state_mapping.html
-e8c57cbcea8328957e5fbf2d73fd15bd43cf783380f31deda9e8f96f6f7e6475  gencode/docs/state_validation.html
+5a4db4a693c7a56b8faeebc0062ea0cef7ef4373548c5ca4fd895a14c4943f82  gencode/docs/state.html
+d06f0fa0991bfd65740bca6fa20228dbe6b460e8f9f4f10ade4d7a17f533c979  gencode/docs/state_mapping.html
+298712c47e127eef3d716292c1ca38ce5122b7d255ef690127e96ca192c47409  gencode/docs/state_validation.html
 d39d7fe37a41c74a40080af7b0a429d201ab1fdff7444428c4b98eb7b38c332b  gencode/java/udmi/schema/Asset.java
 b405ce628f7819b46b19950aeaba89ee938fea54261000616bc534b9f81bd59c  gencode/java/udmi/schema/Auth_provider.java
 0825a5cec83003bb0a6488c4ed7010a04ae0d3848ef36fe01bb4e6718ba7b96d  gencode/java/udmi/schema/Aux.java
@@ -34,7 +34,7 @@ b9f903444ab08907e41eb123286434ff3207b1edd01397af3ddefb8475bbdadc  gencode/java/u
 fcbed49f1af8b791d8c52bcbe18f65521a79d9ac3eb33ec3afd9b342ab2bfc56  gencode/java/udmi/schema/BlobsetState.java
 b9699c9540d185ee5cfd49c6834892daf3a340328db2219ba16a65c874dc8f64  gencode/java/udmi/schema/Bucket.java
 0a4f6bcd5065418c1cdc6c05b900b3de31744847d25b6ab6de7aabb1e724710e  gencode/java/udmi/schema/BuildingTranslation.java
-53b376f83028237345d1746e8e6023fc701da1d16499929470ec1f80fecddae6  gencode/java/udmi/schema/Category.java
+dc1aa4a9038954327905bdea80ef75babb3ddd8faf78f999eef4469796db0e4a  gencode/java/udmi/schema/Category.java
 a2eeff86f4302272736d84602e2ca36a64d27c8ef6761cc05ffb8ad17b030d4d  gencode/java/udmi/schema/CloudModel.java
 ff79de9390aa25bb45fb3e2ebb682c865ccab764f56d9644377d9d28c0ab10e4  gencode/java/udmi/schema/Config.java
 cf9762392e02b5d04c6498963222cc0c00f7be6c3cd82bde3d063a5eceba2b65  gencode/java/udmi/schema/Connections.java
@@ -66,7 +66,7 @@ a5e5adfc187709e8646a11c92e804acfb67743f9d72149008aaca954df3177f6  gencode/java/u
 07fd4911363437b274c19b024759b04b116152176702da8d4203c4ff4cb55b7f  gencode/java/udmi/schema/LocalnetConfig.java
 910c68183db7703b00bcb81146ad73e6fe0d4bbc4caec4dc9c621f3cc2e5eee5  gencode/java/udmi/schema/LocalnetModel.java
 2df4ae32d0bbecc21f7c3f6a416a195baa766a6210cfa8abca4a7bb45b9c7961  gencode/java/udmi/schema/Location.java
-b815ba1f198fd32b11fbedf71e5fa820bba08713dc5c95603c700dfa21ec5904  gencode/java/udmi/schema/MappingCommand.java
+ccc7c234dd522a91d387d55573677681bbc5a6926f0fbf1101c2e9f607cafd63  gencode/java/udmi/schema/MappingCommand.java
 0f6f85a4aaffb90735acc2565e8e4afa349d3ded5781cb1dce1ebbaa237feaa7  gencode/java/udmi/schema/MappingConfig.java
 39f4cf5f89dc52f24ea02246e17668ebc85ed0fab351e69138e477bcc048d79c  gencode/java/udmi/schema/MappingEvent.java
 052b6b7f9ca8173901d9d2fae314f5858e034f20efa5d184780b800bd870cb2b  gencode/java/udmi/schema/MappingEventEntity.java
@@ -114,7 +114,7 @@ b77d953fd22e655c0f10ae32deeaa222769d971f8c38b3379eba45720fb910cc  gencode/java/u
 dab4f5fca272ec48c2881bca2b6bc43786ada47fa1f6dd935c35f7ce0eb6b0f6  gencode/python/udmi/schema/building_translation.py
 470b688984b89b25fcdfa8e08bd95b0c5d8c551d53a6ab5512503ee39419e6fa  gencode/python/udmi/schema/category.py
 6578d68f65b87b781086e72566de910db4bef365599fe3188862d4d8a81e84fb  gencode/python/udmi/schema/command_discovery.py
-e96b4fc8e7be1f078d3e66b7075f9357fd27bb57b703fb07068ebb3d73d6d04f  gencode/python/udmi/schema/command_mapping.py
+27762e35ea705b0c02c4875d77834d5935f93f3414f6c0ba5e23c55a37b70ea7  gencode/python/udmi/schema/command_mapping.py
 c5a62f92328e2ede167fc1f53bece6e48696a0ab0e37e3a41f65cd98494ba0d7  gencode/python/udmi/schema/common.py
 b975892df78076dabc797b4c0be87f20b33eacda11f9d1ac1c09be33d4937a87  gencode/python/udmi/schema/config.py
 79eb0299b3751d93c01a5de65eacc717283e99caf0996f3db48a15247f69c8eb  gencode/python/udmi/schema/config_blobset.py

.github/workflows/testing.yml

@@ -38,6 +38,17 @@ jobs:
         if: ${{ always() }}
         run: bin/run_tests registrar_tests
 
+  spelling:
+    name: Docs Spelling Checks
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - name: Check Spelling
+        uses: rojopolis/[email protected]
+        with:
+          config_path: .spellcheck.yml
+          task_name: Markdown
+
   redirect:
     name: Endpoint Redirection
     runs-on: ubuntu-latest

.spellcheck.yml

@@ -0,0 +1,28 @@
+matrix:
+- name: Markdown
+  expect_match: false
+  apsell:
+    mode: en
+  dictionary:
+    wordlists:
+    - .wordlist.txt
+    output: wordlist.dic
+    encoding: utf-8
+  pipeline:
+  - pyspelling.filters.markdown:
+      markdown_extensions:
+      - markdown.extensions.extra:
+  - pyspelling.filters.html:
+      comments: false
+      attributes:
+      - alt
+      ignores:
+      - ':matches(code, pre)'
+      - 'code'
+      - 'pre'
+      - 'blockquote'
+  sources:
+  - '*.md'
+  - 'docs/**/*.md'
+  - 'misc/**/*.md'
+  - 'udmif/**/*.md'

.wordlist.txt

@@ -0,0 +1,159 @@
+acked
+AHU
+anagement
+api
+APIs
+ARP
+ascii
+auth
+Auth
+backend
+backoff
+bacnet
+BACnet
+blobset
+BMS
+buildingsiot
+centric
+CLA
+CLI
+CloudRun
+CoAP
+comms
+config
+coreutils
+CoV
+cron
+datapoint
+DBO
+DBP
+designator
+deterministically
+dev
+Dev
+directionality
+DNS
+downlink
+enablement
+encoding
+encodings
+env
+envs
+etag
+etags
+ethmac
+ETHMAC
+evice
+faucetsdn
+fieldbus
+gcloud
+GCP
+GCR
+GCS
+gencode
+GiB
+github
+Github
+GitLab
+gittools
+GKE
+googlegroups
+GraphQL
+hostname
+http
+https
+IAM
+idToken
+invoker
+io
+iot
+IoT
+ipv
+IPv
+JDK
+JS
+json
+JWT
+keygen
+kube
+kubectl
+Kubernetes
+localhost
+logentry
+loglevel
+macos
+MacOS
+md
+modbus
+MQTT
+mydomain
+niversal
+npm
+nterface
+OIDC
+onboarding
+Onboarding
+pagent
+parameterization
+parsers
+pointname
+pointset
+postfix
+prem
+Prem
+prepend
+programmatically
+provisioner
+proxied
+Proxied
+proxying
+PUBACKs
+pubber
+PubSub
+QoS
+Readme
+repo
+RPC
+RSA
+runDev
+runtime
+schemas
+Schemas
+SDK
+setpoint
+sha
+src
+Stackdriver
+stateStatus
+subblock
+subblocks
+subdirectory
+subflows
+subFolder
+subType
+subTypes
+terraform
+terraformed
+testability
+TLS
+TODO
+transactional
+transpile
+transpiles
+txt
+udmi
+UDMI
+udmif
+UDMIF
+UDMI's
+UDMIS
+UI
+underspecified
+uniqs
+unwriteable
+uplink
+url
+validator
+writeback
+Writeback
+yaml

CONTRIBUTING.md

@@ -10,8 +10,8 @@ just a few small guidelines you need to follow.
 Contributions to this project must be accompanied by a Contributor License
 Agreement. You (or your employer) retain the copyright to your contribution,
 this simply gives us permission to use and redistribute your contributions as
-part of the project. Head over to <https://cla.developers.google.com/> to see
-your current agreements on file or to sign a new one.
+part of the project. Head over to [the CLA developer's page](https://cla.developers.google.com/)
+to see your current agreements on file or to sign a new one.
 
 You generally only need to submit a CLA once, so if you've already submitted one
 (even if it was for a different project), you probably don't need to do it

README.md

@@ -57,7 +57,7 @@ All these situations are conceptually about _management_ of devices, which is co
 different than the _control_ or _operation_. These concepts are similar to the _management_,
 _control_, and _data_ planes of
 [Software Defined Networks](https://queue.acm.org/detail.cfm?id=2560327).
-Once operational, the system should be able to operate completely autonomoulsy from the
+Once operational, the system should be able to operate completely autonomously from the
 management capabilities, which are only required to diagnose or tweak system behavior.
 
 ## Design Philosophy
@@ -76,7 +76,7 @@ to implement, and more ambiguity. Strive towards having only _one_ way of doing
 very large structures or high-bandwidth streams.
 * <b>Property Names:</b>Uses <em>snake_case</em> convention for property names.
 * <b>Resource Names:</b> Overall structure (when flattened to paths), follows the
-[API Resource Names guidline](https://cloud.google.com/apis/design/resource_names).
+[API Resource Names guidelines](https://cloud.google.com/apis/design/resource_names).
 
 ## Subsystem Blocks
 

docs/cloud/gcp/cloud_setup.md

@@ -16,7 +16,7 @@
     *   Set the default _Cloud Pub/Sub topic_ for the registry to the topic `udmi_target`
     *   Set the _Device state topic_ (may be hidden under _Advanced Options_) to `udmi_state`
 4.  Install the Google Cloud SDK in order to be able to use some of the tools included,
-    such as the registrar tool
+    such as the `registrar` tool
     *   Follow the guidance on [Google Cloud SDK](https://cloud.google.com/sdk/docs/install)
         installation documentation
     *   Once installed, configure the
@@ -25,7 +25,7 @@
     *   Select the project your registry resides in using
         `gcloud config set project <YOUR_PROJECT_ID>`
 5.  Ensure the authenticated user has at minimum the following IAM permissions
-    in order to use the the validator and registar tools
+    in order to use the the `validator` and `registrar` tools
     *   IoT Core Provisioner
     *   Pub/Sub Editor
 6.  Install [Cloud Functions](functions.md)

docs/cloud/gcp/functions.md

@@ -51,10 +51,12 @@ graph LR
 
 The UDMI reflector setup is designed to allow an external (to the GCP project) _utility_ to interact
 with the system through a channel authenticated as an IoT Device. This is functionally equivalent
-to an _agent_ connected over PubSub, but has a different authenticaiton/connection paradigm. Specifically,
+to an _agent_ connected over PubSub, but has a different authentication/connection paradigm. Specifically,
 a PubSub connection will rely on a GCP-based IAM auth to provide access to PubSub resources,
 while a _reflector_ connection relies on a device-specific credential and connects over MQTT.
 
 Utilities connect to the `UDMS-REFLECT` IoT Core registry, backed by the _udmi__reflect_ topic/function.
 The 'device' within the `UDMS-REFLECT` registry is actually the _site\_name_ of the site (so not
-an actual device), corresponding to the IoT Core _registry_ containing the actual device connections.
+an actual device), corresponding to the IoT Core _registry_ containing the actual device connections. The
+(undocumented) reflector API allows for all the basic device-oriented operations { _config_, _state_, _events_,
+_commands } as well as some meta-functions like querying the version of running UDMIS functions.

docs/cloud/gcp/swarm.md

@@ -17,7 +17,7 @@ The 'pubber swarm' capability relies on four major components:
 ## Create/identify GCP project
 
   * Set project location if/as necessary for your organization
-  * Docs assume GCP_PROJECT env varaible is set appropriately, e.g.
+  * Docs assume GCP_PROJECT env variable is set appropriately, e.g.
   `export GCP_PROJECT=udmi-swarm-example`
 
 ## Setup IoT Core Registry

docs/cloud/gcp/terraform.md

@@ -6,19 +6,17 @@ The files in the [`cloud`](../../cloud) folder enable the creation of Cloud infr
 
 At the moment only Google Cloud Platform (GCP) is supported.
 
-## Pre-requisites
+## Prerequisites
 
-There are some pre-requisites that need to be satisfied in order to use this terraform configuration to setup UDMI infrastructure in a GCP cloud project:
+There are some prerequisites that need to be satisfied in order to use this terraform configuration to setup UDMI infrastructure in a GCP cloud project:
 
 1. A working installation of [terraform](https://learn.hashicorp.com/tutorials/terraform/install-cli?in=terraform/gcp-get-started)
 2. An [existing project on GCP](https://cloud.google.com/resource-manager/docs/creating-managing-projects)
 4. [Create a service account](https://cloud.google.com/iam/docs/creating-managing-service-accounts) for terraform with Owner role
 5. Create a Standard type storage bucket setup with a unique name. example: `udmi-terraform-state-bucket`. You should disable public access and ensure your service account has access to it.
 6. [Generate a JSON key](https://cloud.google.com/iam/docs/creating-managing-service-account-keys) for the terraform service account, download it and store it in the [`udmi/cloud/auth`](../../../cloud/gcp/auth) folder with the name `credentials.json`\
-7. [Create a UDMI group for your organisation](https://cloud.google.com/iam/docs/groups-in-cloud-console). This group name should be provided in various locations. 
-8. [Create a mongoDB account](https://www.mongodb.com/atlas/database). This is our current persistence layer for UDMIF.
-9. [create a mongoDB API key with Project Creator permissions](https://www.mongodb.com/docs/atlas/configure-api-access/#std-label-create-org-api-key). Those keys are used by terraform to create the DB cluster and databases.
-10. [Enable the following APIS manually](https://cloud.google.com/endpoints/docs/openapi/enable-api). Cloud Resource Manager API and Service Usage API.
+7. [Create a UDMI group for your organization](https://cloud.google.com/iam/docs/groups-in-cloud-console). This group name should be provided in various locations. 
+8. [Enable the following APIs manually](https://cloud.google.com/endpoints/docs/openapi/enable-api). Cloud Resource Manager API and Service Usage API.
 
 NOTE: There is currently a limitation in the terraform code that requires the project name and id to be the same.
 TODO: create a gcloud based shell script to automatically does all activities listed above.
@@ -37,15 +35,15 @@ cp main.tf.template main.tf
 Edit them according to the project settings and according to the UDMI site you need to create and group permissions you want to attribute to it.
 
 The next steps are to initialize the required terraform backend, provider and modules and 
-to import the project and the bucket previously created to the terraform state: (Note, you only need to do the imports once, unless you remove their associated states from beeing tracked.
+to import the project and the bucket previously created to the terraform state: (Note, you only need to do the imports once, unless you remove their associated states from being tracked.
 
 ```
 terraform init
 terraform import google_project.udmi-project ${GCP_PROJECT_NAME}
 terraform import google_storage_bucket.tf-bucket ${UDMI_TERRAFORM_BUCKET_NAME}
 ```
 
-where ${GCP_PROJECT_NAME} is the name of the GCP project created in the pre-requisite step 2 and ${UDMI_TERRAFORM_BUCKET_NAME} is the name of the terraform state bucket created in step 3.
+where ${GCP_PROJECT_NAME} is the name of the GCP project created in the prerequisite step 2 and ${UDMI_TERRAFORM_BUCKET_NAME} is the name of the terraform state bucket created in step 3.
 
 The next step is to check that the planned tasks are correct:
 
@@ -61,9 +59,9 @@ terraform apply
 
 ### Troubleshooting
 
-- If you need to reset your infrastructure by using *terraform destroy* (use with caution), you should first remove the tf_bucket and project resources from being tracked in the terraform state:
+- If you need to reset your infrastructure by using *terraform destroy* (use with caution), you should first remove the `tf_bucket` and project resources from being tracked in the terraform state:
     ```
     terraform state rm google_project.udmi-project
     terraform state rm google_storage_bucket.tf-bucket
     ```
-- If you run into API enablement issues or other issues, you can retry the *plan* and *apply* terraform commands. If you still have issues, you can look at api.tf for a list of APIs that must be enabled and enable them manually.
+- If you run into API enablement issues or other issues, you can retry the *plan* and *apply* terraform commands. If you still have issues, you can look at `api.tf` for a list of APIs that must be enabled and enable them manually.