@ctrlpi/ctrlpi-lab 0.0.0-stage → 0.9.26
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +192 -2
- package/ctrlpi-lab.js +713 -0
- package/package.json +33 -4
- package/pages/api.html +139 -0
- package/pages/api_curl.html +60 -0
- package/pages/logs.html +86 -0
- package/pages/main.html +5391 -0
- package/pages/webhooks.html +52 -0
- package/pages/welcome.html +151 -0
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
<!-- PANE 2: Log Viewer Screen -->
|
|
2
|
+
<!-- PANE: Webhook Viewer -->
|
|
3
|
+
<div id="webhookPane" class="pane">
|
|
4
|
+
<div class="log-toolbar">
|
|
5
|
+
<div class="toolbar-left-group">
|
|
6
|
+
<span style="font-size:0.85rem;font-weight:600;color:var(--text-main);">Webhook Events</span>
|
|
7
|
+
<div class="log-icon-actions">
|
|
8
|
+
<button type="button" class="theme-toggle-btn" title="Refresh webhooks" aria-label="Refresh webhooks" onclick="triggerManualWebhookRefresh()">
|
|
9
|
+
<svg aria-hidden="true" id="webhookRefreshBtnIcon" viewBox="0 0 24 24">
|
|
10
|
+
<path d="M17.65 6.35C16.2 4.9 14.21 4 12 4c-4.42 0-7.99 3.58-7.99 8s3.57 8 7.99 8c3.73 0 6.84-2.55 7.73-6h-2.08c-.82 2.33-3.04 4-5.65 4-3.31 0-6-2.69-6-6s2.69-6 6-6c1.66 0 3.14.69 4.22 1.78L13 11h7V4l-2.35 2.35z"/>
|
|
11
|
+
</svg>
|
|
12
|
+
</button>
|
|
13
|
+
</div>
|
|
14
|
+
<div class="log-count-badge">
|
|
15
|
+
<span id="webhookCount">0</span> events
|
|
16
|
+
</div>
|
|
17
|
+
</div>
|
|
18
|
+
<div class="toolbar-right-group">
|
|
19
|
+
<div class="refresh-rate-group">
|
|
20
|
+
<label for="webhookPollSelect">Poll Rate:</label>
|
|
21
|
+
<select id="webhookPollSelect" class="refresh-rate-select" onchange="setupWebhookAutoRefresh()">
|
|
22
|
+
<option value="3000">3s</option>
|
|
23
|
+
<option value="10000">10s</option>
|
|
24
|
+
<option value="20000" selected>20s</option>
|
|
25
|
+
<option value="30000">30s</option>
|
|
26
|
+
<option value="manual">Manual</option>
|
|
27
|
+
</select>
|
|
28
|
+
</div>
|
|
29
|
+
<div class="config-input-group switch-group" style="border:none; padding:0; background:none;">
|
|
30
|
+
<label for="webhookAutoScrollToggle" style="margin-right: 6px;">Auto Scroll</label>
|
|
31
|
+
<label class="toggle-switch">
|
|
32
|
+
<input type="checkbox" id="webhookAutoScrollToggle" checked>
|
|
33
|
+
<span class="slider"></span>
|
|
34
|
+
</label>
|
|
35
|
+
</div>
|
|
36
|
+
</div>
|
|
37
|
+
</div>
|
|
38
|
+
<div class="webhook-table-wrap">
|
|
39
|
+
<table class="webhook-table">
|
|
40
|
+
<thead>
|
|
41
|
+
<tr>
|
|
42
|
+
<th>Time (UTC)</th>
|
|
43
|
+
<th>Api-Key</th>
|
|
44
|
+
<th>Payload</th>
|
|
45
|
+
</tr>
|
|
46
|
+
</thead>
|
|
47
|
+
<tbody id="webhookTbody">
|
|
48
|
+
<tr><td colspan="3" id="webhookEmpty" style="text-align:center;color:var(--text-muted);padding:48px;">No webhook events yet.</td></tr>
|
|
49
|
+
</tbody>
|
|
50
|
+
</table>
|
|
51
|
+
</div>
|
|
52
|
+
</div>
|
|
@@ -0,0 +1,151 @@
|
|
|
1
|
+
<div id="welcomePanel" class="info-panel">
|
|
2
|
+
<div class="info-panel-header">
|
|
3
|
+
<span class="info-panel-title">Welcome to ctrlPi</span>
|
|
4
|
+
<button class="info-panel-close" onclick="closeInfoPanel()">Close</button>
|
|
5
|
+
</div>
|
|
6
|
+
|
|
7
|
+
<div class="info-section">
|
|
8
|
+
<h3>What is ctrlPi?</h3>
|
|
9
|
+
<p>ctrlPi lets you control Raspberry Pi, Pico W, and ESP32 GPIO pins and read named sensors over a REST API, from a dashboard, command line, or integration.</p>
|
|
10
|
+
</div>
|
|
11
|
+
|
|
12
|
+
<div class="info-section">
|
|
13
|
+
<h3>Architecture</h3>
|
|
14
|
+
<p>One tiny server per board. Everything else talks to it over plain HTTP on your LAN.</p>
|
|
15
|
+
<div class="info-cards">
|
|
16
|
+
<div class="info-card">
|
|
17
|
+
<div class="info-card-icon i-green">
|
|
18
|
+
<svg viewBox="0 0 24 24"><rect x="7" y="7" width="10" height="10" rx="1.6"/><path d="M9 7V4M12 7V4M15 7V4M9 20v-3M12 20v-3M15 20v-3M7 9H4M7 12H4M7 15H4M20 9h-3M20 12h-3M20 15h-3"/></svg>
|
|
19
|
+
</div>
|
|
20
|
+
<div class="info-card-title">Agents: the muscle</div>
|
|
21
|
+
<div class="info-card-desc">A single-file REST server on the Pi, Pico W, or ESP32 drives the pins: outputs, inputs, pull-ups, pulses with auto-revert, reversed relay logic, and webhooks on every change. Same API across boards, clients never care which one answered.</div>
|
|
22
|
+
</div>
|
|
23
|
+
<div class="info-card">
|
|
24
|
+
<div class="info-card-icon i-violet">
|
|
25
|
+
<svg viewBox="0 0 24 24"><path d="M4 11.5 12 4l8 7.5"/><path d="M6 10v8a1 1 0 0 0 1 1h3v-5h4v5h3a1 1 0 0 0 1-1v-8"/></svg>
|
|
26
|
+
</div>
|
|
27
|
+
<div class="info-card-title">Bridges: the home</div>
|
|
28
|
+
<div class="info-card-desc">Matter and native-HomeKit bridges declare your devices in one JSON file: lights, locks, garage doors, valves, sensors, buttons, and drive them through the agents' API. Pair once, control from your phone, your watch, or "Hey Siri".</div>
|
|
29
|
+
</div>
|
|
30
|
+
<div class="info-card">
|
|
31
|
+
<div class="info-card-icon i-rose">
|
|
32
|
+
<svg viewBox="0 0 24 24"><path d="M12 3v3M8 8h8a2 2 0 0 1 2 2v6a3 3 0 0 1-3 3H9a3 3 0 0 1-3-3v-6a2 2 0 0 1 2-2Z"/><circle cx="9.5" cy="12.5" r="1"/><circle cx="14.5" cy="12.5" r="1"/><path d="M5 12H3M21 12h-2"/></svg>
|
|
33
|
+
</div>
|
|
34
|
+
<div class="info-card-title">MCP: the brain</div>
|
|
35
|
+
<div class="info-card-desc">A zero-dependency Model Context Protocol server exposes the whole GPIO surface as tools. Ask Claude to scan your LAN for agents, flip a relay, or watch a door sensor, in plain language.</div>
|
|
36
|
+
</div>
|
|
37
|
+
</div>
|
|
38
|
+
<div class="info-flow">
|
|
39
|
+
<p><strong>Small pieces, one wire format:</strong> every connection is plain HTTP with an <code>Api-Key</code> header, no hubs or clouds required.</p>
|
|
40
|
+
<pre class="info-flow-pre">
|
|
41
|
+
<span class="c-rose">[Claude / MCP client]</span> <span class="c-violet">[Apple Home]</span> <span class="c-violet">[Google Home / Alexa]</span>
|
|
42
|
+
│ │ │
|
|
43
|
+
MCP (STDIO/HTTP) HAP Matter
|
|
44
|
+
│ │ │
|
|
45
|
+
▼ ▼ ▼
|
|
46
|
+
<span class="c-rose">mcp-bridge</span> <span class="c-violet">homekit-bridge</span> <span class="c-violet">matter-bridge</span> <span class="c-blue">◀─────────────────────────┐</span>
|
|
47
|
+
│ │ │ <span class="c-blue">:</span>
|
|
48
|
+
└──────────────────────────┼───────────────────────┘ <span class="c-blue">:</span>
|
|
49
|
+
│ <span class="c-blue">:</span>
|
|
50
|
+
REST /gpio/* /sensors/* /scripts/* /config/* <span class="c-mut">(Api-Key)</span> <span class="c-blue">:</span>
|
|
51
|
+
│ <span class="c-blue">:</span>
|
|
52
|
+
<span class="c-green">agents · pi-gpio-api (Pi) · pico-gpio-api (Pico W) · esp32-gpio-api (ESP32)</span><span class="c-blue"> ── Notifications ──────┘</span>
|
|
53
|
+
│
|
|
54
|
+
relays · locks · lights · valves · sensors · buttons</pre>
|
|
55
|
+
</div>
|
|
56
|
+
</div>
|
|
57
|
+
|
|
58
|
+
<div class="info-section">
|
|
59
|
+
<h3>What is ctrlpi-lab?</h3>
|
|
60
|
+
<p><strong>ctrlpi-lab</strong> is the browser workbench for your ctrlPi setup. It provides a lightweight, zero-dependency local dashboard that communicates with your agents over HTTP through an internal proxy:</p>
|
|
61
|
+
<ul>
|
|
62
|
+
<li><strong>API Tester:</strong> test every GPIO, sensor, and configuration endpoint directly from the browser with dynamic form controls, response inspection, and instant cURL examples.</li>
|
|
63
|
+
<li><strong>Live Logs:</strong> inspect and tail agent logs in real time with keyword search and category filtering.</li>
|
|
64
|
+
<li><strong>Webhook Monitor:</strong> monitor live events and notifications delivered to public test or local webhook endpoints.</li>
|
|
65
|
+
<li><strong>Automatic Discovery:</strong> sweeps your local subnet for online agents, saves credentials securely, and keeps your agent list in sync with all ctrlPi tools.</li>
|
|
66
|
+
<li><strong>Shared Ecosystem:</strong> shares configuration with <code>mcp-bridge</code> and smart-home bridges, allowing AI assistants (like Claude) to connect to your agents using the same saved credentials.</li>
|
|
67
|
+
</ul>
|
|
68
|
+
</div>
|
|
69
|
+
|
|
70
|
+
<div class="info-section">
|
|
71
|
+
<h3>Key capabilities</h3>
|
|
72
|
+
<ul>
|
|
73
|
+
<li>Read and write GPIO pins by number or configured name alias</li>
|
|
74
|
+
<li>Configure pins as input, output, VCC (always HIGH), or GND (always LOW)</li>
|
|
75
|
+
<li>Timed output pulses with automatic revert: <code>duration</code> is capped by <code>max</code>; when duration is omitted, a configured max supplies it</li>
|
|
76
|
+
<li>Active-low (reversed) logic, with logical value and physical level reported separately</li>
|
|
77
|
+
<li>Watch inputs for state changes and outputs for writes; send events to configured webhook and bridge targets, or log them when no target is configured</li>
|
|
78
|
+
<li>Read named sensors on demand using scripts: shell scripts on Pi, MicroPython scripts on Pico and ESP32</li>
|
|
79
|
+
<li>Read, update, and load configuration, with automatic backups before updates and loads</li>
|
|
80
|
+
</ul>
|
|
81
|
+
</div>
|
|
82
|
+
|
|
83
|
+
<div class="info-section">
|
|
84
|
+
<h3>Quick start</h3>
|
|
85
|
+
<p>Install an agent using the instructions below. In the header, select a discovered agent or click <strong>+</strong> to add its IP address or hostname, port (default <strong>8314</strong>), and API key. Use the key icon to edit the saved key, then explore endpoints in the <strong>API</strong> tab or open <strong>API - cURL Examples</strong>.</p>
|
|
86
|
+
<p>The agents serve plain HTTP. Keep them on a trusted LAN; use a tunnel for remote access rather than exposing port 8314 to the internet.</p>
|
|
87
|
+
</div>
|
|
88
|
+
|
|
89
|
+
<div class="info-section">
|
|
90
|
+
<h3>Install the API on a Raspberry Pi</h3>
|
|
91
|
+
<p>Requires Python 3.9+ on Raspberry Pi OS. Supported boards: Raspberry Pi 2, 3, 4, 5, Zero W, and Zero 2 W. Run these commands in a terminal on the Pi.</p>
|
|
92
|
+
<p><strong>Install with curl</strong></p>
|
|
93
|
+
<div class="info-code-block">curl -fsSL https://raw.githubusercontent.com/ctrlpi/pi-gpio-api/main/install.sh | bash
|
|
94
|
+
cd pi-gpio-api
|
|
95
|
+
./run.sh</div>
|
|
96
|
+
<p>The installer downloads the project, builds its virtual environment, and asks for an agent name and API key if no config exists. The server listens on all interfaces at port 8314 by default.</p>
|
|
97
|
+
<p>To run at boot, copy the ready-to-paste systemd command printed by the installer. To change and save the API key when starting the server:</p>
|
|
98
|
+
<div class="info-code-block">./run.sh --api-key your-secret-key --save</div>
|
|
99
|
+
<p>See the <a href="https://github.com/ctrlpi/pi-gpio-api#install-on-your-pi" target="_blank" rel="noopener noreferrer">Pi API installation guide</a> for GPIO backend requirements and more options.</p>
|
|
100
|
+
</div>
|
|
101
|
+
|
|
102
|
+
<div class="info-section">
|
|
103
|
+
<h3>Install the API on a Raspberry Pi Pico</h3>
|
|
104
|
+
<p>Requires a <strong>Pico W or Pico 2 W</strong>, MicroPython firmware, and a Mac/PC connected to the board over USB. Run the tools below on your computer, not on the Pico.</p>
|
|
105
|
+
<p><strong>Easiest: Pico Bay</strong></p>
|
|
106
|
+
<div class="info-code-block">npx @ctrlpi/pico-bay</div>
|
|
107
|
+
<p>Connect your board and choose <strong>Install ctrlPi API</strong> from the top-right menu. Enter your API key and WiFi information when prompted. Pico Bay can also install MicroPython when the board is connected in BOOTSEL mode, or after choosing <strong>Reboot to BOOTSEL</strong>.</p>
|
|
108
|
+
<p><strong>Or install with curl</strong></p>
|
|
109
|
+
<div class="info-code-block">curl -fsSL https://raw.githubusercontent.com/ctrlpi/pico-gpio-api/main/install.sh | bash</div>
|
|
110
|
+
<p>With MicroPython already installed, the installer asks for any missing API key, agent name, and WiFi credentials, copies the files to every connected Pico over USB using mpremote, and resets the boards. Existing device configuration is preserved on a normal reinstall.</p>
|
|
111
|
+
<p>The API starts automatically at every boot on port 8314. The original Pico W requires an <code>http://</code> webhook target; Pico 2 W also supports <code>https://</code>.</p>
|
|
112
|
+
<p>See the <a href="https://github.com/ctrlpi/pico-gpio-api#install-on-your-pico-w" target="_blank" rel="noopener noreferrer">Pico API installation guide</a> for firmware, WiFi, and USB deployment details.</p>
|
|
113
|
+
</div>
|
|
114
|
+
|
|
115
|
+
<div class="info-section">
|
|
116
|
+
<h3>Install the API on an ESP32</h3>
|
|
117
|
+
<p>Requires an <strong>ESP32</strong>, <strong>ESP32-C3</strong> or <strong>ESP32-S3</strong> with MicroPython 1.29 firmware (the matching ESP32_GENERIC build), and a Mac/PC connected to the board over USB. Run the tools below on your computer, not on the ESP32.</p>
|
|
118
|
+
<p><strong>Easiest: Pico Bay</strong></p>
|
|
119
|
+
<div class="info-code-block">npx @ctrlpi/pico-bay</div>
|
|
120
|
+
<p>Connect your ESP32 and choose <strong>Install ctrlPi API</strong> from the top-right menu. Enter your API key and WiFi information when prompted.</p>
|
|
121
|
+
<p><strong>Or install with curl</strong></p>
|
|
122
|
+
<div class="info-code-block">curl -fsSL https://raw.githubusercontent.com/ctrlpi/esp32-gpio-api/main/install.sh | bash</div>
|
|
123
|
+
<p>With MicroPython already installed, the installer asks for your API key, agent name, and WiFi credentials, compiles bytecode, and deploys to the board over USB.</p>
|
|
124
|
+
<p>The API starts automatically at boot on port 8314.</p>
|
|
125
|
+
<p>See the <a href="https://github.com/ctrlpi/esp32-gpio-api#install-on-your-esp32" target="_blank" rel="noopener noreferrer">ESP32 API installation guide</a> for details.</p>
|
|
126
|
+
</div>
|
|
127
|
+
|
|
128
|
+
<div class="info-section">
|
|
129
|
+
<h3>Install and connect ctrlPi MCP Bridge</h3>
|
|
130
|
+
<p>An MCP (Model Context Protocol) server that gives AI assistants like Claude Desktop full control over your GPIO agents in natural conversation, with zero dependencies.</p>
|
|
131
|
+
<p><strong>Add to Claude Desktop (no install required)</strong></p>
|
|
132
|
+
<p>Open Claude Desktop settings, click <strong>Developer → Edit Config</strong>, and add <code>ctrlpi</code> under <code>mcpServers</code>:</p>
|
|
133
|
+
<div class="info-code-block">{
|
|
134
|
+
"mcpServers": {
|
|
135
|
+
"ctrlpi": {
|
|
136
|
+
"command": "npx",
|
|
137
|
+
"args": ["-y", "@ctrlpi/mcp-bridge"]
|
|
138
|
+
}
|
|
139
|
+
}
|
|
140
|
+
}</div>
|
|
141
|
+
<p>Restart Claude Desktop. On first launch, it sweeps your local /24 subnet for agents and records them in <code>~/.ctrlpi/agents-config.json</code>.</p>
|
|
142
|
+
<p><strong>Run as an HTTP service (for remote clients and integrations)</strong></p>
|
|
143
|
+
<div class="info-code-block">npx -y @ctrlpi/mcp-bridge --http</div>
|
|
144
|
+
<p>Or install it in a folder of your choice:</p>
|
|
145
|
+
<div class="info-code-block">npm install @ctrlpi/mcp-bridge
|
|
146
|
+
cd node_modules/@ctrlpi/mcp-bridge
|
|
147
|
+
npm start -- --http</div>
|
|
148
|
+
<p>Listens on port <strong>8315</strong> and shares configuration with ctrlpi-lab in <code>~/.ctrlpi/agents-config.json</code>.</p>
|
|
149
|
+
<p>See the <a href="https://github.com/ctrlpi/mcp-bridge#readme" target="_blank" rel="noopener noreferrer">MCP Bridge documentation</a> for PM2 service configuration, key rotation, and tool details.</p>
|
|
150
|
+
</div>
|
|
151
|
+
</div>
|