Third Party Example Server Implementation

Owned by Ricky Goldfarb
Last updated: Nov 22, 2024 by Andrew Stokinger
4 min read

By request, implementors wanting to create a custom endpoint server are provided source code for a sample TPS (Third Party Server) implementation that can successfully interface with a CWM and OKE. The source code files are in the ./tps directory of the https://github.com/Powerhouse-Dynamics/connectware/tree/master

The example server implementation is written in Python using the Flask framework. The Waitress package provides a WSGI interface to the NGINX web server.

The following lists the general steps necessary to run the server example:

  1. Launch a server instance running Linux (such as a recent Debian distribution)

  2. As necessary open TCP port 443 on the server instance.

  3. Install NGINX

sudo apt install nginx

  1. Install Python 3

sudo apt install python3

  1. Install Flask and supporting Python packages. For convenience, a copy of the get-pip.py installer script is included in the tps directory.

python3 get-pip.py

pip install -U Flask

pip install waitress

  1. Create a self-signed Server SSL certificate (cert.pem) and key (key.pem)

openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -days 365 -nodes

  1. Create an tps directory and copy the following files to that directory: key.pem, cert.pem, app.py, cwcrc16.py

  2. Copy the file "default" to /etc/nginx/sites-enabled and edit so that the ssl_certificate and ssl_certificate_key paths to cert.pem and key.pem are correct, and the server_name value reflects the DNS name associated with the server.

  3. Restart NGINX

sudo /etc/init.d/nginx restart

10.   Run the OK server example in a terminal window.

python3 app.py

 11. Using a browser enter the following URL https://dnsnameofyourserver/pull

The browser will issue a server certificate warning, accept the server certificate. If the server is setup successfully then the browser will display {"pull":false}.

  1. From an OKE configure the 3 custom endpoints with the DNS name of the server. The CWM will begin communicating with the server, and output will be displayed on the terminal window running the app.py service.

The server's /pullform URL allows a message to be queued and sent to a CWM. For example, if your CWM device ID is 0002010203040506 and the OKE device ID is 1122334455667788 then enter ["1122334455667788","0002010203040506"] into the _dst field. The device IDs must match your CWM and OKE otherwise the message will not be processed. Enter in a message in the _pld field, for example {"cmd":{"relay":1}}. Enter either wr or rd in the _cmd field depending on if the command is a write or a read operation. Press submit to queue the request. The next time the CWM pushes data to the server, the server will indicate that a message is queued, and the CWM will pull the message and process it.

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 OKEs. It is the responsibility of the implementor to create a production system that can manage communications with large numbers of CWMs and OKEs.

For file transfer endpoints, the files must exist in the tps directory. The files referenced in app.py are simply random data and can be recreated using dd, for example:

dd if=/dev/random of=file1023.bin count=1023 bs=1

will create a 1023 byte file names file1023.bin.

 CWM2 Configuration

Note: The CWM2 firmware must be at version 130 or later before proceeding with any configuration described in this section. Earlier versions of firmware will not work as expected if configured to communicate with custom server endpoints.

Using the OKE Simulator , or an OKE device the CWM custom endpoints can be configured over a USB or serial connection. Please update to the latest version of the OKE simulator in the Connectware repository, this version will have the ability to configure Custom Endpoints enabled by default.

When custom endpoints are configured, the CWM will no longer communicate through a SAP. It's WiFi configuration must be set manually, or the Ethernet connection can be used.

Use the OKE Simulator '3' command to set a custom WiFi network configuration, or plug in the Ethernet cable to use Ethernet.

The OKE Simulator 'c' command iterates over and requests the currently configured custom endpoint settings one at a time. Only when all three custom endpoints are configured will the CWM2 attempt to communicate to the TPS server.

The OKE Simulator 'p', '>', and '<'commands allow the configuration of the provision, push, and pull endpoints. When using the TPS example all the endpoints will have the same configuration. The configuration should be the DNS name or IP address of the TPS server without any decoration, paths, or arguments. For example, a valid endpoint would be:

tps.mycompany.com or 192.168.2.100

Invalid configurations include: "https://tps.mycompany.com" , "tps.mycompany.com/servlet", "tps.mycompany.com?redirect=true", or any combination of additional decoration, paths, or arguments to the DNS name.

Once the Custom Endpoints are configured the CWM can now be physically connected to the OKE. If the OKE port and baud rate settings differ from the OKE Simulator used for Custom Endpoint configuration then the TPS server must send a Port command to the CWM after it connects to the TPS server. The Port command must have the correct Port configuration for the OKE to which the CWM is communicating. For example, if the OKE simulator used a USB CDC connection and the OKE uses the RS232 interface at 115200 baud then the following Port command must be sent as _pld to the CWM from the TPS server’s /pullform form:

{"oke":{"port":"232","baud":115200}}

Other valid values for port are "usb", "ttl", and "485".

_cmd must be wr.

_dst must be ["CWMDEVID"], where CWMDEVID is the actual Device ID of the CWM.

If you used the simulator with a USB cable connection to the CWM, it will have saved “usb” as the port setting to the CWM. If you used a custom RS232 cable, it would have saved “232” as the port. A common issue is when the cable used for the simulator doesn’t match the equipment’s cable.