The Powerhouse-Dynamics ConnectWare 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.

The Simulators

OKC (Open Kitchen Cloud) Simulator

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 (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

cwm.exe is a software simulation of the physical ConnectWare Module that runs on a local computer using a terminal. The CWM sits in between the OKC simulator and the OKE or OKE Simulator. The simulated CWM and OKC communicate to each other via inter-process communication that simulates a network connection between them.

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:

Developer Scenario

Run the OKC and CWM simulators on a PC and connect the PC with a serial connection to a controller board. Use the setup instructions below for each simulator.

Demonstration Scenario

Run the OKC, CWM, and OKE simulators all on the same PC. The PC requires two serial ports connected with a NULL modem cable. Use the setup instructions below for each simulator.

Demonstration Setup

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

Tip: For greater debug flexibility use two RS485 cables to provide a convenient sniffing capability through a single computer serial terminal.

Simulator Software Location

All the simulation software cane 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.

CWM Simulation Instructions

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.

OKC Simulation Instructions

The OKC simulation can be run by opening a command prompt and changing to the ./sim directory in the ConnectWare Library distribution. The okc.exe program takes two command line arguments. The first argument is the device ID of the simulated CWM and the second argument is the device ID of the OKE system.

>okc

Arguments: okc <cwmId> <okeId>

Example : okc 1122334455667788 0102030405060708

For example, to run the simulated OKC:

>okc 1122334455667788 0102030405060708

To access the command menu of the simulated OKC press <Enter>.

Send Heartbeat , 'h', 'H'

This causes the OKC simulator to send a heartbeat request to either the OKE or CWM. When connected the command target will immediately send a heartbeat.

Send Reset, 'r', 'R'

This causes the OKC simulator to send a reset to either the OKE or CWM. When connected the command target will immediately reset.

Send Flush, 'f', 'F'

This causes the OKC simulator to send a flush to either the OKE or CWM. When connected the CWM will flush its queues, an OKE will perform an implementation specific action.

Send File Directory, 'd', 'D'

This causes the OKC simulator to send a file directory request to either the OKE or CWM. When connected the command target will immediately send a directory listing.

Send File Read, 'g', 'G'

This causes the OKC simulator to send a file read for source.bin to either the OKE or CWM. When connected the command target will immediately start writing source.bin back to the OKC which will store it as source.bin.okc.

Send File Write, 'p', 'P'

This causes the OKC simulator to send a file write of source.bin to either the OKE or CWM. When connected the command target will immediately receive the file and save it appropriately.

Send File Delete, 'x', 'X'

This causes the OKC simulator to send a file delete to either the OKE or CWM. When connected the command target will immediately delete the requested file.

Send Set Time, 't', 'T'

This causes the OKC simulator to send a set time message to either the OKE or CWM. When connected the command target will immediately set their time as requested.

Send Ping, 'i', 'I'

This causes the OKC simulator to send a ping message to either the OKE or CWM. When connected the command target will immediately send a matching ping message.

Quit, 'q'

Pressing the 'q' key will cause the simulated OKC to exit.

OKE Simulation Instructions

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.

Quit, 'q'

Pressing the 'q' key will cause the simulated OKE to exit.

Building Custom Simulators on Windows

The simulators were built using Microsoft Visual Studio Community 2019 with the C/C++ tools. At the top level 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.

To build the OKE simulator right click on the _OpenKitchenEquipment_OKE project in the Solution Explorer pane and click Set as StartUp Project. To change the default command line parameters, go to Project->Properties->Debugging and modify the Command Arguments field. On the toolbar you can launch the debugger by clicking the Local Windows Debugger option.

Debugging Simulators

The Simulators

OKC (Open Kitchen Cloud) Simulator

OKC Sim Use Cases

CWM (ConnectWare Module) Simulator

CWM Sim Use Cases

OKE (Open Kitchen Equipment) Simulator

There are two typical simulation scenarios:

Developer Scenario

Demonstration Scenario

Simulator Software Location

CWM Simulation Instructions

Send Heartbeat, 'h'

Sending Ping, 'i'

Change Baud Rate, 'b'

Pause Outbound File Transfer, 'p'

Toggle Net Connection, '1'

Toggle Net Enable, '2'

Quit, 'q'

OKC Simulation Instructions

Send Heartbeat , 'h', 'H'

Send Reset, 'r', 'R'

Send Flush, 'f', 'F'

Send File Directory, 'd', 'D'

Send File Read, 'g', 'G'

Send File Write, 'p', 'P'

Send File Delete, 'x', 'X'

Send Set Time, 't', 'T'

Send Ping, 'i', 'I'

Quit, 'q'

OKE Simulation Instructions

Send Heartbeat, 'h'

Request File, 'G'

Send File, 'P'

Request Scan, '1'

Request Net Status, '2'

Config Custom WiFi Network, '3'

Config Custom WiFi Network, '4'

Config IP Network Settings, '5'

Quit, 'q'

Building Custom Simulators on Windows

Related pages