{"id":49687010,"url":"https://github.com/thin-edge/tedge-ctrlx-os","last_synced_at":"2026-05-07T10:40:59.819Z","repository":{"id":353307748,"uuid":"1218722059","full_name":"thin-edge/tedge-ctrlx-os","owner":"thin-edge","description":"WIP: thin-edge.io app for Bosch CtrlX OS","archived":false,"fork":false,"pushed_at":"2026-05-04T12:07:06.000Z","size":1555,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-04T13:34:45.271Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/thin-edge.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-23T06:40:22.000Z","updated_at":"2026-05-04T11:54:42.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/thin-edge/tedge-ctrlx-os","commit_stats":null,"previous_names":["thin-edge/tedge-ctrlx-os"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/thin-edge/tedge-ctrlx-os","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thin-edge%2Ftedge-ctrlx-os","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thin-edge%2Ftedge-ctrlx-os/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thin-edge%2Ftedge-ctrlx-os/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thin-edge%2Ftedge-ctrlx-os/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/thin-edge","download_url":"https://codeload.github.com/thin-edge/tedge-ctrlx-os/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thin-edge%2Ftedge-ctrlx-os/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32734382,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-07T02:14:30.463Z","status":"ssl_error","status_checked_at":"2026-05-07T02:14:29.405Z","response_time":62,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-05-07T10:40:59.012Z","updated_at":"2026-05-07T10:40:59.809Z","avatar_url":"https://github.com/thin-edge.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# thin-edge.io for ctrlX AUTOMATION (WORK IN PROGRESS)\n\n[![Version](https://img.shields.io/badge/version-2.0.0-blue)](https://github.com/thin-edge/tedge-ctrlx-os)\n[![License](https://img.shields.io/badge/license-Apache%202.0-green)](LICENSE)\n[![Architecture](https://img.shields.io/badge/arch-amd64%20%7C%20arm64-lightgrey)](https://github.com/thin-edge/tedge-ctrlx-os)\n\n## Overview\n\nThis is a **ctrlX AUTOMATION** snap app that packages [thin-edge.io](https://thin-edge.io) — the open-source, cloud-agnostic IoT edge framework. It enables ctrlX CORE and ctrlX COREvirtual devices to securely connect to major IoT cloud platforms and provides a built-in web UI for configuration and monitoring.\n\n## Features\n\n- **Multi-Cloud Connectivity** — Cumulocity IoT, AWS IoT Core, Azure IoT Hub\n- **Web-Based Configuration UI** — Browser-accessible dashboard served directly from the device\n- **Device Management** — Remote monitoring, configuration management\n- **Log Management** — Centralized log collection with live viewer in the web UI\n- **MQTT Bridge** — Efficient local and cloud messaging via Mosquitto\n- **ctrlX Data Layer Bridge** — Bridge service reads ctrlX Data Layer nodes and publishes them to MQTT/cloud\n- **ctrlX License Enforcement** — Acquires and periodically re-checks ctrlX OS license via Unix socket; shows warning banner when license is missing\n- **Health Monitoring** — Integrated watchdog service with automatic service recovery\n- **Strict Snap Confinement** — Process isolation, no root privileges required\n\n## Repository Structure\n\n```\ntedge-ctrlx-os/\n├── snap/\n│   ├── snapcraft.yaml          # Snap build definition\n│   └── hooks/                  # install, configure, post-refresh, remove hooks\n├── web-server-rust/            # Actix-web backend (Rust)\n│   └── src/main.rs             # REST API server + license enforcement loop\n├── bridge-service-rust/        # ctrlX Data Layer bridge (Rust)\n├── web/www/                    # Frontend source (HTML, JS, CSS, styles.less)\n├── scripts/                    # Build and runtime helper scripts\n├── configs/                    # App metadata (caddyfile, package-manifest.json)\n├── package-assets/             # ctrlX Store assets (icons, i18n, proxy config)\n└── docs/                       # Documentation\n```\n\n## Components\n\n### Core Services (thin-edge.io v1.7.1)\n| Service | Description |\n|---------|-------------|\n| `tedge` | CLI tool for configuration and management |\n| `tedge-agent` | Main agent service for device operations |\n| `tedge-mapper-c8y` | Protocol mapper for Cumulocity IoT |\n| `tedge-mapper-aws` | Protocol mapper for AWS IoT Core |\n| `tedge-mapper-az` | Protocol mapper for Azure IoT Hub |\n| `tedge-watchdog` | Health monitoring and automatic recovery |\n| `mosquitto` | Local MQTT broker |\n\n### Plugins\n| Plugin | Description |\n|--------|-------------|\n| `tedge-file-config-plugin` | Configuration file management |\n| `tedge-snap-plugin` | Lists installed snaps in Cumulocity software inventory (read-only, install/remove not supported) |\n\n### Custom Services\n| Service | Description |\n|---------|-------------|\n| `webserver` | Rust/Actix-web configuration UI (accessible via ctrlX sidebar); acquires ctrlX license on startup, shows warning banner if missing |\n| `tedge-datalayer-bridge` | ctrlX Data Layer ↔ thin-edge.io bridge; polls Data Layer nodes and publishes measurements/events/alarms to MQTT |\n| `tedge-log-upload-manager` | Coordinates log file uploads to cloud platforms (replaces standard `tedge-file-log-plugin`) |\n\n## Web UI\n\nAfter installation, the configuration UI is accessible via the ctrlX CORE sidebar under **thin-edge.io**, or directly at:\n\n```\nhttps://\u003cdevice-ip\u003e/thin-edge-io/\n```\n\n### UI Sections\n\nEach section is a collapsible card in the sidebar UI. All sections are always visible simultaneously (no navigation required).\n\n---\n\n#### CONNECTION STATUS\n\nThree-column live status dashboard, auto-refreshing every 30 seconds (also on demand via **Refresh Status** button):\n\n| Column | Items |\n|--------|-------|\n| **Services** | MQTT Broker, Tedge Agent, Datalayer Bridge, Watchdog, Log Manager — each label is clickable to restart the service |\n| **Mappers** | Cumulocity IoT, AWS IoT, Azure IoT — shows whether the mapper process is running |\n| **Cloud Connections** | Cumulocity IoT, AWS IoT, Azure IoT — shows MQTT bridge state (`$SYS/broker/connection/*/state`) |\n\nStatus indicators:\n- 🟢 **Running** — process active\n- 🔴 **Stopped** — process not running  \n- ⚫ **Inactive** — disabled/not configured\n- ⚪ **Unknown** — not yet checked\n\n---\n\n#### CLOUD CONFIGURATION\n\nThree tabs — **Cumulocity IoT**, **AWS IoT**, **Azure IoT**:\n\n| Tab | Fields |\n|-----|--------|\n| **Cumulocity IoT** | C8Y URL (e.g. `https://your-tenant.cumulocity.com`), Tenant ID, Enable Cumulocity Mapper toggle |\n| **AWS IoT** | AWS IoT Endpoint URL (e.g. `xxxxxxxxxx.iot.us-east-1.amazonaws.com`), Enable AWS Mapper toggle |\n| **Azure IoT** | Azure IoT Hub URL (e.g. `your-hub.azure-devices.net`), Enable Azure Mapper toggle |\n\nEach tab has a **Save Configuration** button that writes values via `POST /api/config/{cloud}`. The **Enable Mapper** toggle immediately starts (`snapctl start thin-edge-io.tedge-mapper-\u003ccloud\u003e`) or stops (`snapctl stop`) the corresponding mapper service — no manual restart required.\n\n---\n\n#### DEVICE CONFIGURATION \u0026 CERTIFICATE\n\nLeft panel — device identity:\n\n| Element | Description |\n|---------|-------------|\n| **Device ID** | Read-only; the unique device identifier derived from the serial number |\n| **Device Name** | Editable CN used when creating / renewing the X.509 certificate |\n| **Certificate Status** | Indicates whether a valid device certificate exists |\n| **Upload Status** | Shows whether the certificate has been uploaded to Cumulocity (persisted in `tedge-web-config.json`) |\n| **Save** | Saves device name changes |\n| **Renew Certificate** | Recreates the certificate with the current Device Name as CN |\n| **Upload Certificate** | Expands a credential form (Cumulocity username + password) and uploads the certificate via `POST /api/cert/upload/c8y` |\n\nRight panel (shown when a certificate exists): **Certificate Details** — displays subject, issuer, validity dates, and fingerprint.\n\n---\n\n#### CONNECT DEVICE\n\nThree tabs — **Cumulocity IoT**, **AWS IoT**, **Azure IoT** — each with:\n\n- **Connect** — runs `tedge connect \u003ccloud\u003e`\n- **Reconnect** — runs `tedge reconnect \u003ccloud\u003e`\n- **Disconnect** — runs `tedge disconnect \u003ccloud\u003e`\n- **Setup ↗** — opens the thin-edge.io documentation for the respective cloud\n\nFor **Cumulocity IoT** only, an additional **MQTT Port** toggle selects between:\n- `Core MQTT (8883)` — standard TLS MQTT\n- `MQTT Service (9883)` — Cumulocity MQTT Service (connection only; SmartREST operations not supported)\n\n**Test Messages** section (bottom, shared across all tabs):\n\n| Button | MQTT Topic |\n|--------|-----------|\n| Test Measurement | publishes a sample measurement payload |\n| Test Event | publishes a sample event payload |\n| Test Alarm | publishes a sample alarm payload |\n\nOutput of connect/disconnect/test operations appears in the **Logs \u0026 Diagnostics** viewer.\n\n---\n\n#### LOGS \u0026 DIAGNOSTICS\n\nLive log viewer with controls:\n\n| Control | Options |\n|---------|---------|\n| **Service** | `tedge-agent`, `tedge-mapper-c8y`, `tedge-mapper-aws`, `tedge-mapper-az`, `tedge-bridge`, `log-upload`, `mosquitto`, `webserver` |\n| **Log Level** | `error`, `warn`, `info` (default), `debug`, `trace` |\n| **Apply Level** | Writes the selected level via `RUST_LOG` to `$SNAP_DATA/log-levels/\u003cservice\u003e` and restarts the service |\n| **Load Logs** | Fetches recent log lines via `GET /api/logs?service=\u003cname\u003e` |\n| **Copy** | Copies viewer content to clipboard |\n\nThe viewer is a 320 px high monospace scrollable area.\n\n---\n\n#### TEDGE CONFIGURATION\n\nRead-only view of the complete `tedge config list` output (equivalent to running `thin-edge-io.tedge config list` on the device):\n\n- **Load** — fetches via `GET /api/tedge-config-list`\n- **Copy** — copies all lines to clipboard\n\nThe viewer is a 400 px high monospace scrollable area.\n\n---\n\n#### SNAP CONFIGURATION FILES\n\nDirect file editor for the snap's configuration files stored in `$SNAP_DATA`. Useful for advanced manual edits without SSH access.\n\n**File selector:**\n\n| File | Location | Description |\n|------|----------|-------------|\n| `datalayer-mappings.json` | `$SNAP_DATA/datalayer-mappings.json` | ctrlX Data Layer ↔ MQTT bridge mapping definitions |\n| `inventory.json` | `$SNAP_DATA/tedge/device/inventory.json` | Device inventory reported to cloud (hardware, snap list) |\n| `mosquitto.conf` | `$SNAP_DATA/mosquitto/mosquitto.conf` | Mosquitto MQTT broker configuration (ports, TLS, bridge) |\n| `tedge.toml` | `$SNAP_DATA/tedge/tedge.toml` | Main thin-edge.io configuration (URLs, paths, plugin settings) |\n| `tedge-log-plugin.toml` | `$SNAP_DATA/tedge/plugins/tedge-log-plugin.toml` | Log file paths exposed for remote log upload requests |\n| `tedge-configuration-plugin.toml` | `$SNAP_DATA/tedge/plugins/tedge-configuration-plugin.toml` | Config files exposed for remote configuration management |\n\nThe file's full path is shown below the selector as a hint. The editor textarea is resizable vertically.\n\n- **Load** — reads the file via `GET /api/snapconfig?file=\u003cname\u003e`\n- **Save** — writes back via `POST /api/snapconfig` (requires `thin-edge-io.rw` scope)\n- **Copy** — copies editor content to clipboard\n\n---\n\n#### CTRLX DATA POINTS (DATALAYER)\n\nManages the optional ctrlX Data Layer ↔ MQTT bridge service (`tedge-datalayer-bridge`).\n\n**Status row:** Shows the bridge service dot and connection state; **Refresh** button re-polls `GET /api/datalayer/status`.\n\n**Connection Settings** (collapsible `\u003cdetails\u003e`):\n\n| Field | Description |\n|-------|-------------|\n| Base URL | ctrlX Data Layer base URL (default `https://localhost`) |\n| Username | Data Layer username (default `boschrexroth`) |\n| Password | Data Layer password |\n| Poll interval (ms) | How often the bridge polls Data Layer nodes (default `5000`) |\n| Static Token | Optional bearer token (overrides username/password) |\n| Enabled toggle | Enable/disable the bridge |\n| Accept invalid TLS certs | Skip TLS verification (useful for self-signed certificiates on local device) |\n| **Save Connection** | Saves via `POST /api/datalayer/config` |\n\n**Node Browser** (collapsible `\u003cdetails\u003e`):\n- Path input + **Browse** button — lists child nodes of the given Data Layer path via `GET /api/datalayer/browse`\n- **↑ Up** — navigates to the parent path\n- Clicking a node reads its current value; a **+** icon in the node list opens the Add Mapping form pre-filled with that path\n\n**Mappings Form** (shown when adding or editing):\n\n| Field | Description |\n|-------|-------------|\n| Datalayer Path | Full path to the Data Layer node (e.g. `/framework/metrics/system/memfree-mb`) |\n| Direction | `Datalayer ➔ tedge` (read) or `tedge ➔ Datalayer` (write) |\n| tedge MQTT Topic | Auto-suggested based on transform type; editable (e.g. `c8y/mqtt/out/myTopic`) |\n| Transform | `raw`, `measurement`, `event`, or `alarm` |\n| Field name | JSON field name in the payload (auto-derived from path if left empty) |\n| Unit | Optional unit string (e.g. `°C`, `MB`, `%`) — published as top-level `\"unit\"` field |\n\n**Measurement Payload Format** (when using Cumulocity MQTT Service, port 9883):\n\n```json\n{\n  \"memfree-mb\": 6892.03,\n  \"unit\": \"MB\",\n  \"time\": \"2026-04-21T09:30:00.123Z\",\n  \"externalId\": \"ctrlx-984c906200b9425eb91c96474c64c938\"\n}\n```\n\n- `\"time\"`: UTC timestamp, added automatically on each poll cycle\n- `\"unit\"`: included only if configured in the mapping\n- `\"externalId\"`: automatically injected for topics starting with `c8y/mqtt/out/`; equals the device certificate CN (= the external ID registered in Cumulocity)\n- Multiple mappings can use the **same** MQTT topic — each is identified by its UUID and processed independently\n\n**Mappings Table** (bottom): lists all saved mappings with columns Path, Topic, Direction (arrow icon), Type · Field, Active toggle, and an edit button. Changes to individual rows are saved via `PUT /api/datalayer/mappings/{id}` or `DELETE /api/datalayer/mappings/{id}`.\n\n---\n\n#### CTRLX LICENSING\n\nShows the ctrlX OS licenses currently active on the device. Loaded automatically when the section is opened.\n\n| Element | Description |\n|---------|-------------|\n| License table | Lists all capabilities returned by the ctrlX License Manager API (`/license-manager/api/v1/capabilities`) — name, permanent flag, expiry date, count |\n| **Refresh** button | Re-fetches `GET /api/licenses` |\n| **Manage Licenses** button | Opens `/license-manager` (ctrlX License Manager UI) in a new tab |\n\nIf no valid license is held, a **red warning banner** is shown at the top of the page with a link to the Licensing section and the Bosch Rexroth Licensing Center.\n\n---\n\n#### SYSTEM INFORMATION\n\nDisplays read-only device and build metadata:\n\n| Field | Source |\n|-------|--------|\n| **Version** | Snap version (from `GET /api/build-info`) |\n| **Build** | Build number / Git commit from `configs/build-info.txt` |\n| **Architecture** | CPU architecture (`amd64` or `arm64`) |\n\n**Refresh** button reloads all status data (same as the button in Connection Status).\n\n### Web API (REST)\n\nSee **[docs/api-reference.md](docs/api-reference.md)** for the complete REST API reference.\n\n## Installation\n\nSee **[docs/installation.md](docs/installation.md)** for the complete installation guide, including:\n\n- Prerequisites and supported ctrlX OS versions\n- Step-by-step install via web interface and CLI\n- First-time setup wizard (cloud config, certificate, connect)\n- Snap service management commands\n- CLI commands reference\n- Important file paths\n- Network requirements\n- Uninstall instructions\n\n## Configuration\n\nSee **[docs/installation.md](docs/installation.md)** for CLI-based configuration and **[docs/configuration-reference.md](docs/configuration-reference.md)** for the complete reference of all auto-configured tedge settings, plugin configs, and Data Layer bridge configuration.\n\nQuick start via web UI:\n\n```\nhttps://\u003cdevice-ip\u003e/thin-edge-io/\n```\n\n## Building from Source\n\nSee **[docs/building.md](docs/building.md)** for the full build guide, including automated and manual build instructions, frontend development workflow, and a build scripts reference.\n\nQuick start:\n\n```bash\ngit clone https://github.com/thin-edge/tedge-ctrlx-os.git\ncd tedge-ctrlx-os\n./setup-and-build-all.sh --fix\n```\n\n## Troubleshooting\n\nSee **[docs/troubleshooting.md](docs/troubleshooting.md)** for common issues and solutions covering cloud connectivity, certificate management, service startup failures, the Data Layer bridge, and license problems.\n\n## Network Requirements\n\n| Direction | Protocol | Port | Purpose |\n|-----------|----------|------|---------|\n| Outbound | HTTPS | 443 | Cloud platform REST API |\n| Outbound | MQTT/TLS | 8883 | Secure cloud MQTT (recommended) |\n| Outbound | MQTT/TLS | 9883 | Cumulocity MQTT Service (connection only; SmartREST operations not supported) |\n| Local | HTTP | 8888 | Web UI (proxied via ctrlX Caddy) |\n| Local | MQTT | 1883 | Local broker (internal) |\n\n## Security\n\n- All cloud connections use **TLS 1.2+**\n- **Certificate-based** device authentication (X.509)\n- **Strict snap confinement** — process isolation, no root required\n- **ctrlX Bearer Token** authentication for web UI access\n- Role-based scopes: `thin-edge-io.rwx`, `thin-edge-io.rw`, `thin-edge-io.r`\n\n## Resource Usage\n\n| Resource | Typical |\n|----------|---------|\n| RAM | ~50–100 MB (depending on active mappers) |\n| CPU | \u003c5% idle, \u003c20% during active data transfer |\n| Storage | ~100 MB for app + logs/cache |\n\n## License\n\nThis app packages **thin-edge.io**, licensed under the **Apache License 2.0**.\n\nAll included open-source components are documented in [`package-assets/fossinfo.json`](package-assets/fossinfo.json) and [`package-assets/foss-offer.txt`](package-assets/foss-offer.txt).\n\n## Links\n\n- **thin-edge.io Docs**: https://thin-edge.github.io/thin-edge.io/\n- **thin-edge.io GitHub**: https://github.com/thin-edge/thin-edge.io\n- **This App Repository**: https://github.com/thin-edge/tedge-ctrlx-os\n- **Discord Community**: https://discord.com/invite/sVX3B8nj5d\n\n## Roadmap\n\n- ✅ ctrlX License Management integration (acquire/release/periodic re-check + warning banner)\n- Enhanced ctrlX Diagnostics/Logbook integration\n\n## Contributing\n\nContributions to thin-edge.io are welcome! Visit the GitHub repository for contribution guidelines.\n\n## About thin-edge.io\n\nthin-edge.io is the first open-source and cloud-agnostic edge framework designed for resource-constrained IoT devices. It provides re-usable and modular components for IoT device enablement across different cloud platforms and industrial IoT scenarios.\n\n## Build \u0026 Development\n\nSee **[docs/building.md](docs/building.md)** for the complete build guide and scripts reference.\n\n```bash\n# Full build\n./setup-and-build-all.sh\n\n# Format check\n./scripts/check-format.sh\n\n# Clean build artifacts\n./scripts/clean.sh\n```\n\n## thin-edge.io Configuration Interface\n\nSee **[docs/configuration-reference.md](docs/configuration-reference.md)** for the complete reference of all auto-configured tedge settings and snap-managed plugin configurations.\n\n## Documentation\n\n| Document | Description |\n|----------|-------------|\n| [docs/installation.md](docs/installation.md) | Installation, first-time setup, CLI reference, file paths, network requirements |\n| [docs/building.md](docs/building.md) | Building from source, frontend development, scripts reference |\n| [docs/configuration-reference.md](docs/configuration-reference.md) | tedge.toml auto-configuration, plugin configs, Data Layer bridge config |\n| [docs/api-reference.md](docs/api-reference.md) | Complete REST API reference with all endpoints and scopes |\n| [docs/troubleshooting.md](docs/troubleshooting.md) | Common issues and solutions |\n| [docs/manual.md](docs/manual.md) | Screenshot-based user manual for the web UI |\n| [docs/architecture-overview.md](docs/architecture-overview.md) | System architecture and component overview |\n| [docs/auth-integration.md](docs/auth-integration.md) | ctrlX authentication and role-based access control |\n| [docs/release-notes.md](docs/release-notes.md) | Version history and changelog |\n| [docs/roadmap.md](docs/roadmap.md) | Not yet implemented features and known limitations |\n| [docs/test-setup-description.md](docs/test-setup-description.md) | Test environment setup |\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthin-edge%2Ftedge-ctrlx-os","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthin-edge%2Ftedge-ctrlx-os","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthin-edge%2Ftedge-ctrlx-os/lists"}