QuickStart Process Outline

This User Guide has a tremendous amount of valuable information about properly porting and using the CWL.

It is strongly recommended that implementors read or at least skim this section and the rest of the document before using the library.

If not, implementors should at least read this section and refer to the rest of the User Guide when more information is needed.

Contact Powerhouse Dynamics at connectware@powerhousedynamics.com to setup credentials for the ConnectWare read only Git repository https://github.com/powerhousedynamics/connectware

We recently moved the ConnectWare repo from Beanstalk to GitHub. If you had access to the Beanstalk repo, your email address will be automatically registered to the GitHub repo. If you would like the email address associated in the GitHub repo changed, please contact us at the email address above.

2. Clone the repository and checkout the latest tagged version:

$ git clone https://github.com/powerhousedynamics/connectware

Cloning into 'connectware'...

remote: Counting objects: 538, done.

Remote: Compressing objects: 100% (517/517), done.

Remote: Total 538 (delta 312), reused 0 (delta 0)

Receiving objects: 100% (538/538), 43.18 MiB | 631.00 KiB/s, done.

Resolving deltas: 100% (312/312), done.

$ cd connectware/

$ git tag

1.0.0

1.0.1

….

1.0.15

1.0.16

$ git checkout -b 1.0.16 1.0.16

Switched to a new branch '1.0.16'

OKE implementors should use the latest tagged version.

This document contains detailed release notes for each tagged version and information about upgrading from earlier versions to the newer versions.

3. Add the core CWL source files to your platform project.

From the ./lib directory:

cwassert.h, cwcrc16.c, cwcrc16.h, cwdll.c, cwdll.h, cwnwk.c, cwnwk.h, mjson.c, mjson.h, cwver.h

From the ./_OpenKitchenEquipment_OKE directory:

cwcmd.c, cwcmd.h, cwmsg.c, cwmsg.h

Implementors should not modify any of these files.

4. Add the port specific source files to your platform project.

From either the ./_OpenKitchenEquipment_OKE/ports/windows or ./_OpenKitchenEquipment_OKE/ports/linux directory copy the following files: cwport.c, cwport.h, cwmsgsel.h, and optionally strlcpy.c if your platform does not natively support strlcpy().

Embedded platforms will start their port using either the Windows or Linux port as a baseline.

Carefully read the instructions contained in cwport.c and cwport.h and modify either the Windows or Linux specific implementation to work on your controller.

When not using a Windows or Linux toolchain, it is expected that some or all the Windows or Linux specific header files in cwport.c and cwport.h must either be commented out or replaced by platform specific ones to get the CWL to compile.

For the initial port, it is recommended to set CW_PORT_INVALID_OKM_HARD_ERROR to 1 and CW_PORT_IS_FILE_SUPPORT_ENABLED to 0 in cwport.h. This will minimize the number of functions that must be implemented to get the first port working.

A successful port will only require changes to cwport.c and cwport.h.

It is strongly recommended that MJUnitTest() is run to verify that the JSON library is working correctly on the target platform.

If you have previously ported the CWL successfully and are updating to the newer version of the CWL then merge your existing cwport.c and cwport.h files with the newer versions of those files. For cwport.c if the function signatures match it is generally safe to bring over your existing code without modification, however care should be taken to follow any new porting guidelines for those functions. For cwport.h make sure to bring over your port configuration settings and configure any new settings as appropriate for your system.

5. Initialize and run the CWL task.

Call CWPortInitTask(), and then from the main loop or dedicated task/thread periodically call CWPortTask().

Refer to ./_OpenKitchenEquipment_OKE/ports/windows/main.c for an example of how to initialize and call the ConnectWare Library from your main() function.

See CWL Task for a detailed explanation of how to properly invoke CWPortInitTask() and CWPortTask().

6. Test the port by connecting to a simulated CWM and OKC.

Connect the controller to a serial port on a Windows PC. Run the cwm.exe and okc.exe programs included with the CWL sources.

The simulated CWM and OKC allow you to test the port running on the controller.

7. Debug the CWL port before connecting to a hardware-based CWM and OKC.

The simulated CWM and OKC will make it much easier to debug the CWL port than connecting to the real system.

Review the implementation sanity checklist included towards the end of this document.

After debugging ask for a code review of your cwport.c/h files before moving to the next step.

Our goal is that the CWL compiles cleanly without warnings or errors on all toolchains. If any warnings or errors are encountered that require changes to core CWL files, then please report it to the maintainers.