Gwproto Enums

GridWorks Enums used in gwproto, the Application Shared Language (ASL) used by SCADA devices and AtomicTNodes to communicate with each other. These enums play a specific structural role as semantic “glue” within ASLs.

Key attributes:

  • Enum values are translated into “GridWorks Type Enum Symbols” (GtEnumSymbols) when embedded

in a serialized type sent as a message from one Application and/or Actor to another. - Each Enum has a unique name in the type registry (like spaceheat.telemetry.name), along with a version (like 001). - That name are interpretted locally in the SDK and do not necessarily carry the larger context of the unique type registry name (for example gwproto uses TelemetryName, since the spaceheat context goes without saying). - Each Value/Symbol pair also has a version. Value/Symbol pairs cannot be changed or removed. The only adjustments that can be made to an enum are adding more Value/Symbols. This is to support forwards- and backwards- compatability in GridWorks Types that use these enums.

If Enums are “glue”, then GridWorks Types are the building blocks of SALs. Every SAL is comprised of a set of shared GridWorks Types.

Application Shared Languages are an evolution of the concept of Application Programming Interfaces. In a nutshell, an API can be viewed as a rather restricted version of an SAL, where only one application has anything complex/interesting to say and, in general, the developers/owners of that application have sole responsibility for managing the versioning and changing of that API. Note also that SALs do not make any a priori assumption about the relationship (i.e. the default client/server for an API) or the message delivery mechanism (i.e. via default GET/POST to RESTful URLs). For more information on these ideas:

class gwproto.enums.ActorClass(value)

Determines the code running Spaceheat Nodes supervised by Spaceheat SCADA software

Enum sh.actor.class version 001 in the GridWorks Type registry.

Used by used by multiple Application Shared Languages (ASLs), including but not limited to gwproto. For more information:

Values (with symbols in parens):

  • NoActor (00000000): A SpaceheatNode that does not have any code running on its behalf within the SCADA, but is instead only a reference object (for example, a tank of hot water or a resistive element) that can be discussed (for example, the power drawn by the resistive element can be measured) or evaluated (for example, a set of 5 different temperatures in different places on the tank can be used to estimate total thermal energy in the tank).

  • Scada (6d37aa41): The SCADA actor is the prime piece of code running and supervising other ProActors within the SCADA code. It is also responsible for managing the state of TalkingWith the AtomicTNode, as well maintaining and reporting a boolean state variable that indicates whether it is following dispatch commands from the AtomicTNode XOR following dispatch commands from its own HomeAlone actor.

  • HomeAlone (32d3d19f): HomeAlone is an abstract Spaceheat Actor responsible for dispatching the SCADA when it is not talking with the AtomicTNode.

  • BooleanActuator (fddd0064): A SpaceheatNode representing a generic boolean actuator capable of turning on (closing a circuit) or turning off (opening a circuit).

  • PowerMeter (2ea112b9): A SpaceheatNode representing the power meter that is used to settle financial transactions with the TerminalAsset. That is, this is the power meter whose accuracy is certified in the creation of the TerminalAsset GNode via creation of the TaDeed. [More Info](https://gridworks.readthedocs.io/en/latest/terminal-asset.html).

  • Atn (b103058f): A SpaceheatNode representing the AtomicTNode. Note that the code running the AtomicTNode is not local within the SCADA code, except for a stub used for testing purposes. [More Info](https://gridworks.readthedocs.io/en/latest/atomic-t-node.html).

  • SimpleSensor (dae4b2f0): A SpaceheatNode representing a sensor that measures a single category of quantity (for example, temperature) for a single object (for example, on a pipe). [More Info](https://gridworks-protocol.readthedocs.io/en/latest/simple-sensor.html).

  • MultipurposeSensor (7c483ad0): A sensor that either reads multiple kinds of readings from the same sensing device (for example reads current and voltage), reads multiple different objects (temperature from two different thermisters) or both. [More Info](https://gridworks-protocol.readthedocs.io/en/latest/multipurpose-sensor.html).

  • Thermostat (4a9c1785): A SpaceheatNode representing a thermostat.

  • HubitatTelemetryReader (0401b27e): A generic actor for reading telemetry data from a Hubitat Home Automation Hub LAN API. [More Info](https://drive.google.com/drive/u/0/folders/1AqAU_lC2phzuI9XRYvogiIYA7GXNtlr6).

  • HubitatTankModule (e2877329): The actor for running a GridWorks TankModule, comprised of two Z-Wave Fibaro temp sensors built together inside a small container that has 4 thermistors attached. These are designed to be installed from top (1) to bottom (4) on a stratified thermal storage tank. [More Info](https://drive.google.com/drive/u/0/folders/1GSxDd8Naf1GKK_fSOgQU933M1UcJ4r8q).

  • HubitatPoller (00000100): An actor for representing a somewhat generic ShNode (like a thermostat) that can be polled through the Hubitat.

  • Hubitat: (0000101): An actor for representing a Hubitat for receiving Hubitat events over HTTP.

  • HoneywellThermostat: (0000102): An actor for representing a Honeywell Hubitat thermostat which can load thermostat heating state change messages into status reports.

classmethod default()

Returns default value (in this case NoActor)

Return type:

ActorClass

classmethod enum_name()

The name in the GridWorks Type Registry (sh.actor.class)

Return type:

str

classmethod enum_version()

The version in the GridWorks Type Registry (001)

Return type:

str

classmethod symbol_to_value(symbol)

Given the symbol sent in a serialized message, returns the encoded enum.

Parameters:

symbol (str) – The candidate symbol.

Returns:

The encoded value associated to that symbol. If the symbol is not recognized - which could happen if the actor making the symbol is using a later version of this enum, returns the default value of “NoActor”.

Return type:

str

classmethod symbols()

Returns a list of the enum symbols

Return type:

List[str]

classmethod value_to_symbol(value)

Provides the encoding symbol for a ActorClass enum to send in seriliazed messages.

Parameters:

value (str) – The candidate value.

Returns:

The symbol encoding that value. If the value is not recognized - which could happen if the actor making the message used a later version of this enum than the actor decoding the message, returns the default symbol of “00000000”.

Return type:

str

classmethod values()

Returns enum choices

Return type:

List[str]

classmethod version(value)

Returns the version of an enum value.

Once a value belongs to one version of the enum, it belongs to all future versions.

Parameters:

value (str) – The candidate enum value.

Raises:

ValueError – If value is not one of the enum values.

Returns:

The earliest version of the enum containing value.

Return type:

str

class gwproto.enums.LocalCommInterface(value)

Categorization of in-house comm mechanisms for SCADA

Enum local.comm.interface version 000 in the GridWorks Type registry.

Used by used by multiple Application Shared Languages (ASLs), including but not limited to gwproto. For more information:

Values (with symbols in parens):

  • Unknown (00000000)

  • I2C (9ec8bc49)

  • Ethernet (c1e7a955)

  • OneWire (ae2d4cd8)

  • RS485 (a6a4ac9f)

  • SimRabbit (efc144cd)

  • Wifi (46ac6589)

  • Analog_4_20_mA (653c73b8)

  • RS232 (0843a726)

classmethod default()

Returns default value (in this case UNKNOWN)

Return type:

LocalCommInterface

classmethod enum_name()

The name in the GridWorks Type Registry (local.comm.interface)

Return type:

str

classmethod enum_version()

The version in the GridWorks Type Registry (000)

Return type:

str

classmethod symbol_to_value(symbol)

Given the symbol sent in a serialized message, returns the encoded enum.

Parameters:

symbol (str) – The candidate symbol.

Returns:

The encoded value associated to that symbol. If the symbol is not recognized - which could happen if the actor making the symbol is using a later version of this enum, returns the default value of “Unknown”.

Return type:

str

classmethod symbols()

Returns a list of the enum symbols

Return type:

List[str]

classmethod value_to_symbol(value)

Provides the encoding symbol for a LocalCommInterface enum to send in seriliazed messages.

Parameters:

value (str) – The candidate value.

Returns:

The symbol encoding that value. If the value is not recognized - which could happen if the actor making the message used a later version of this enum than the actor decoding the message, returns the default symbol of “00000000”.

Return type:

str

classmethod values()

Returns enum choices

Return type:

List[str]

classmethod version(value)

Returns the version of an enum value.

Once a value belongs to one version of the enum, it belongs to all future versions.

Parameters:

value (str) – The candidate enum value.

Raises:

ValueError – If value is not one of the enum values.

Returns:

The earliest version of the enum containing value.

Return type:

str

class gwproto.enums.MakeModel(value)

Determines Make/Model of device associated to a Spaceheat Node supervised by SCADA

Enum spaceheat.make.model version 001 in the GridWorks Type registry.

Used by used by multiple Application Shared Languages (ASLs), including but not limited to gwproto. For more information:

Values (with symbols in parens):
classmethod default()

Returns default value (in this case UNKNOWNMAKE__UNKNOWNMODEL)

Return type:

MakeModel

classmethod enum_name()

The name in the GridWorks Type Registry (spaceheat.make.model)

Return type:

str

classmethod enum_version()

The version in the GridWorks Type Registry (001)

Return type:

str

classmethod symbol_to_value(symbol)

Given the symbol sent in a serialized message, returns the encoded enum.

Parameters:

symbol (str) – The candidate symbol.

Returns:

The encoded value associated to that symbol. If the symbol is not recognized - which could happen if the actor making the symbol is using a later version of this enum, returns the default value of “UnknownMake__UnknownModel”.

Return type:

str

classmethod symbols()

Returns a list of the enum symbols

Return type:

List[str]

classmethod value_to_symbol(value)

Provides the encoding symbol for a MakeModel enum to send in seriliazed messages.

Parameters:

value (str) – The candidate value.

Returns:

The symbol encoding that value. If the value is not recognized - which could happen if the actor making the message used a later version of this enum than the actor decoding the message, returns the default symbol of “00000000”.

Return type:

str

classmethod values()

Returns enum choices

Return type:

List[str]

classmethod version(value)

Returns the version of an enum value.

Once a value belongs to one version of the enum, it belongs to all future versions.

Parameters:

value (str) – The candidate enum value.

Raises:

ValueError – If value is not one of the enum values.

Returns:

The earliest version of the enum containing value.

Return type:

str

class gwproto.enums.Role(value)

Categorizes SpaceheatNodes by their function within the heating system

Enum sh.node.role version 000 in the GridWorks Type registry.

Used by used by multiple Application Shared Languages (ASLs), including but not limited to gwproto. For more information:

Values (with symbols in parens):

  • Unknown (00000000): Unknown Role

  • Scada (d0afb424): Primary SCADA

  • HomeAlone (863e50d1): HomeAlone GNode

  • Atn (6ddff83b): AtomicTNode

  • PowerMeter (9ac68b6e): A SpaceheatNode representing the power meter that is used to settle financial transactions with the TerminalAsset. That is, this is the power meter whose accuracy is certified in the creation of the TerminalAsset GNode via creation of the TaDeed. [More Info](https://gridworks.readthedocs.io/en/latest/terminal-asset.html).

  • BoostElement (99c5f326): Resistive element used for providing heat to a thermal store.

  • BooleanActuator (57b788ee): A solid state or mechanical relay with two states (open, closed)

  • DedicatedThermalStore (3ecfe9b8): A dedicated thermal store within a thermal storage heating system - could be one or more water tanks, phase change material, etc.

  • TankWaterTempSensor (73308a1f): A temperature sensor used for measuring temperature inside or on the immediate outside of a water tank.

  • PipeTempSensor (c480f612): A temperature sensor used for measuring the temperature of a tank. Typically curved metal thermistor with thermal grease for good contact.

  • RoomTempSensor (fec74958): A temperature sensor used for measuring room temperature, or temp in a heated space more generally.

  • OutdoorTempSensor (5938bf1f): A temperature sensor used for measuring outdoor temperature.

  • PipeFlowMeter (ece3b600): A meter that measures flow of liquid through a pipe, in units of VOLUME/TIME

  • HeatedSpace (65725f44): A Heated Space.

  • HydronicPipe (fe3cbdd5): A pipe carrying techinical water or other fluid (e.g. glycol) in a heating system.

  • BaseboardRadiator (05fdd645): A baseboard radiator - one kind of emitter in a hydronic heating system.

  • RadiatorFan (6896109b): A fan that can amplify the power out of a radiator.

  • CirculatorPump (b0eaf2ba): Circulator pump for one or more of the hydronic pipe loops

  • MultiChannelAnalogTempSensor (661d7e73): An analog multi channel temperature sensor

  • Outdoors (dd975b31): The outdoors

classmethod default()

Returns default value (in this case Unknown)

Return type:

Role

classmethod enum_name()

The name in the GridWorks Type Registry (sh.node.role)

Return type:

str

classmethod enum_version()

The version in the GridWorks Type Registry (000)

Return type:

str

classmethod symbol_to_value(symbol)

Given the symbol sent in a serialized message, returns the encoded enum.

Parameters:

symbol (str) – The candidate symbol.

Returns:

The encoded value associated to that symbol. If the symbol is not recognized - which could happen if the actor making the symbol is using a later version of this enum, returns the default value of “Unknown”.

Return type:

str

classmethod symbols()

Returns a list of the enum symbols

Return type:

List[str]

classmethod value_to_symbol(value)

Provides the encoding symbol for a Role enum to send in seriliazed messages.

Parameters:

value (str) – The candidate value.

Returns:

The symbol encoding that value. If the value is not recognized - which could happen if the actor making the message used a later version of this enum than the actor decoding the message, returns the default symbol of “00000000”.

Return type:

str

classmethod values()

Returns enum choices

Return type:

List[str]

classmethod version(value)

Returns the version of an enum value.

Once a value belongs to one version of the enum, it belongs to all future versions.

Parameters:

value (str) – The candidate enum value.

Raises:

ValueError – If value is not one of the enum values.

Returns:

The earliest version of the enum containing value.

Return type:

str

class gwproto.enums.TelemetryName(value)

Specifies the name of sensed data reported by a Spaceheat SCADA

Enum spaceheat.telemetry.name version 001 in the GridWorks Type registry.

Used by used by multiple Application Shared Languages (ASLs), including but not limited to gwproto. For more information:

Values (with symbols in parens):

  • Unknown (00000000): Default Value - unknown telemetry name.

  • PowerW (af39eec9): Power in Watts.

  • RelayState (5a71d4b3): An associated read must be either 0 or 1, with 0 meaning that the relay is open and current CANNOT flow and 1 meaning that the relay is closed and current CAN flow. Note in particular that this TelemetryName is NOT meant to be used to reflect whether a relay is energized or de-energized and in particular ‘1’ means the same thing for both Normally Open and Normally Closed relays. Also, it is not meant to be used for a double-throw relay.

  • WaterTempCTimes1000 (c89d0ba1): Water temperature, in Degrees Celcius multiplied by 1000. Example: 43200 means 43.2 deg Celcius.

  • WaterTempFTimes1000 (793505aa): Water temperature, in Degrees F multiplied by 1000. Example: 142100 means 142.1 deg Fahrenheit.

  • GpmTimes100 (d70cce28): Gallons Per Minute multiplied by 100. Example: 433 means 4.33 gallons per minute.

  • CurrentRmsMicroAmps (ad19e79c): Current measurement in Root Mean Square MicroAmps.

  • GallonsTimes100 (329a68c0): Gallons multipled by 100. This is useful for flow meters that report cumulative gallons as their raw output. Example: 55300 means 55.3 gallons.

  • VoltageRmsMilliVolts (bb6fdd59): Voltage in Root Mean Square MilliVolts.

  • MilliWattHours (e0bb014b): Energy in MilliWattHours.

  • FrequencyMicroHz (337b8659): Frequency in MicroHz. Example: 59,965,332 means 59.965332 Hz.

  • AirTempCTimes1000 (0f627faa): Air temperature, in Degrees Celsius multiplied by 1000. Example: 6234 means 6.234 deg Celcius.

  • AirTempFTimes1000 (4c3f8c78): Air temperature, in Degrees F multiplied by 1000. Example: 69329 means 69.329 deg Fahrenheit.

  • ThermostatState (00002000): An enum representing the state of the thermostat heat call.

classmethod default()

Returns default value (in this case Unknown)

Return type:

TelemetryName

classmethod enum_name()

The name in the GridWorks Type Registry (spaceheat.telemetry.name)

Return type:

str

classmethod enum_version()

The version in the GridWorks Type Registry (001)

Return type:

str

classmethod symbol_to_value(symbol)

Given the symbol sent in a serialized message, returns the encoded enum.

Parameters:

symbol (str) – The candidate symbol.

Returns:

The encoded value associated to that symbol. If the symbol is not recognized - which could happen if the actor making the symbol is using a later version of this enum, returns the default value of “Unknown”.

Return type:

str

classmethod symbols()

Returns a list of the enum symbols

Return type:

List[str]

classmethod value_to_symbol(value)

Provides the encoding symbol for a TelemetryName enum to send in seriliazed messages.

Parameters:

value (str) – The candidate value.

Returns:

The symbol encoding that value. If the value is not recognized - which could happen if the actor making the message used a later version of this enum than the actor decoding the message, returns the default symbol of “00000000”.

Return type:

str

classmethod values()

Returns enum choices

Return type:

List[str]

classmethod version(value)

Returns the version of an enum value.

Once a value belongs to one version of the enum, it belongs to all future versions.

Parameters:

value (str) – The candidate enum value.

Raises:

ValueError – If value is not one of the enum values.

Returns:

The earliest version of the enum containing value.

Return type:

str

class gwproto.enums.Unit(value)

Specifies the physical unit of sensed data reported by SCADA

Enum spaceheat.unit version 000 in the GridWorks Type registry.

Used by used by multiple Application Shared Languages (ASLs), including but not limited to gwproto. For more information:

Values (with symbols in parens):

  • Unknown (00000000)

  • Unitless (ec972387)

  • W (f459a9c3)

  • Celcius (ec14bd47)

  • Fahrenheit (7d8832f8)

  • Gpm (b4580361)

  • WattHours (d66f1622)

  • AmpsRms (a969ac7c)

  • VoltsRms (e5d7555c)

  • Gallons (8e123a26)

  • ThermostatStateEnum (00003000)

classmethod default()

Returns default value (in this case Unknown)

Return type:

Unit

classmethod enum_name()

The name in the GridWorks Type Registry (spaceheat.unit)

Return type:

str

classmethod enum_version()

The version in the GridWorks Type Registry (000)

Return type:

str

classmethod symbol_to_value(symbol)

Given the symbol sent in a serialized message, returns the encoded enum.

Parameters:

symbol (str) – The candidate symbol.

Returns:

The encoded value associated to that symbol. If the symbol is not recognized - which could happen if the actor making the symbol is using a later version of this enum, returns the default value of “Unknown”.

Return type:

str

classmethod symbols()

Returns a list of the enum symbols

Return type:

List[str]

classmethod value_to_symbol(value)

Provides the encoding symbol for a Unit enum to send in seriliazed messages.

Parameters:

value (str) – The candidate value.

Returns:

The symbol encoding that value. If the value is not recognized - which could happen if the actor making the message used a later version of this enum than the actor decoding the message, returns the default symbol of “00000000”.

Return type:

str

classmethod values()

Returns enum choices

Return type:

List[str]

classmethod version(value)

Returns the version of an enum value.

Once a value belongs to one version of the enum, it belongs to all future versions.

Parameters:

value (str) – The candidate enum value.

Raises:

ValueError – If value is not one of the enum values.

Returns:

The earliest version of the enum containing value.

Return type:

str