misc doc updates (#4)

README.md

@@ -7,7 +7,7 @@ Nominally meant for use with [Googe's Cloud IoT Core](https://cloud.google.com/i
 as a schema it can be applied to any set of data or hosting setup. Additionally, the schema
 has provisions for basic telemetry ingestion, such as datapoint streaming from an IoT device.
 
-By deisgn, this schema is intended to be:
+By design, this schema is intended to be:
 * <b>U</b>niversal: Apply to all subsystems in a building, not a singular vertical solution.
 * <b>D</b>evice: Operations on an IoT _device_, a managed entity in physical space.
 * <b>M</b>anagement: Focus on device _management_, rather than command & control.
@@ -17,7 +17,7 @@ RPC mechanism.
 See the associated [UDMI Tech Stack](docs/tech_stack.md) for details about transport mechanism
 outside of the core schema definition. For questions and discussion pertaining to this topic,
 please join/monitor the
-[daq-users@googlegroups.com](https://groups.google.com/forum/#!forum/daq-users) email list 
+[daq-users@googlegroups.com](https://groups.google.com/forum/#!forum/daq-users) email list.
 
 ## Use Cases
 
@@ -32,15 +32,15 @@ UDMI is intended to support a few primary use-cases:
 * [_Gateway Proxy_](docs/gateway.md): Proxy data/connection for non-UDMI devices,
 allowing adaptation to legacy systems.
 * _On-Prem Actuation_: Ability to effect on-prem device behavior.
-* _Device Testability_: e.g. Trigger a fake alarm to test reporting mechanims.
+* _Device Testability_: e.g. Trigger a fake alarm to test reporting mechanisms.
 * _Commissioning Tools_: Streamline complete system setup and install.
-* _Operational Diagnostics_: Make it easy for system operators to diagnoe basic faults.
+* _Operational Diagnostics_: Make it easy for system operators to diagnose basic faults.
 * _Status and Logging_: Report system operational metrics to hosting infrastructure.
 * _Key Rotation_: Manage encryption keys and certificates in accordance with best practice.
 * _Credential Exchange_: Bootstrap higher-layer authentication to restricted resources.
 * _Firmware Updates_: Initiate, monitor, and track firmware updates across an entire fleet
 of devices.
-* _On-Prem Discovery_: Enumerate and on-prem devices to aid setup or anomaly detection.
+* _On-Prem Discovery_: Enumerate any on-prem devices to aid setup or anomaly detection.
 
 All these situations are conceptually about _management_ of devices, which is conceptually
 different than the _control_ or _operation_. These concepts are similar to the _management_,
@@ -49,14 +49,14 @@ _control_, and _data_ planes of
 Once operational, the system should be able to operate completely autonomoulsy from the
 management capabilities, which are only required to diagnose or tweak system behavior.
 
-## Design Philiosphy
+## Design Philosophy
 
 In order to provide for management automation, UDMI strives for the following principles:
-* <b>Secure and Authenticated:</b> Requires a propertly secure and authenticated channel
+* <b>Secure and Authenticated:</b> Requires a properly secure and authenticated channel
 from the device to managing infrastructure.
 * <b>Declarative Specification:</b> The schema describes the _desired_ state of the system,
 relying on the underlying mechanisms to match actual state with desired state. This is
-conceptually similar to Kubernetes-style configuraiton files.
+conceptually similar to Kubernetes-style configuration files.
 * <b>Minimal Elegant Design:</b> Initially underspecified, with an eye towards making it easy to
 add new capabilities in the future. <em>It is easier to add something than it is to remove it.</em>
 * <b>Reduced Choices:</b> In the long run, choice leads to more work
@@ -78,7 +78,7 @@ is comprised of several subsections (e.g. _system_ or _pointset_) that describe
 relevant sub-state components.
 * Device _config_ ([example](schema/config.tests/example.json)), passed from cloud to device,
 defined by [<em>config.json</em>](schema/config.json). There is one active _config_ per device,
-which is considered current until a new config is recevied.
+which is considered current until a new config is received.
 * Message _envelope_ ([example](schema/envelope.tests/example.json)) for server-side
 attributes of received messages, defined by [<em>envelope.json</em>](schema/envelope.json). This is
 automatically generated by the transport layer and is then available for server-side

docs/pubber.md

@@ -1,7 +1,7 @@
 # Pubber Reference Client
 
 The _Pubber_ reference client is a sample implementation of a client-side 'device' that implements
-the [UDMI Schema](../schemas/udmi/README.md). It's not intended to be any sort of production-worthy
+the [UDMI Schema](../README.md). It's not intended to be any sort of production-worthy
 code or library, rather just a proof-of-concept of what needs to happen.
 
 ## Build Pubber
@@ -20,7 +20,7 @@ BUILD SUCCESSFUL in 2s
 ## Key Generation
 
 <pre>
-~/daq$ <b>pubber/bin/keygen</b>
+~/daq$ <b>bin/keygen RS256_X509 local</b>
 Generating a 2048 bit RSA private key
 ............+++
 ......................................+++
@@ -32,7 +32,7 @@ writing new private key to 'local/rsa_private.pem'
 -rw-r--r-- 1 user primarygroup 1216 Nov 19 18:56 local/rsa_private.pkcs8
 </pre>
 
-After generating the key pair, you'll have to upload/associate the `pubber_cert.pem` public certificate
+After generating the key pair, you'll have to upload/associate the `rsa_cert.pem` public certificate
 with the device entry in the cloud console as an _RS256_cert_. (This can be done when the device is
 created, or anytime after.)
 

docs/registrar.md

@@ -1,15 +1,15 @@
 # Registrar Overview
 
 The `registrar` is a utility program that registers and updates devies in Cloud IoT.
-Running `bin/registrar` will pull the necessary configuraiton values from `local/system.conf`,
+Running `bin/registrar` will pull the necessary configuration values from `local/system.conf`,
 build the executable, and register/update devices.
 
 ## Configuration
 
 The `local/system.conf` file should have the following parameters (in `x=y` syntax):
-* `gcp_cred`: Defines the target project and [service account](service.md) to use for configuration.
-* `site_path`: [Site-specific configuration](site_path.md) for the devices that need to be registered.
-* `schema_path`: Path to metadata schema (see the [DAQ PubSub documentation](pubsub.md) for more details/examples).
+* `gcp_cred`: Defines the target project and [service account](https://github.com/faucetsdn/daq/blob/master/docs/service.md) to use for configuration.
+* `site_path`: [Site-specific configuration](https://github.com/faucetsdn/daq/blob/master/docs/site_path.md) for the devices that need to be registered.
+* `schema_path`: Path to metadata schema (see the [DAQ PubSub documentation](https://github.com/faucetsdn/daq/blob/master/docs/pubsub.md) for more details/examples).
 
 The target `gcp_cred` service account will need the _Cloud IoT Provisioner_ and _Pub/Sub Publisher_ roles.
 There also needs to be an existing `registrar` topic (or as configured in `cloud_iot_config.json`, below).

docs/tech_stack.md

@@ -10,8 +10,8 @@ technology stack for compliant IoT devices.
   * Other transports (non-Google MQTT, CoAP, etc...) are acceptable with prior approval.
   * Connected to a specific Cloud IoT Registry designated for each site-specific project.
 * Utilizes the MQTT Topic table listed below.
-* JSON encoding following the core [UDMI Schema](README.md), specifying the semantic structure of the data.
-* Passes the [DAQ Validation Tool](../../docs/validator.md) for all requirements.
+* JSON encoding following the core [UDMI Schema](../README.md), specifying the semantic structure of the data.
+* Passes the [DAQ Validation Tool](validator.md) for all requirements.
 
 # MQTT Topic Table