Outbound & Inbound OKMs
- Ricky Goldfarb
Sending Outbound OKMs
An OKE system can send outbound OKM requests. However, it must do so under the context of the CWPortOutboundMsgCB() function to prevent contention with the serial driver.
For example, if an OKE system wants to force the CWM to scan for WiFi networks, the OKE system needs to call the CWCmdRequestNetScan() function from within the CWPortOutboundMsgCB() function.
void CWPortOutboundMsgCB(CWNWK_STATUS_t lastMsgStatus)
{
if (_sendScanRequest)
{
CWCmdRequestNetScan()
_sendScanRequest = false;
}
}To force the CWPortOutboundMsgCB() function to be called a request can be issued from the CWPortRunTask() function context by calling the CWMsgScheduleOutboundMsgCB() function. This will cause CWPortOutboundMsgCB() to be called as soon as possible.
void CWPortRunTask(bool returnToCaller)
{
/* Service the ConnectWare task */
do
{
if (_sendScanRequest) CWMsgScheduleOutboundMsgCB();
CWMsgRunTask();
Sleep(5);
} while (!returnToCaller);
}The OKE's user interface would simply set the _sendScanRequest flag true whenever the user selected for a scan to occur. In this case scan results are returned via the CWPortSetNetScanResults() callback.
Processing Inbound Equipment Specific OKMs
A few OKE systems will not need to process Equipment Specific OKMs since many inbound OKMs are already handled automatically by the CWL. However, many OKE systems may want to allow the OKC to make configuration changes and affect control operations, therefore the application will need to handle these requests.
Whenever the CWL receives an inbound OKM that does not contain a message already known to the CWL, the CWL will pass the message to the application code by calling the CWPortInboundMsgCB() function.
void CWPortInboundMsgCB(char* payload, uint16_t len, bool isWrite, uint16_t id, char* srcStr)The payload parameter is a string containing a valid JSON message. The len parameter is the length of the payload string. The isWrite parameter is true if the payload should be interpreted as a write, else when false the payload should be interpreted as a read. The two different values of isWrite change the meaning and processing behavior of the exact same payload string. When documenting OKE commands in the data dictionary, they should indicate if a command is read, write, or both. For example, a message that changes a setpoint would be designated as a write command, but a message that causes the OKE to generate and send a diagnostic file to the OKC would be designated as a read command. The id parameter is a transaction ID associated with the inbound message. In some cases, when the OKE generates "response" message to the OKC, it may be useful to include the id's value as the rid (response id) so that it is easy for the OKC to match the request/response sequence. The srcStr parameter indicates the source of the inbound command message contained in payload.
The application code will need to parse the OKM and handle it appropriately. The application code to parse and handle an application specific OKM should be modeled after the parsing code in cwcmd.c and other example contained in this User's Guide.
Inbound Equipment Specific OKM Parsing Example
The following example shows how a an OKE would parse an incoming message to change the state of a relay. In this relay example a payload can have the following valid values: {"cmd":{"relay":0}} or {"cmd":{"relay":1}}. MJFind() checks to see if the relay command is present in the payload string, and if so if the value is a number. If the relay command is present and the value is a number, then it confirms that it is a write request. If those checks pass, the value of relay is read into relayVal, which is subsequently bounds checked by the switch statement.
Notice that if the relay command is not present, it is not a write, or it does not have a valid numerical value code execution will simply continue. If an OKE support inbound messages, it will typically support more than one command. So, the parsing code should sequentially check for the presence of all possible commands in each payload. For example, the following pseudocode shows the proper logic for parsing both the relay command, documented above and a setpoint command:
This allows the following combination of payloads to be fully processed
In contrast the following pseudocode shows the incorrect way to parse incoming payload because it fails to check for other valid commands if one is found earlier:
When an OKE supports optional schedule overrides it must implement some additional logic in the incoming parser code. See OpenKitchen Scheduling for details.