Virtual ConnectWare Module Service

Some OKE platforms have desktop class hardware, built in Ethernet and/or WiFi interfaces, and run either embedded Linux or Android. These platforms have the option to use a software-only Virtual ConnectWare Module (VCWM), rather than a physical ConnectWare Module (CWM).

Use cases where a VCWM has a significant advantage versus a physical CWM:

1. Frequently (more than once per day) transferring extremely large files (>10MB). The VCWM will be able to transfer the files much faster than a physical CWM.

2. Retrofitting existing products with OpenKitchen compatibility. A software update can deploy the VCWM, without having to install physical CWMs.

3. Driving down the cost to deploy OpenKitchen compatibility. The VCWM software adds zero additional BOM costs.

OKE Compatibility

From the perspective of an OKE implementor, there is no difference between supporting a physical CWM or a VCWM.

In other words, an OKE implementation requires no changes to support the VCWM.

An OKE communicates to a CWM via a physical serial port, and to the VCWM over a virtual serial port. Likewise, when the OKE configures network settings, the VCWM will manages the appropriate Linux or Android system networking configuration. A properly implemented OKE should be able to easily use either a physical CWM or a VCWM with no software changes other than communication port selection.

Virtual ConnectWare Source Code

VCWM is written in C and distributed as source code. It is maintained in its own git repository separate from the CWL. For access to the VCWM repository contact the CWL maintainers directly.

Memory and CPU Utilization

Compared to the resources available on the embedded Linux and Android platforms where VCWM is targeted, the VCWM service will only use a tiny (<1%) amount of system resources, such as CPU, RAM, and disk space. It should not impact the UI responsiveness of integrated touchscreen displays, or in any other way affect the performance of the equipment.

System Compatibility

The first releases of VCWM only supported embedded Linux running systemd's systemd-networkd with an Ethernet network interface. The latest VCWM release also supports WiFi network interfaces with or without a SAP. The WiFi/SAP functionality additionally requires the systemd's wpa_supplicant and systemd-resolved components.

Building the VCWM Executable

The VCWM source code includes a shell script to build the VCWM executable. The build script requires that the toolchain be passed as an argument. This allows simple cross compilation.

Packages required to build VCWM for an embedded Linux distribution:

1. libcurl4-openssl-dev – Used for web service requests between the VCWM and OKC.

2. sqlite3, libsqlite3-dev – Used to implemented store and forward queue functionality.

 The output is the vcwm executable file.

The CWL maintainers strive to have a clean compile without any warnings. However, due to the sheer number and constant flux of different cross toolchains, warnings or errors might occur. If they do, please contact the CWL maintainers to address the problem and update the repository with a fix.

Embedded Linux Implementation Requirements

 Runtime requirements to execute a VCWM daemon.

1. The host system SHALL provide a user interface to the end user that "Resets to Defaults" the VCWM service. The host SHALL perform a "Reset to Defaults" by erasing all VCWM configuration files *.config from the configDir specified in the VCWM configuration file and restarting the VCWM service.

2. The embedded Linux distribution uses systemd to configure and manage either its Ethernet or WiFi interface. Specifically, the VCWM service minimally requires systemd-networkd and systemd-resolved for Ethernet. For WiFi/SAP support systemd's wpa_supplicant is also required. Other network management services such as NetworkManager must be disabled and stopped to prevent network configuration contention. Only the VCWM service must be managing the network interfaces on the OKE. It is possible to run the VCWM with alternative services or on platforms other tham Linux, but that may require additional porting and integration work on the part of the OKE implementor.

3. The embedded Linux distribution has libsqlite3 at runtime and libsqlite3-dev for building.

4. The embedded Linux distribution has libcurl at runtime and libcurl-dev for building.

OKE implementors building and running the VCWM are responsible for determining the correct options and build procedures for their platform.

5. The embedded Linux distribution has libpthread at runtime and libpthread-dev for building.

6. The embedded Linux distribution has libnl-3 and libnl-genl-3 at runtime for VCWM versions supporting WiFi and SAP. libnl-3-dev and libnl-genl-3-dev is required for building.

7. The embedded Linux distribution supports ptys.

8. The embedded Linux distribution supports the /sys filestsyem interface.

9. A way to make the vcwm executable a Linux daemon, such as using systemd to run and manage a VCWM service. The daemon wrapper SHALL automatically restart the VCWM service if it stops running. The latest version of the VCWM service implements network recovery procedures that will terminate the VCWM service with the expectation that the service manager will automatically restart it.

10. A local file system location for the sqlite store and forward database, which can persist through cold and warm boots. Ideally this location is in its own disk partition to prevent potential corruption or memory exhaustion of the main image partition, and to set a hard limit to the maximum size of the database. Network filesystem locations are not supported.

11. A valid VCWM configuration file.

12. A certificate directory with the VCWM certificate files which must be requested from the Powerhouse development team.

13. The VCWM service will maintain the system time. NTP and other automatic time service daemons should be disabled when the VCWM service is running.

Android Implementation Requirements

TBD

VCWM Configuration File

The VCWM executable takes a single command line argument, the full path to its configuration file. The configuration file must only contain a syntactically valid JSON object. This section details the optionsthat can be declared in the configuration file. A sample configuration file, vcwm.json is included in the repository.

Model ID

The modelId option is required. The string value is the model ID of the VCWM integrated into a specific OKE. Please contact the Powerhouse development team to be assigned a model ID.

Temporary Directory

The tmpDir option is required. The string value is a fully qualified path to the system's tmp directory, usually a RAM backed filesystem.

Configuration Directory

The configDir option is required. The string value is a fully qualified path to the directory where the VCWM services configuration files will be read and written. This should be in a non-volatile disk partition. The VCWM service does not write to its configuration files frequently and they use only a tiny amount of disk space.

Certificate Directory

The certificateDir option is required. The string value is a fully qualified path to the directory containing the SSL certificates used by the VCWM service. The certificate directory must contain the contents of the certs/ directory of the repository. These include ca.crt, device-cw_mfg.crt, device-cw_mfg.key, and gd_bundle-g2-g2.crt.

Store and Forward Database Directory

The databaseDir option is required. The string value is a string s the fully qualified file system directory where the database file sill be stored. It is strongly recommended that the database directory is mapped to its own local disk partition.

The size of the partition should be set so that the maximum number of telemetry and priority messages can be stored with additional room to account for wear leveling and bad blocks. For comparison, a physical CWM can store about 29,000 telemetry messages.

Store and Forward Maximum Telemetry Messages

The maxTelemetryQueueSize option is required. The value is an integer which sets the maximum number of telemetry messages stored in the database. If the VCWM is not in communication with the OKC, the database will start filling up with telemetry messages. If the VCWM connects to the OKC before it hits the maximum, then no telemetry messages will be lost. However, if the VCWM does not connect to the OKC for a very long time, then the database will reach the maximum number of telemetry messages, and the oldest telemetry message will be purged each time a new telemetry message is stored.

Store and Forward Maximum Priority Messages

The maxPriorityQueueSize option is required. The value is an integer which sets the maximum number of priority messages stored in the database. If the VCWM is not in communication with the OKC, the database will start filling up with priority messages. If the VCWM connects to the OKC before it hits the maximum, then no priority messages will be lost. However, if the VCWM does not connect to the OKC for a very long time, then the database will reach the maximum number of priority messages, and the oldest priority message will be purged each time a new priority message is stored. Priority messages are purged when the VCWM service starts. A value of 300 is more than sufficient for the priority queue.

Store and Forward Maximum Inbound Messages

The maxInboundQueueSize option is required. The value is an integer which sets the maximum number of inbound messages stored in a RAM queue. Use the recommended value of 40.

OKE Comport

The okeCommFilename option is required. The string value is a string is a fully qualified file path name for the virtual serial port device that the OKE will connect to.

For example, if the string is /tmp/okecomport then when the VCWM service starts it will create a comport device with the name /tmp/okecomport. The OKE will initialize its CWL using the same comport device, /tmp/okecomport. The VCWM service will be able to receive and transmit messages with the OKE over the virtual comport. The virtual comport is an Inter Process Communication (IPC) mechanism that operates much faster than a physical comport. The device file is created by the VCWM service, so only the file directory path must exist when the VCWM service starts.

The order in which the OKE and VCWM boots is not critical. If the OKE boots before the VCWM, then it will be unable to open the comport, but it will keep trying. Once the VCWM boots and creates the OKE serial port device, the OKE will automatically open it and start communicating with the VCWM. Conversely, if the VCWM boots first then the OKE's comport will exist when the OKE boots up. Anytime the VCWM restarts the comport device is reinitialized, and the OKE will automatically detect a fault and reopen the comport.

It is recommended to use a RAM backed filesystem, such as /tmp as the directory path for the comport, so that it will get cleaned up on every system restart.

Device ID Network Interface

The deviceIdMacFromNetworkInterface option is required. The VCWM will use the MAC address of this network device to generate the VCWM's Device ID. Since the Device ID should not change for the entire lifetime of the OKE device the ideal network interface to choose would be one physically embedded in the OKE such as Ethernet.  A USB WiFi device would be a bad choice since if it is replaced the Device ID will change and the OKE will no longer be manageable. The VCWM will not use this network interface for any communications.The Device ID of the VCWM service will be generated by concatenating "0003" to the MAC address returned by reading /sys/class/net/[netdev]/address with the colons removed.

It is the responsibility of the OKE implementor to ensure that the network interface is always assigned the same device name so that the device is always present when the VCWM starts.

Active Network Interface

The networkInterface option is required. The string value is the device name (without any path) of the active network interface. Only Ethernet or 802.11 WiFi devices are supported. Other network device types will cause the VCWM to assert. If an OKE has multiple network interfaces only one may be active at any time. The other inactive network interfaces should be completely disabled. Enabling and disabling network interfaces is the responsibility of the OKE implementor and is not handled by the VCWM service.

It is the responsibility of the OKE implementor to ensure that the network interface is always assigned the same device name so that the device is always present when the VCWM starts.

To determine if the network device is Ethernet or WiFi the VCWM service will read the /sys/class/net/[netdev]/type file. If it returns a value other than 1 then the network device type is not supported. If the /sys/class/net/[netdev]/wireless directory and /sys/class/net/[netdev]/phy80211 symbolic link exist then the network device is WiFi, otherwise it is Ethernet.

systemd Network Configuration File

The systemdNetworkConfFilename option is required. The string value is the full path to the system network configuration file. When running the VCWM service will take over management of this configuration file. When the OKE makes IP configuration requests this configuration file will be updated, and the network service restarted.

systemd Network Restart Command

The systemdNetworkRestartCmd option is required. The string value is the command to restart the network interface.

systemd WPA Supplicant Configuration File

The systemdWpaSupplicantConfFilename option is required only when the active network interface type is WiFi. The string value is the full path to the system WPA supplicant configuration file for the specific WiFi interface. For example, if the active WiFi interface is wlx10feed272f84 then the configuration file name should be /etc/wpa_supplicant/wpa_supplicant-wlx10feed272f84.conf. When running the VCWM service will take over management of this configuration file. When the OKE makes WiFi configuration requests this configuration file will be updated, and the WPA Supplicant service restarted.

systemd WPA Supplicant Restart Command

The systemdNetworkRestartCmd option is only required when the active network interface type is WiFi. The string value is the command to restart the WPA supplicant interface. For example, if the active WiFi interface is wlx10feed272f84 then the restart command should be systemctl restart wpa_supplicant@wlx10feed272f84.service.

Trace Options

All trace options are optional in the configuration file. When trace is enabled the VCWM service will print trace to stdout. Usually, trace is enabled when the VCWM service is running manually at a command prompt.

The isTraceEnabled boolean option globally enables or disables all trace output.

The isTraceProvEnabled boolean option globally enables or disables provisioning trace output.

The isTraceProvHTTPEnabled boolean option globally enables or disables provisioning HTTP trace output.

The isTraceProvSapEnabled boolean option globally enables or disables SAP provisioning trace output.

The isTraceProvSapHTTPEnabled boolean option globally enables or disables SAP provisioning HTTP trace output.

The isTracePushEnabled boolean option globally enables or disables push trace output.

The isTracePushHTTPEnabled boolean option globally enables or disables push HTTP trace output.

The isTracePullEnabled boolean option globally enables or disables pull trace output.

The isTracePullHTTPEnabled boolean option globally enables or disables pull HTTP trace output.

The isTraceTimeEnabled boolean option globally enables or disables time trace output.

The isTraceTimeHTTPEnabled boolean option globally enables or disables time HTTP trace output.

The isTraceDatabaseEnabled boolean option globally enables or disables database trace output.

The isTraceWiFiScanEnabled boolean option globally enables or disables WiFi scan trace output.

Assertions

Regardless of trace configuration settings, when the VCWM service has a fatal error, it will generally assert and exit. Assertions are printed to stdout and written to a file called vcwmAssert.log in the tmp directory. Looking at this log file will provide much insight as to why the VCWM service is not running as expected.

Example Configuration File