@@ -10,89 +10,50 @@ device _state_/_config_, and only expose the relevant pieces.
1010
1111The basic mode of this interface is a "read only" subscription to a PubSub topic (normally
1212` udmi_target ` ) that then provides a complete view of updates as they flow through the system.
13- For example, a cloud-to-device _ config_ update would be published on this topic as a "update
14- to device config." This level of visibility should be sufficient to completely mirror the
13+ This level of visibility should be sufficient to completely mirror the
1514visible state of the system (barring issues like loss-of-message etc...).
1615
17- The various _ subblocks _ are detailed below. Each _ subblock _ (or _ subFolder _ if you're looking
18- at the PubSub _ message envelope _ ), has several basic _ subTypes _ that manifest themselves from
19- different sources:
16+ Messages are typed by their _ subType _ and _ subFolder _ (named so because of legacy integrations).
17+ The _ subType _ field specifies generic message semantics, while the _ subFolder _ specifies the
18+ semantic interpretation.
2019
21- * ** Model** : Model-based description of this device. Unlike the other messages, this exists
22- independent of any actual physical device, and will be injected by the system through something
23- like the ` registrar ` tool. The _ model_ is typically also reflected in a _ site\_ model_ as a
24- static set of files somewhere.
25- * ** Event** : Streaming telemetry. This is essentially a raw feed from the device itself,
26- and will always be segmented by subblock (e.g. for a
27- [ pointset event] ( ../../tests/schemas/events_pointset/example.json ) ). Streaming telemetry
28- is sent from the device, so will be _ received by_ a client app.
29- * ** State** : Device state for this subblock. Unlike a
20+ ## _ subType_ attribute values
21+
22+ Several main _ subType_ values cover normal system operations. Other values not specified here should
23+ be ignored if received. If the _ subType_ field is missing then it should default to ` event ` .
24+
25+ * ` event ` : Streaming telemetry from the device, representing changes to metrics or other values
26+ that change frequently.
27+ (See [ pointset event] ( ../../tests/schemas/events_pointset/example.json ) as an example.) Messages
28+ with a defaulted ` event ` type represent raw telemetry from the device, while an explicit ` event `
29+ type means the messages has been processed by the intermediate pipeline in some form.
30+ * ` state ` : Device state for this subblock. Unlike a
3031 [ comprehensive device state message] ( ../../tests/schemas/state/example.json )
3132 this message contains information _ only_ for a single subblock. Used for reporting any 'sticky'
32- state from a device, so will be _ received by_ a client app.
33- * ** Config** : Device config for this subblock. Unlike a
33+ state from a device that has been processed and separated out by the UDMIS pipeline. A special
34+ _ subFolder_ of ` update ` indicates a complete state message and should generally be ignored by
35+ consuming applications.
36+ * ` config ` : A confirmed device config update for this subblock. Unlike a
3437 [ comprehensive device config message] ( ../../tests/schemas/config/example.json )
35- this message contains information _ only_ for a single subblock. Used for writing configuration
36- changes to a device, so will be _ sent from_ a client app.
37- * ** Commands** : Streaming commands from cloud to the device. Generally not used because a model-based
38- approach using device state is preferred.
39-
40- In all cases, the _ Subblock API_ messages encode the relevant subblock ID { pointset, discovery, ... }
41- in the [ message envelope's] ( ../../tests/schemas/envelope/example.json ) _ subFolder_ field.
42- The _ subType_ field encodes the relevant type { _ events_ , _ config_ , _ state_ , _ model_ }.
43-
44- ## System
45-
46- * ** Model**
47- * ** Event**
48- * ** State**
49- * ** Config**
50-
51- ## [ Pointset] ( ../messages/pointset.md )
52-
53- A _ pointset_ covers the structures necessary to model a device _ point_ with associated data readings.
54- This is typically what is thought of as 'device telemetry' and represents the expected end value of
55- the device-to-cloud connection.
56-
57- * [ ** Model** ] ( ../../tests/schemas/model_pointset/example.json ) : Expected model for what the device should
58- be reporting.
59- * [ ** Event** ] ( ../../tests/schemas/events_pointset/example.json ) : Streaming telemetry events from the device
60- containing the actual data points.
61- * [ ** State** ] ( ../../tests/schemas/state_pointset/example.json ) : State of the device points, indicating any
62- sticky errors or status of any cloud-to-device config.
63- * [ ** Config** ] ( ../../tests/schemas/config_pointset/example.json ) : Configuration of the device points,
64- indicating the expected points, cloud-to-device control, etc...
65-
66- ## Discovery
67-
68- _ Discovery_ covers systems that are actively searching for systems on a network (of some kind), and
69- returning results about what was discovered and what their capabilities are. This provides a mechanism
70- for doing things like a BACnet discovery sequence.
71-
72- * ** Model**
73- * ** Event**
74- * ** State**
75- * ** Config**
76-
77- ## Audit
78-
79- _ Audit_ covers an external "black box" audit of a system for vulnerabilities or other characteristics.
80- E.g., doing a port-scan of a device to see what network ports are open would be part of a network
81- exposure audit.
82-
83- * ** Model**
84- * ** Event**
85- * ** State**
86- * ** Config**
87-
88- ## Mapping
89-
90- The _ mapping_ process covers the determination of a translation from a set of identifiers or points to
91- a canonical or other set of identifiers or points. E.g., there's a mapping process that goes on to
92- correlate a BACnet MAC address (such as ` 9832C2 ` ) with an associated IoT ID (such as ` FCU-323 ` ).
93-
94- * ** Model**
95- * ** Event**
96- * ** State**
97- * ** Config**
98-
38+ this message contains information _ only_ for a single subblock. This message is injected after
39+ the config update has been applied to the device as an effective confirmation of an applied
40+ config change.
41+ * ` model ` : Model-based description of this device(so does not correspond to any to/from device
42+ message). This message is generated by various tools (such as ` registrar ` ) that manipulate the
43+ cloud-based provisioning and setup of the device. Generally, this is a live reflection of the
44+ device's ` site_model ` contents.
45+
46+ ## _ subFolder_ attribute values
47+
48+ The _ subFolder_ attribute describes the semantic category for the message. There's many potential
49+ values for this field (and it can be easily extended), but there are some primary values commonly
50+ of interest (and values not relevant to any given application should be ignored).
51+
52+ * [ ` system ` ] ( ../messages/system.md ) : High level information about a device as an overall entity,
53+ independent of specific functional blocks.
54+ * [ ` pointset ` ] ( ../messages/pointset.md ) : Relating to point (value reading) telemetry and values.
55+ * [ ` gateway ` ] ( gateway.md ) : How devices are connected together in a logical structure to proxy information from
56+ legacy (non-UDMI) fieldbus protocols.
57+ * [ ` discovery ` ] ( discovery.md ) : Raw information from on-prem discovery about on-prem configuration and setup.
58+ * ` cloud ` : How a device is represented or connects to cloud infrastructure (e.g. the authentication
59+ key type).
0 commit comments