The Powerhouse-Dynamics ConnectWare repo GitHub repository includes software simulators that are highly recommended tools for developing OKE (Open Kitchen Equipment) ports of the CWL (ConnectWare Library). The simulations can be used for debugging a new CWL port since they minimize the number of "moving parts" required to exercise an OKE system.
There are three independent simulators that can be run out of the box or modified to suit the needs of the developer. The compiled simulators are text-based Windows programs and are run from a command prompt. All three simulators can be run on different command terminals on the same computer.
...
okc.exe is a software simulation of the cloud server that runs on a local computer using a terminal. This simulator provides a means of monitoring OKM traffic, sending commands and data back to the OKE through the CWM simulator(Open Kitchen Message) traffic to and from the cloud.
The simulated CWM and OKC communicate to each other via inter-process communication that simulates a network connection between them. The OKC simulator can only interface with the CWM simulator.
OKC Sim Use Cases
This simulator is quite useful for validating data integrity of messages sent through the communications network chain. Use of this tool can be expanded to include unit testing for future firmware developments, ensuring that changes made in firmware do not break the OKM protocol.
CWM (ConnectWare Module) Simulator
...
The CWM simulation opens a serial comport on the Windows PC. This serial comport is used to connect to the developer’s equipment in the same manner that the physical CWM would connect.
CWM Sim Use Cases
The OKE typically provides the user interface for the equipment. The UI is responsible for providing access to network settings which reside in the CWM. The CWM Simulator provides the interaction with the OKE necessary to validate commands and messages used for network status and configuration changes necessary for installations. Using the CWM simulator, the developer can see the interaction of communications from both sides.
OKE (Open Kitchen Equipment) Simulator
This is a software simulation of a Kitchen appliance. The purpose of this from a developer point of view is for demonstration purposes. To show how the OKE should be communicating with the rest of the simulators. This can be a helpful starting place to guide a developer on what heartbeat messages are meant for and to follow along with the API porting guide.
There are two typical simulation scenarios:
...
| Expand | ||
|---|---|---|
| ||
An off the shelf Null Modem cable from FTDI Model USB NMC-2.5M has a convenient USB-A connector at each end. https://www.digikey.com/short/8mtn047d OR Use two separate USB to Serial cables wired together in null modem configuration. https://www.digikey.com/short/vc37mvzv Info | |
Simulator Software Location
All the simulation software can be found at the https://github.com/Powerhouse-Dynamics/connectware. If you have not requested access, please see the QuickStart page for details on gaining access for your integration.https://sitesage.atlassian.net/wiki/x/AwDqFw
The Powerhouse-Dynamics ConnectWare GitHub repository contains a folder called sim. These are the compiled for Windows simulators.
Run each simulator below in its own terminal window.
CWM Simulation Instructions
| Expand |
|---|
The CWM simulation can be run by opening a command prompt and changing to the ./sim directory in the ConnectWare Library distribution. The cwm.exe program takes three command line arguments. The first argument is the comport, the second argument indicates if the serial connection is full or half duplex, and the last parameter is the device ID of the simulated CWM. > cwm Arguments: cwm COM[0-9]* (FULL|HALF) <devId> Example : cwm COM8 FULL 0102030405060708 For example, to run the simulated CWM: > cwm COM20 FULL 1122334455667788 To access the command menu of the simulated CWM press <Enter>. Send Heartbeat, 'h'Pressing the 'h' key will cause the simulated CWM to generate and immediately send a heartbeat message to the OKC. Sending Ping, 'i'Pressing the 'i' key will cause the simulated CWM to generate and immediately send a ping request to the OKE. Change Baud Rate, 'b'Pressing the 'b' key will cause the simulated CWM to change the baud rate at which it is communicating to the OKE. By default, the CWM simulator uses a baud rate of 115200. The OKE must match the baud rate of the CWM otherwise no messages will be received by the CWM. Pause Outbound File Transfer, 'p'Pressing the 'p' key will cause the simulated CWM to pause or un-pause an outbound file transfer for both the simulated CWM and the OKE. Use this to test that OKE implementations process outbound file transfer pauses gracefully. An actual CWM will pause an OKE only if the outbound telemetry queue becomes too full. Toggle Net Connection, '1'Pressing the '1' key will cause the simulated CWM to have or not have a working network connection to the OKC. This option allows implementors to test how their controller behave when the network connection to the OKC is not working. Toggle Net Enable, '2'Pressing the '2' key will cause the simulated CWM to enable or disable the network connection to the OKE. Quit, 'q'Pressing the 'q' key will cause the simulated CWM to exit. Toggle Serial Debug Output, 'd'Pressing the 'd' key will cause the simulator to display the ingoing and outgoing serial data in hex format.
Strip off the r’s and T’s and convert the hex bytes to text. |
OKC Simulation Instructions
...
| Expand |
|---|
The CWL contains a full OKE Windows port and simulation. Implementors may use the OKE simulation to get familiar with the CWL and to experiment with creating heartbeat messages. The Visual Studio environment may be used to step through and debug the modified OKE simulation. Implementors may choose to modify the stock OKE simulator and create a full simulation of their specific equipment so that it is easier to test the integration with the OKC when certain states or errors conditions are time consuming or difficult to generate. The OKE simulation requires a serial port just like the CWM simulation, therefore the Windows PC needs two physical serial ports connected with a NULL modem cable to allow communication with each other. The OKE simulation can be run by opening a command prompt and changing to the ./sim directory in the ConnectWare Library distribution. The oke.exe program takes three command line arguments. The first argument is the comport, the second argument indicates if the serial connection is full or half duplex, and the last parameter is the device ID of the simulated OKE. > oke Arguments: oke COM[0-9]* (FULL|HALF) <devId> Example : oke COM8 FULL 0102030405060708 For example, to run the simulated OKE: > oke COM19 FULL 0102030405060708 To access the command menu of the simulated OKE press <Enter>. Send Heartbeat, 'h'Pressing the 'h' key will cause the simulated OKE to generate and immediately send a heartbeat message to the OKC. Request File, 'G'Pressing the 'G' key will cause the simulated OKE to generate and immediately send a file read request for file.bin to the OKC. If file.bin exists in the same directory as the OKC simulator then it will write the file back to the OKE, which will save the file as file.bin.oke. Send File, 'P'If file.bin exists in the simulated OKE directory, pressing the 'P' key will cause the simulated OKE to start a file write of file.bin to the OKC. The OKC will save the file as file.bin.okc. Request Scan, '1'Pressing the '1' key will cause the simulated OKE to send a command to the CWM to start a net scan. If the CWM supports scanning it will report the results of the scan within 10s. By default, the CWM simulator reports as a WiFi network, but it can be built for MiWi mode as well. Request Net Status, '2'Pressing the '2' key will cause the simulated OKE to send a command to the CWM to report net status. The CWM will report status immediately. By default, the CWM simulator reports as a WiFi network, but it can be built for MiWi mode as well. Config Custom WiFi Network, '3'Pressing the '3' key will cause the simulated OKE to send a command to the CWM to configure a custom WiFi network. You will be prompted to enter an SSID and PSK. The OKE must subsequently request status to verify if the configuration change was accepted. By default, the CWM simulator reports as a WiFi network, but it can be built for MiWi mode as well. Config Custom WiFi Network, '4'Pressing the '4' key will cause the simulated OKE to send a command to the CWM to configure WiFi SAP network. The OKE must subsequently request status to verify if the configuration change was accepted. By default, the CWM simulator reports as a WiFi network, but it can be built for MiWi mode as well. Config IP Network Settings, '5'Pressing the '5' key will cause the simulated OKE to send a command to the CWM to configure DHCP or static IP settings by prompt. The OKE must subsequently request status to verify if the configuration change was accepted. By default, the CWM simulator reports as a WiFi network, but it can be built for MiWi mode as well. Configure Provision Custom Endpoint, 'p'Pressing 'p' will prompt for a custom Provisioning endpoint URL or IP address. Pressing enter without a custom endpoint will return the endpoint to its default Open Kitchen endpoint. All three endpoints must be configured. Configure Push Custom Endpoint, '>'Pressing '>' will prompt for a custom Push endpoint URL or IP address. Pressing enter without a custom endpoint will return the endpoint to its default Open Kitchen endpoint. All three endpoints must be configured. Configure Pull Custom Endpoint, '<'Pressing 'p' will prompt for a custom Pull endpoint URL or IP address. Pressing enter without a custom endpoint will return the endpoint to its default Open Kitchen endpoint. All three endpoints must be configured. Request Next Custom Endpoint, 'c'Pressing ‘c' will cycle through displaying three endpoints and their string lengths. Length 0 indicates the endpoint is set to the default Open Kitchen endpoint Quit, 'q'Pressing the 'q' key will cause the simulated OKE to exit. |
...
The simulators were built using Microsoft Visual Studio Community 2019 with the C/C++ tools. At the top level ConnectWare directory https://github.com/Powerhouse-Dynamics/connectware there is a solution file called ConnectWare.sln that contains projects for the three simulators.
...
Normally implementors will not need to rebuild the OKC or CWM simulators since precompiled versions are included in the sim directory. However, some implementors may find it useful to use and extend the OKE simulator as a way to prototype and debug parts of their application code.
...