IOx MQTT GPIO Control

IOx MQTT GPIO Control is a sample application for Cisco IW9165E IOx devices. It listens to MQTT topics to remotely control host digital I/O (DIO1/DIO2) and the host CPU low‑power mode, and comes with a browser‑based Web UI for testing and demos.

Project Overview

• What is it?

  • An IOx container application that subscribes to and publishes a small set of MQTT topics to:
    • Turn DIO1/DIO2 on or off for IW9165E.
    • Change the host CPU power state (ACTIVE / LSLEEP / DSLEEP) for IW9165E.
    • Periodically publish the current DIO/power state to status topics so that upstream systems can monitor the device.
  • A minimal Web UI in src/mqtt-webui/ that connects to the MQTT broker via WebSocket and exposes buttons to send control commands and display online devices and their status.

• Main components

  • IOx application container: under src/iox/docker/; mqtt_sub.py consumes MQTT messages, drives /dev/dio-* and /mnt/host_cpu/low_power_mode, and publishes status.
  • MQTT broker: e.g. Mosquitto, used by the IOx app over TCP (1883) and optionally to expose a WebSocket listener for the Web UI.
  • Web UI: under src/mqtt-webui/; connects to the broker via WebSocket, provides buttons to control DIO1/DIO2 and Host CPU, and shows online clients and their status.

Quick Start

1. Download and prepare ioxclient:

   • Download the latest ioxclient binary from the Cisco IOx Resource Downloads page for your platform.
   • Copy the ioxclient executable into the src/iox directory, rename it to ioxclient if needed, and ensure it is executable (for example chmod +x ioxclient).
   • From inside src/iox, run ./ioxclient config and configure the connection to your IOx device.

2. Build the IOx Docker image:

   cd src/iox
   ./build-docker-image.sh

3. Get the IOx application package (package.tar):

   • Recommended for most users: download the prebuilt package.tar from the GitHub Releases page for this repository, and place it in the src/iox/build directory as package.tar.

   • Alternative (developers only): build it locally by running the packaging script:

      cd src/iox
      ./package-iox-tarball.sh

4. Configure the MQTT broker IP used by the app:

   • Edit src/iox/appdata/MQTT_BROKER_IP and put the broker IPv4 address on a single line (no port).

5. Install, activate, and start the IOx app on your device:

   cd src/iox
   ./install-iox-app.sh

6. (Optional) Use the Web UI to send MQTT control messages:

   • Go to src/mqtt-webui/.
   • Edit config.js so host and port match your broker WebSocket listener.
   • Serve the folder over HTTP (for example python3 -m http.server 8000).
   • Open http://localhost:8000 in a browser and use the buttons to toggle DIO1/DIO2 and host CPU sleep states.

For a more detailed explanation of topics and payloads, see the comments in iox/docker/mqtt_sub.py and the dedicated guide in src/mqtt-webui/README.md.

Contributing

Contributions are what make the open source community such an amazing place to
learn, inspire, and create. Any contributions you make are greatly
appreciated. For detailed contributing guidelines, please see
CONTRIBUTING.md

License

Distributed under the Apache License. See LICENSE for more
information.

Contact

Yaojun Wei - yaojwei@cisco.com

Project Link:
https://github.com/CiscoDevNet/iox-mqtt-gpio-ctrl

Acknowledgements

This template was adapted from
https://github.com/othneildrew/Best-README-Template.