Skip to content

Commit

Permalink
documentation updates (#312)
Browse files Browse the repository at this point in the history 
- Makes links on the root README.md direct to the hosted documentation.
- includes discovery in the sequences index page
- split hardware to explicitly describe the different fields
- Correct version description in schema (no longer major version)
- add expected behaviour on config
  • Loading branch information
@noursaidi
noursaidi authored Apr 28, 2022
1 parent 619d9ac commit 9904876
Show file tree
Hide file tree
Showing 36 changed files with 566 additions and 175 deletions.
38 changes: 20 additions & 18 deletions .gencode_hash.txt
View file
Original file line number Diff line number Diff line change
@@ -1,27 +1,27 @@
97695067e507720ef649cca27a0eb9ebf9ba8bebe31898289b7d6586a9ada6db gencode/docs/config.html
db8d2c22a281d8279244bd8768ee54f755a4a888633e036cc29b7f43cc6ce74c gencode/docs/config.html
e2944b13db5ff06be9caea51d03bca48f2cb093a8bb583dca14051255d34ea6b gencode/docs/envelope.html
cecc213148404cd2ad83ee519369c2e2f8b611798bcd6dce441d2f9c02804073 gencode/docs/event_discovery.html
987503860562a3971314a98d75890b6c7615fee84bff6bede7010231f469c035 gencode/docs/event_pointset.html
e3fb2b1a96f6fcb06f5af6cff32829abc825065ed52de81c3d379c8c8070fe09 gencode/docs/event_system.html
7fe8b7e549e9b66575996a1610c3d9f61c17b8784a9722a1ca66053a6d7ec1f0 gencode/docs/event_discovery.html
cb17a57a92baeb96c3de35d614346e8e04900bc0286720aaf31f392fd81dcb0a gencode/docs/event_pointset.html
080329e12ec1adeca08546ceface6ca8ba09495da8642dc3a1a22e83a7b83879 gencode/docs/event_system.html
a82821e72af6d0ee35800e6262eb9bb05256309b98aed2dad1a368fd2d6882bb gencode/docs/index.html
2e2fd3af888c3e784f632ad31115f1029a9af7832c2064871ebb6bb3ec34a58e gencode/docs/metadata.html
18880462118b7f9798687899a93eb9edb579b0a93f84e3345ab8825397c8e47a gencode/docs/metadata.html
741b880216be3743f6747800a042f2dbd89f3b0344c6b0a965f4bc010f03a930 gencode/docs/schema_doc.css
878ea88206c974f40643c3cc430875f9c4e8c5e3fd6bcd6358bd3eb6d48699a9 gencode/docs/schema_doc.min.js
7ed934930aee763e0beebc349725ba3909115e8d346bb762f28bcbe745bb163a gencode/docs/schema_extras.js
891b85eed0ddee056dc8158b82427229aeaa1b2bf3ab2dd36f8f5ba0fdabeb60 gencode/docs/state.html
c2e9ba962dca44436705438ab14e3c32e7ab637f4b279509f849cd4f33643642 gencode/docs/state.html
68f8919d59556c7c781958baaac0b8cc629b6c4ce86e6ffd0171d23536747ec6 gencode/java/udmi/schema/Ancillary.java
d39d7fe37a41c74a40080af7b0a429d201ab1fdff7444428c4b98eb7b38c332b gencode/java/udmi/schema/Asset.java
9a6088ab93e6de9107ba4c91e5ed19375d16a24baaec6ab5998e1c6351d5bba9 gencode/java/udmi/schema/AuditEvent.java
0edc9b905bbe4ad0ee5ffdb7fb5d65a00ad171b2dad299ef128e59c0bd9dddc0 gencode/java/udmi/schema/AuditEvent.java
0825a5cec83003bb0a6488c4ed7010a04ae0d3848ef36fe01bb4e6718ba7b96d gencode/java/udmi/schema/Aux.java
724ad8db7982f4d703c05245119dc7f7ff731d2141dd861893b55684e3cd6224 gencode/java/udmi/schema/BlobBlobsetConfig.java
7f54da38284a1010de1a2590381022fa16d27fd141d76d1ba6eb471de4d94781 gencode/java/udmi/schema/BlobBlobsetState.java
d2c5b5aae8db27b68104fc83a1f38de0a3f1b5d683f2b13599adf24e96c7d124 gencode/java/udmi/schema/BlobsetConfig.java
b6ff9b8739a9c3bb6972f73db6fc54f451189c13b273e58bc11cb3d82c74ad40 gencode/java/udmi/schema/BlobsetState.java
a2eeff86f4302272736d84602e2ca36a64d27c8ef6761cc05ffb8ad17b030d4d gencode/java/udmi/schema/CloudModel.java
28001569e7902d3aa39aa3749ca08fb8e29460ba97a4b560d266b365bf5f8c46 gencode/java/udmi/schema/Config.java
67ac3441ce6d5d4450741ee7e639174756498e1b3780c2d18ce20562b5a88c26 gencode/java/udmi/schema/DiscoveryCommand.java
ff79de9390aa25bb45fb3e2ebb682c865ccab764f56d9644377d9d28c0ab10e4 gencode/java/udmi/schema/Config.java
587d67a67431349939dffd37b880c44e798a1eb607d54bd6d8a077bbac668067 gencode/java/udmi/schema/DiscoveryCommand.java
d8a80ab3180d33bfa17564c969018e1d4350a47dbc70c4ae8a5abbfb25cfedc9 gencode/java/udmi/schema/DiscoveryConfig.java
0d4d7461494578c3530998ae203b43b422d2d7f3722e1095c3d81eb4bc0a1fd6 gencode/java/udmi/schema/DiscoveryEvent.java
fb243b3fa232d8497472869b0cf1acb2accea6dee72bbd006ec82396fd0012a9 gencode/java/udmi/schema/DiscoveryEvent.java
04112dd47b0f761131c276c67d3cd8b789d25e6716b5732be9fef14fc6831f1d gencode/java/udmi/schema/DiscoveryModel.java
9962b0eb7d5adf52af6160e9f3131f8eeb52ae9e518954dbb6aead1bcad0245e gencode/java/udmi/schema/DiscoveryState.java
090bbaf1508aa6ca8380af936af990673f300eb5a940c9e8ab94deb64efa2b7b gencode/java/udmi/schema/Entry.java
Expand All @@ -35,11 +35,12 @@ efb376cd7a80ca74fbf74d3ef3f4101d393341a91d01db36456aa84f6be3d0a5 gencode/java/u
60a8115ae1acae7c199b63180823198d38ec50d57b48dd85aca1ccc865058f85 gencode/java/udmi/schema/GatewayConfig.java
56b46f4914ef1f4baa59bf597186ff7901b7c8b607720ec798f4e4e6ad59aa08 gencode/java/udmi/schema/GatewayModel.java
e0e7739046e834c0f0ca6a70b38b4579618899be3162887a0fa7ab60bbff22a5 gencode/java/udmi/schema/GatewayState.java
961fc2b6972f3524e6796d1b065ae19de51bd875ac361649822961b1a9b30069 gencode/java/udmi/schema/Hardware.java
a5e5adfc187709e8646a11c92e804acfb67743f9d72149008aaca954df3177f6 gencode/java/udmi/schema/Level.java
07fd4911363437b274c19b024759b04b116152176702da8d4203c4ff4cb55b7f gencode/java/udmi/schema/LocalnetConfig.java
910c68183db7703b00bcb81146ad73e6fe0d4bbc4caec4dc9c621f3cc2e5eee5 gencode/java/udmi/schema/LocalnetModel.java
2df4ae32d0bbecc21f7c3f6a416a195baa766a6210cfa8abca4a7bb45b9c7961 gencode/java/udmi/schema/Location.java
a1b17e0a1bc10f8e2ea105649a4254fd81c67c3dbe5d78af661fadb739b5be54 gencode/java/udmi/schema/Metadata.java
304164da05dc722b6e94cfa68659f0120e2425c94bfb5f5a4c6d796fe13da885 gencode/java/udmi/schema/Metadata.java
a4e8f69100ab678a8236f481c558d677bbaea3e76c853bbd9262113d2a9c031d gencode/java/udmi/schema/Metrics.java
5e1c5411fae4d7c47391ceb5d19ae864fcd484df75ac6b6db39fd2d12647dec8 gencode/java/udmi/schema/Physical_tag.java
0868f0a9beb671dd08f066e7e7e796531fe151307a0b853b1f1a1aafe50ee746 gencode/java/udmi/schema/PointEnumerationEvent.java
Expand All @@ -48,20 +49,20 @@ a4e8f69100ab678a8236f481c558d677bbaea3e76c853bbd9262113d2a9c031d gencode/java/u
1372dc65268324a65a5854008b5dc5d2492328c145799dc4fda2a520e9f8198b gencode/java/udmi/schema/PointPointsetModel.java
db8d6dd3498019ad12e0f328b6237d07e52f133f8b08858b712611a52c198009 gencode/java/udmi/schema/PointPointsetState.java
c6a0571e228490defcb8fba335220b23247aea0e0cb9b657efc1e1e6dbcc0fb3 gencode/java/udmi/schema/PointsetConfig.java
f3aea029530d0d8c6f50a75f266fd222d3f5ad92004f40675d6a99c906d22c82 gencode/java/udmi/schema/PointsetEvent.java
bb1c7e0df78870b7f7bd78fdfb1ed115cb121613ffcd98ec6b95e41c01624d41 gencode/java/udmi/schema/PointsetEvent.java
580dd48ce15879fcedf2150e9b87de99c3b6bdf3b631372b1391af048ba6771f gencode/java/udmi/schema/PointsetModel.java
fc3a9415c04d8a06954dbdbfdff5d68ab113cce3948532c19df555778ffb04fa gencode/java/udmi/schema/PointsetState.java
ca2e7566106818ca7e5190c8041eb86f0c9b3251b0bda8c3ea7ce11a0c891a0a gencode/java/udmi/schema/Position.java
6ddce136f5e34e7e8c7d101c8a729f1fdd323befdfa52590ebdf0028f970bdf5 gencode/java/udmi/schema/Properties.java
0a1a025dde88fd46925cbb56f5179ed2803ea97948292809ff328a5201d90a3e gencode/java/udmi/schema/State.java
3df66bb1a37a9e0b2b6cf392f8c64d404a73c83e5e13c02bb4844f09b9a04b70 gencode/java/udmi/schema/Properties.java
580df660dad1b97399002271716d597f72aa1a6110a49de9e162104c231752f4 gencode/java/udmi/schema/State.java
6b8b054c5fa2baef5163d42cd6bf1b0aeb4d07aa881529d81f4ae7dfa4c2906e gencode/java/udmi/schema/SystemConfig.java
8075f2133463e55ac24fccf9391c94698c580b860ad1a0901d5346a2f369030b gencode/java/udmi/schema/SystemEvent.java
247652dd11714452adc27ffa542e3d5915f8e9b7b255d181723d6fe1e897b565 gencode/java/udmi/schema/SystemEvent.java
9cad2475189fa1115ca78978cbacaeac62fcb875494d72efa4bc40781e8072f9 gencode/java/udmi/schema/SystemModel.java
451217e2cce0ae9224a86f35b3bdea14b36658efe6f94f4a2dff4f4b1dc51cf7 gencode/java/udmi/schema/SystemState.java
6d4334b92e374ff096b90fcb4378cbc91b9c11a1eb238312a3e4b65d4aa01fe3 gencode/java/udmi/schema/SystemState.java
dfe4bb7c9ba6e366a967ff475883a8ff33fc558ae51db5c71fafae2323d0f8eb gencode/java/udmi/schema/Target.java
7d6dd13e368e7f073738fee69c15e18652a9b7d7ac63bde0a200f747e3aa1b1d gencode/java/udmi/schema/TargetTestingModel.java
d3968b92497e83a63f18cc0e74484a9807f1bb92db0c92d556ec2caaa143d645 gencode/java/udmi/schema/TestingModel.java
256831be7080ab66aac89d7027d9fa174a12ef4182de6123efa7f4c3f1e7ff04 gencode/python/udmi/schema/__init__.py
04e5a1734f164edea681962debfa3e1f2c2ec09726fd9cc5a45848d76b8e16f4 gencode/python/udmi/schema/__init__.py
6578d68f65b87b781086e72566de910db4bef365599fe3188862d4d8a81e84fb gencode/python/udmi/schema/command_discovery.py
704c8f0eec0b87015af8f7e524375f651b3d35f659ec89b4b022f8c1d0813ec5 gencode/python/udmi/schema/common.py
b975892df78076dabc797b4c0be87f20b33eacda11f9d1ac1c09be33d4937a87 gencode/python/udmi/schema/config.py
Expand Down Expand Up @@ -105,4 +106,5 @@ a5a914cb5d74c29671a4d29dfa6c700b3fec27d695d607e28814ad31307e82da gencode/python
05e82aa15c64842e206ae8ce3d5810d115bb890d009ea5d657822fad0e0d2165 gencode/python/udmi/schema/state_gateway.py
3520ad936af70b414d9e7f90e606a011768bc4ee3bf1248714acc517ee9b393d gencode/python/udmi/schema/state_pointset.py
837ecc89c477abe3a1faf837733ca05475774891b55353d84ca231d90a1fbf31 gencode/python/udmi/schema/state_pointset_point.py
c7e5245ac7fb8a17691e8bd5b71ff47b6b586f33b01e5c0150706598ee58aed5 gencode/python/udmi/schema/state_system.py
644cfe921d9973a8cc4e022c9c6881c212220ed97782ada9a009cb7c2f2ccc9d gencode/python/udmi/schema/state_system.py
12c0dba5d0e9123ebe6cbfbe91bc40b4e98a7f0d57e2ecb23207b7aa962c7d57 gencode/python/udmi/schema/state_system_hardware.py
22 changes: 11 additions & 11 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,8 +6,8 @@ The Universal Device Management Interface (UDMI) provides a high-level specifica
management and operation of physical IoT systems. This data is typically exchanged
with a cloud entity that can maintain a "digital twin" or "shadow device" in the cloud.

* [Core UDMI documentation](docs/) for tools and specifications
* [Message schema definition](https://github.com/faucetsdn/udmi/tree/master/schema) with ([_🧬Interactive Viewer_](gencode/docs/))
* [Core UDMI documentation](http://faucetsdn.github.io/udmi/docs/) for tools and specifications
* [Message schema definition](https://github.com/faucetsdn/udmi/tree/master/schema) with ([_🧬Interactive Viewer_](http://faucetsdn.github.io/udmi/gencode/docs/)
* [udmi-discuss@googlegroups.com](https://groups.google.com/forum/#!forum/udmi-discuss) email discussion list
* Bi-weekly _UDMI Discuss_ video meeting open to all (join the mailing list to get an invite)

Expand All @@ -19,14 +19,14 @@ By design, this schema is intended to be:
* **M**anagement: Focus on device _management_, rather than command & control.
* **I**nterface: Define an interface specification, rather than a client-library or RPC mechanism.

See the associated [UDMI Tech Stack](docs/specs/tech_stack.md) for details about transport mechanism
See the associated [UDMI Tech Stack](http://faucetsdn.github.io/udmi/docs/specs/tech_stack.md) for details about transport mechanism
outside of the core schema definition. Nominally meant for use with
[Google's Cloud IoT Core](https://cloud.google.com/iot/docs/), it can be applied to any set
of data or hosting setup.

## Recommended Workflow

The [recommended workflow](docs/guides/workflow.md) for UDMI covers using the _registrar_ and
The [recommended workflow](http://faucetsdn.github.io/udmi/docs/guides/workflow.md) for UDMI covers using the _registrar_ and
_validator_ tools to configure and test a cloud project. Additionally, the _pubber_ tool
is instrumental in setting up and testing the system independent of actual device setup.

Expand All @@ -40,7 +40,7 @@ manual operation (aren't automated), and increase the security exposure of the s

UDMI is intended to support a few primary use-cases:
* _Telemetry Ingestion_: Ingest device data points in a standardized format.
* [_Gateway Proxy_](docs/specs/gateway.md): Proxy data/connection for non-UDMI devices,
* [_Gateway Proxy_](http://faucetsdn.github.io/udmi/docs/specs/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 mechanisms.
Expand Down Expand Up @@ -83,10 +83,10 @@ very large structures or high-bandwidth streams.
UDMI provides a means to multiplex multiple functional subsystems through the same shared
communication channel. There are a number of subsystems that make up the core UDMI spec:

* Core [_system_](docs/messages/system.md) messages about the base device itself.
* Device [_pointset_](docs/messages/pointset.md) for device telemetry organized by points.
* Optional [_gateway_](docs/specs/gateway.md) functionality for proxying device/MQTT connections.
* Local [_discover_](docs/specs/discovery.md) for discovering device and network capabilities.
* Core [_system_](http://faucetsdn.github.io/udmi/docs/messages/system.md) messages about the base device itself.
* Device [_pointset_](http://faucetsdn.github.io/udmi/docs/messages/pointset.md) for device telemetry organized by points.
* Optional [_gateway_](http://faucetsdn.github.io/udmi/docs/specs/gateway.md) functionality for proxying device/MQTT connections.
* Local [_discover_](http://faucetsdn.github.io/udmi/docs/specs/discovery.md) for discovering device and network capabilities.

## Schema Structure

Expand Down Expand Up @@ -120,6 +120,6 @@ An interactive view of the schema is available on [https://faucetsdn.github.io/u
### Metadata Registration and Validation

Using UDMI on a project entails not only the base device and server implementations, but also
properly registering and validating device configuration. The [registrar](docs/tools/registrar.md)
tool and [validator](docs/tools/validator.md) tool provide a means to configure and check site
properly registering and validating device configuration. The [registrar](https://faucetsdn.github.io/udmi/docs/tools/registrar.md)
tool and [validator](https://faucetsdn.github.io/udmi/docs/tools/validator.md) tool provide a means to configure and check site
installations, respectively.
53 changes: 53 additions & 0 deletions docs/specs/sequences/config.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@
* There is an update from internal logic
* Other [sequences](./) such as [writeback](writeback.md) may have specific behaviors relating to
state messages
* A device should of continuously operating when recieving an erroneous config message. The

![State and config](images/state.png)

Expand Down Expand Up @@ -40,4 +41,56 @@ Device->Broker: **STATE**
* `system`:
* `last_config`: Server-side timestamp from the last processed `config`.
* `updating`: Boolean indicating if the system is still processing the last `config` update.

## Erroneous Config Handling

A device should be capable of interpreting erroneous messages without distrupting operation. There are
three types of errors which may be encountered when interpreting config messages:
* Hard-errors
* Soft-errors
* Non-errors

This behavior is tested by the `config` [sequencer](../../tools/sequencer.md) tests.

### Hard-errors

Hard errors are ones such that the sanity of the entire config block is held in question, and
considered "invalid" at a core level. This can happen when:
* Only in response to config update message received
* Payload does not pass JSON parsing
* Missing "required" parameters (e.g. top-level version field)
* NOT by unrecognized extra JSON fields

When this happens, the device should:
* Keep the previous config (and use it) as a "steady state"
* The state system.last_update time should not be updated
* Appropriate error message included in system.statuses.config
* All other status blocks (pointset, etc…) should remain unaffected

## Soft-errors

Are things that can be safely relegated to a specific sub-block (e.g. pointset) without other areas
being affected. This can happen when:
* Invalid operations are indicated (e.g. writeback to non-writable point)
* There is no blanket conditions for all subblocks (just depends)
* Possibly independent of config (internal to device changes)
* Can happen to multiple subblocks independently

When this happens, the device should:
* Update system.last_config with last config.timestamp (config change)
* Indicate relevant error (most significant) in system.statuses.{subblock}
* Indicate more error detail (if any) in irrelevant state sunblock
* Include additional error information in log messages (if appropriate)
* Continue operating as best possible given the specified (invalid) config

## Non-Errors

There are some things that are specifically non-errors, and essentially meant to enable/help with
backwards compatibility. This can happen when:
* There is an extra unknown field in a config json message.

When this happens, the device should:
* Silently ignore the extra field(s) as if there was nothing wrong.
* Generally can be implemented by setting some JSON parsers to "ignore unrecognized fields"


1 change: 1 addition & 0 deletions docs/specs/sequences/readme.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ Sequences are defined device behavior which are formulated from a series of even
## Defined Sequences

- [Config and State](config.md)
- [Discovery](discovery.md)
- [Writeback](writeback.md)

## Validation
Expand Down
Loading

0 comments on commit 9904876

Please sign in to comment.