Connectware Edge Server Guide
How to build an Edge Server or Third Party server for your Connectware enabled Equipment
In Connectware you do not call device, Device calls YOU!
A quick review of thehttps://sitesage.atlassian.net/wiki/x/DIBcRQ will show you that there is a one directional arrow from the Connectware Module to the server. For security, Connectware was designed with a pull based architecture. There are no APIs available and no open ports on Connectware enabled equipment. Instead, the Connectware Module calls APIs at preconfigured URLs or IP addresses, and receives instructions in the response. At least one ‘heartbeat’ call is made every minute.
To use data from your Connectware device in real time inside the same building as your equipment, you will need to:
Host four APIs from a local server
Configure each Connectware module to point to those APIs
Building Connectware APIs on your Server
The four required end points are Push, Pull, Provision and Time. Their implementation is defined in https://sitesage.atlassian.net/wiki/x/AQBWMw.
/provision: This returns the security certificates to the module. The module does not begin calling other endpoints without a certificate.
/push: This is where the CWM will push its data, both telemetry and core heartbeats. If this API response contains ”pull”: true, then the module will call the pull API.
/pull: This API is for delivering commands to the CWM. The CWM will continue hitting the pull endpoint until it receives a ”pull”: false.
/time: The CWM will call this automatically to update it’s clock. It acts as a NTP service.
Edge Server Example
There is a Python example server https://sitesage.atlassian.net/wiki/x/HwBYHQ
The example only implements what is necessary to allow a CWM to successfully communicate to a custom server. The example server does not process telemetry or provide any administration of CWMs or Equipment.
Configuring Connectware Modules to use an Edge Server
To make the Connectware Module call your Edge server instead of Open Kitchen, the endpoints will need to be configured on the module. Those will cause the HTTPS communication to be redirected to servers other than the Open Kitchen Cloud.
Note: API Endpoint configuration is only available on the Connectware 2 Module or greater.
While it is possible to configure a Connectware Module over USB https://sitesage.atlassian.net/wiki/x/EwBiRQ , the suggested method is to use the Open Kitchen Install mobile app, available on both iOS and Android.
Custom Endpoint Configuration Process Using the Open Kitchen Install App:
Power up the module, either connected to the equipment, or using a Connectware Dock and a USB cable adapter.
Select “Configure Network Settings” from the menu
Follow the instructions to put your Module into “Access Point Mode” (AP Mode)
Connect your mobile device to the Connectware WiFi network
Return to the App and follow the prompts.
The custom endpoints are the base URL or IP address of where you hosted your APIs. The module will add “/push” to that URL. It is common to set all three endpoints to the same URL or IP address.
Provisioning
Connectware will communicate over HTTPS to the server endpoints configured in the Connectware module. For a server to validate the Connectware message, the server can provide a certificate to the Connectware Module. This is done through provisioning:
https://sitesage.atlassian.net/wiki/x/HQDyRQ
Provisioning: Getting settings from the Open Kitchen Cloud
Out of the box, the Connectware Module is designed to use the Open Kitchen Cloud to get it’s settings. If not configured and when connected to the Internet, the module will call the /provision API on the Open Kitchen Cloud to get settings, which can include endpoints, wifi configurations and security keys. The Open Kitchen Cloud will also validate security keys and confirm the module was manufactured by Powerhouse Dynamics and not an intruder.
If you are interested in registering your Connectware Modules and automating your configuration step, please reach out to your sale rep or Powerhouse Dynamics Support. This does require a cloud license, but can support disaster recovery and credential rotation while keeping your data private.
Interpreting Data Sent from a Connectware Device
Connectware specifies that data is sent using JSON with a series of reserved key at the top level, but allows any shape nested JSON payload.
https://sitesage.atlassian.net/wiki/x/BQB0HQ
To help your cloud understand the data coming from different models, Manufacturers implementing Connectware will create a Data Dictionary which maps their payload to human readable names, values, and data types.