Global Caché integration for Unfolded Circle Remotes

Unfolded Circle Remote integration driver for Global Caché devices.

Supported devices using the Unified TCP API:

• GC-100
• iTach
• Flex
• Global Connect

Supported features:

• IR sending

Relay control and serial features are planned.

This integration driver is included in the Unfolded Circle Remote firmware and does not need to be run as external integration to use Global Caché devices as IR emitters. A standalone driver can be used for development or custom functionality.

The integration implements the UC Remote Integration-API which communicates with JSON messages over WebSocket.

Standalone usage

Setup

Requirements:

• Remote Two firmware 1.9.3 or newer with support for new IR-emitter entity.
• Install nvm (Node.js version manager) for local development.
• Node.js v20.16 or newer (older versions are not tested).
• Install required libraries:

npm install

For running a separate integration driver on your network for UC Remotes, the configuration in file driver.json needs to be changed:

• Set driver_id to a unique value, uc_gc_driver is already used for the embedded driver in the firmware.
• Change name to easily identify the driver in discovery & setup with the Remote or the web-configurator.
• Optionally add a "port": 8090 field for the WebSocket server listening port.
  • Default port: 9090
  • Also overrideable with environment variable UC_INTEGRATION_HTTP_PORT

Run

Run as external integration driver:

UC_CONFIG_HOME=. UC_INTEGRATION_HTTP_PORT=8079 node src/driver.js

The configuration file is loaded & saved from the path specified in the environment variable UC_CONFIG_HOME.

Logging

Logging any kind of output is directed to the debug module. To let the integration driver output anything, run the driver with the DEBUG environment variable set like:

DEBUG=uc_gc:* node src/driver.js

The driver exposes the following log-levels:

Log namespaces:

• uc_gc:debug: debugging messages
• uc_gc:info: informational messages like server up and running, device connected or disconnected
• uc_gc:warn: warnings
• uc_gc:error: errors

If you only want to get errors and warnings reported:

DEBUG=uc_gc:warn,uc_gc:error node src/driver.js

The Global Caché communication library and the Unfolded Circle Integration-API library are also using the debug module for logging:

• gc-unified-lib log namespaces
  • Enable device socket message trace: gclib:msg
• Node.js API wrapper log namespaces
  • Enable WebSocket message trace: ucapi:msg

Gotchas

• Don't use DHCP for Global Caché devices, since they frequently get a new IP address after power loss!
  • Configure a static IP address to improve connectivity issues.
• GC-100 only allows one TCP connection!
  • iTach, Flex and Global Connect devices support 8 TCP connections.
• GC-100 doesn't seem to support TCP keep-alive option.

Versioning

We use SemVer for versioning. For the versions available, see the tags and releases in this repository.

Changelog

The major changes found in each new release are listed in the changelog and under the GitHub releases.

Contributions

Please read our contribution guidelines before opening a pull request.

License

This project is licensed under the Mozilla Public License 2.0. See the LICENSE file for details.