Scheduling is a feature of the OK platform. It allows schedules to be created in the OKC that can command OKEs to change states at specific dates and times. The schedule created in the OKC is run locally on the CWM connected to the OKE. When a schedule period activates, the CWM will sequentially send a list of one or more equipment specific commands to the OKE. The CWM will run the schedule even when connectivity to the OKC is down.

To support scheduling, an OKE implementor only needs to parse and handle equipment specific commands in the CWPortInboundMsgCB()  callback, document those commands in the OK data dictionary, and collaborate with the OK developers to add the scheduling UI widget to the portal's dashboard.

With this division of labor most of the scheduling feature's implementation complexity is the burden of the OKC and CWM. OKE implementors have only a small amount of documentation and implementation work to leverage this capability.

Optionally, part or all of a schedule may be overridden for a period of time by either the OKE or the OKC based on the specific requirements and policies enumerated by the OKE implementors. Schedule overrides do increase the complexity of implementing a schedule feature by OKE implementors.

OK Scheduling Capabilities

1. Schedules have 1 minute resolution for each period. Theoretically, there can be up to 1440 periods per day, but typically there are only a small number.

2. Schedules are created and execute in the OKE's local time base, even across daylight savings discontinuities.

3. Schedules are encoded as JSON.

4. Within the OKC, schedules that are months to years in advance can be created. The CWM will locally store and execute a schedule for up to a week in the future. The OKC will automatically update the schedule daily to maintain about 1 week of future schedule on the CWM.

5. One or more OKE commands may be associated with a schedule period. The OKE commands are embedded in the schedule, the CWM does not interpret or validate the commands before sending them sequentially to the OKE. Since each command is a JSON string it may contain multiple elements.

6. Optionally, either the OKE or OK portal may issue temporary schedule overrides that affect parts or all of a schedule.

7. The CWM can store and execute a weekly schedule up to 4096 bytes in total size. This size may be increased in future releases.

8. When the CWM boots up it will look for the active schedule period and issue the commands associated with that period even if it is not at the exact start of the period. Once running the CWM will issue new commands at the start of the next schedule period. In both cases the period's commands will be reissued every minute. This addresses cases where an OKE was not able to receive the commands, or if an unauthorized change is made to the equipment's state during the period. For example, a schedule sets a thermostat's setpoint to 72F, an employee accidentally changes the setpoint to 78F, at the next minute interval the CWM will resend the setpoint command and the thermostat will revert the setpoint to 72F.

Equipment Specific Command Requirements

1. Commands must be valid JSON syntax. For example, {"on":1} is a valid command.

2. Commands should follow the guidelines in the section "OKM Field Name Conventions". In short, do not collide with reserved OKM names, and make equipment commands compact and reasonably human comprehendible.

3. Commands must be stateless. For example, a command to toggle a thermostat fan on and off is stateful and is not allowed since the behavior of the command depends on the current state of the equipment. In contrast, fan turn on and fan turn off commands are stateless.

4. Redundant commands must be gracefully ignored. For example, if a thermostat's fan is off and is subsequently commanded to turn off it should not report any warnings or errors, it should simply do nothing.

5. Commands must be processed such that unnecessary dependencies are not required nor disallowed. For example, a turn off command should not require that a setpoint be contained in the same command request. Likewise, if the setpoint is included with a turn off command they should both be successfully processed. The goal is to have maximum flexibility to issue commands in any combination to the OKE.

6. Commands must be range checked by the OKE and ignored if outside design limits. For example, if a command is issued to change a setpoint to 1100F, well beyond the upper limit, the OKE must ignore the request and may optionally report a warning or error counter to the OKC in its heartbeat.

7. The OKE may process commands differently based on the source and the override state.

See Processing Inbound Equipment Specific OKMs for examples of how to properly parse incoming commands when schedule overrides are not implemented.

Overrides

Both the OKE and the OK portal may optionally override part or all of a schedule temporarily based on the requirements and policy preferences of the OKE implementors.

Overrides are an optional feature for OKE implementors. OKEs may support schedules: without overrides, with only local overrides, with only remote overrides, or with both local and remote overrides.

Local Overrides (OKE Overrides)

OKE implementors may optionally provide equipment specific UIs, such as buttons or configuration screens, that enable equipment operators to override some or all scheduled commands for an arbitrary time based on the requirements and policy preferences of the OKE implementors.

When overriding, the OKE conditionally ignores specific command requests in the CWPortInboundMsgCB()callback that would affect the state of the override. For example, if a setpoint is overridden locally any command received by the callback to change the setpoint would simply be ignored until the override ends.

The CWL provides APIs so that the OKE can locally set and clear specific types of OKE defined overrides, and easily determine when specific overrides are in effect so that the appropriate command requests in the CWPortInboundMsgCB()callback can be ignored. The CWL automatically and periodically reports the local override states to the OKC. The set of overrides is documented by the OKE implementor in the data dictionary thus allowing the OKC to report when specific local overrides are in effect.

Remote Overrides (OK Overrides)

Optionally the OKC, based on the specific requirements and policies defined by the equipment implementors, can set and clear the same set of OKE defined overrides as can be done locally. Remote overrides are tracked separately from local overrides. The CWL automatically and periodically reports the remote override state to the OKC thus allowing the OKC to report when specific remote overrides are in effect.

Overriding an Override

Based on the requirements and policies defined by the OKE implementors, the OKE may be allowed to clear a remote override, and the OKC may be allowed to clear a local override.

The CWL API allows for the OKE to determine if a remote override is in effect, if the remote override can be cleared locally, and when permitted the ability to clear the remote override. The OKC, based on the policy preferences of the OKE implementors, determines which remote overrides are permitted to be locally cleared.

Likewise, the CWL allows for the OKC to determine if a local override can be remotely cleared, and when permitted to clear the local override. The OKE, based on the policy preferences of the OKE implementors, determines which local overrides are permitted to be remotely cleared. The CWL provides an API for the OKE to configure the remote override permission individually for each type of override.

Override Persistence

If a local override is in effect and the CWL is reinitialized for any reason, the CWL will, by default, not indicate that any local overrides are in effect. It is up to the OKE implementors to determine if certain local overrides must be tracked in non-volatile memory through a reinitialization, and if so, it must restore the local override state as part of the CWL initialization process.

When a remote override is in effect and the CWL is reinitialized for any reason, the CWL will, by default, not indicate that any remote overrides are in effect. However, the OKC can reenable an active remote override if it detects that the remote override was cleared due to a reinitialization of the CWL, according to the policy preferences of the OKE implementors.

Schedule Override API

Overriding schedules is an optional feature, and when required it must be enabled at compile time in cwport.h by setting CW_PORT_IS_SCHEDULE_OVERRIDE_ENABLED to 1.

When enabled the OKE implementor is responsible for defining the type of overrides that the system supports by adding override enumerations to the CW_PORT_OVERRIDE_t definition in cwport.h and documenting them in the data dictionary.

For example, by default, the CW_PORT_OVERRIDE_t definition is:

If an OKE implementor wants to implement an thermostat setpoint override and a mode override, then they might extend the definition to look like:

Note: When adding new types of overrides it required to add the new overrides immediately before the CW_PORT_MAX_OVERRIDE constant so that the mapping of the existing overrides does not change.

The following is the entire CWL API for controlling the override state (both local and remote):

Setting and Clearing Local Overrides

To set a local override CWCmdSetLocalOverride(CW_PORT_OVERRIDE_t override) is invoked where override is one of the OKE implementor defined constants. For example, if the oven operator increases the oven setpoint to override the scheduled setpoint, the OKE will invoke CWCmdSetLocalOverride(CW_PORT_OVEN_SET_POINT_OVERRIDE)and then change the setpoint to th'operator's requested value.

To clear a local override CWCmdClearLocalOverride(CW_PORT_OVERRIDE_t override) is invoked where override is one of the OKE implementor defined constants. For example, if the oven only permits the oven setpoint override for 2 hours then at the end that duration or if the operator chooses to end it early CWCmdClearLocalOverride(CW_PORT_OVEN_SET_POINT_OVERRIDE) will be invoked. The CWM will send the scheduled setpoint command to the OKE at the next minute interval and cause the OKE to begin following the scheduled behavior again.

Overriding Overrides API Calls

The OKE can set which local overrides are permitted to be cleared remotely by the OKC. By default all local overrides can be cleared remotely by the OKC. If the OKE wants to prevent the OKC from the ability to clear a local override then it can invoke CWCmdSetLocalOverrideClearable(CW_PORT_OVERRIDE_t override) where override is the specific override to prevent the OKC from being able to clear. The OKE can subsequently allow the OKC to remotely clear a local override by invoking CWCmdClearLocalOverrideClearable(CW_PORT_OVERRIDE_t override). The OKE can try to clear a remote override by invoking CWCmdClearRemoteOverride(CW_PORT_OVERRIDE_t override), which will return true if the remote override was cleared, else false if it was not clearable locally.

Checking for Overrides

The CWL provides the bool CWCmdIsInOverride(CW_PORT_OVERRIDE_t override, bool *isLocalOverride, bool *isRemoteOverride, bool *isRemoteOverrideClearable) function that allows the OKE to determine if a specific override is active, and optionally if it is a local or locally overridable remote override. There are two reasons the OKE would invoke this function. First to be able to report to the local operator if local or remote overrides are active via a local OKE user interface. Second, to determine if schedule command requests received from the CWM should be ignored. The override parameter is one of the OKE implementor defined constants. When not passed as a value of NULL, the isLocalOverride parameter will be set to true if a local override is active, false otherwise. When not passed as a value of NULL, the isRemoteOverride parameter will be set to true if a remote ovctivee is active, false otherwise. Note: it is possible for both the local and remote override be set simultaneously. When not passed as a value of NULL, the isRemoteOverrideClearable parameter will be set to true if a remote override is locally clearable, false otherwise. If either a local or remote override is active the function will return true, else false.

Example Inbound Processing with Overrides

The following example shows how a an OKE would parse an incoming message to change the state of a relay while also implementing local and remote overrides.  It is nearly identical to the normal inbound message processing except that a new function, CWPortIsPermitted(), implements application specific logic that determines when part of an inbound message should be ignored due to a local or remote override. In this example, when not in override the system will always process inbound relay commands. When in local override inbound relay commands will not be processed. When in remote override inbound relay commands are only processed if originating from the OKC.