Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

documentation updates #312

Merged
merged 10 commits into from
Apr 28, 2022
Merged

documentation updates #312

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
c95c08a
add links to hosted documentation
noursaidi Apr 26, 2022
57ff4e2
add gencode docs
noursaidi Apr 26, 2022
a4a369e
fix version description, add config handling
noursaidi Apr 27, 2022
71ef770
work with declared hardware fields
noursaidi Apr 28, 2022
0c30963
gencode
noursaidi Apr 28, 2022
e717acc
restore schema change
noursaidi Apr 28, 2022
20d5ff9
restore gencode
noursaidi Apr 28, 2022
23e3090
Merge commit 'a4a369ed' into docs4
noursaidi Apr 28, 2022
1c7d7a3
blank line
noursaidi Apr 28, 2022
be9b1c0
gencode again ..
noursaidi Apr 28, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 20 additions & 18 deletions .gencode_hash.txt
View file
Open in desktop
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
Open in desktop
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
Open in desktop
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
Open in desktop
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