N8N Workflow Automation on the UNO Q — Sensors, GPIO, and AI Agent Control

Arduino App Lab

Arduino® UNO™ Q 4GB

<html><body><h3>What this project does</h3>The Arduino UNO Q is two computers in one: a Linux SBC on top and an AVR microcontroller below, connected by <code class="code">arduino-router </code>— a Go service that routes MessagePack-RPC calls between the two sides. App Lab talks to the MCU through this router. So does Python's <code class="code">arduino_app_bricks.Bridge </code>. And now, so does Node.js. The first thing you might reach for is a Python sidecar: spin a container that wraps <code class="code">Bridge.call() </code>in a small HTTP/TCP server, then have N8N call that over the network. This is exactly what <a href="https://github.com/ffich/UNOQ_DoubleBridge">UNOQ_DoubleBridge </a>does for Node-RED — a Python TCP proxy that relays RPC calls. This project adds N8N to that picture. N8N is a self-hosted workflow automation tool — think a visual programming environment where you connect nodes to process data, call APIs, respond to events, and automate decisions. It runs happily in Docker on the UNO Q. What it was missing was a way to reach the MCU. This project ships two npm packages that close that gap: <ol><li><code class="code">@raasimpact/arduino-uno-q-bridge </code>— a Node.js MessagePack-RPC client that talks directly to <code class="code">arduino-router </code>over its Unix socket or a reverse-SSH tunnel. No Python proxy. No extra container.</li><li><code class="code">n8n-nodes-uno-q </code>— four n8n community nodes: one to call MCU methods, one to trigger workflows from MCU events, one to send computed responses back to the MCU, and one to expose MCU methods as tools for n8n's AI Agent. </li></ol>Both packages also support multiple UNO Qs in the same workflow: define one credential per board and assign a different one to each node. A workflow that reads a temperature sensor on one Q and fires a fan relay on another is just two nodes with different credentials — no other coordination needed.The last point is what makes the project interesting: you can drop a "read temperature" node onto an AI Agent's Tool port and let the LLM decide when to sample it, chain the result with other data, and decide whether to turn on a fan — expressed in natural language, executed by the model autonomously. <h3>How the UNO Q's architecture works</h3>The <code class="code">arduino-router </code>process runs as a systemd service and listens on a Unix socket at <code class="code">/var/run/arduino-router.sock </code>(world-writable, so containers don't need special permissions). It speaks standard MessagePack-RPC: <pre>REQUEST: [0, msgid, method_name, params_array] → expects a RESPONSE </pre><pre>RESPONSE: [1, msgid, error, result] → error is null on success </pre><pre>NOTIFY: [2, method_name, params_array] → fire-and-forget, no response </pre>On the MCU side, your sketch uses <code class="code">Arduino_RouterBridge </code>to register handlers: <pre>#include &lt;Arduino_RouterBridge.h&gt; </pre><pre>// Called by n8n when it wants to turn the LED on or off </pre><pre>void setLedState(BridgeRequest &amp;req) { </pre><pre>	 bool state = req.params()[0].as&lt;bool&gt;(); </pre><pre>	 digitalWrite(LED_BUILTIN, state ? HIGH : LOW); </pre><pre>	 req.reply(state); </pre><pre>} </pre><pre>void setup() { </pre><pre>	 pinMode(LED_BUILTIN, OUTPUT); </pre><pre>	 Bridge.begin(); </pre><pre>	 Bridge.provide("set_led_state", setLedState); </pre><pre>} </pre><pre>void loop() { </pre><pre>	 Bridge.update(); </pre><pre>} </pre> Any Node.js process that connects to the socket and calls <code class="code">set_led_state </code>will have its call routed to this sketch handler. That's the entire mechanism. <h3>Setting up n8n on the UNO Q</h3>SSH into the board, grab the compose file, and start N8N: <pre>ssh arduino@&lt;your-q-hostname&gt; </pre><pre>mkdir -p ~/n8n &amp;&amp; cd ~/n8n </pre><pre>curl -fsSL -O https://raw.githubusercontent.com/raasimpact/n8n-uno-q/main/deploy/n8n/docker-compose.yml </pre><pre>docker compose up -d </pre> The first run pulls the n8n image — allow a few minutes. Then open <code class="code">http://&lt;your-q-hostname&gt;:5678 </code>in a browser, complete the setup wizard, and install the community node: <code class="code">Settings → Community Nodes → Install → search n8n-nodes-uno-q → Install.</code>N8N pulls the package (and the bridge as a transitive dependency) from npm and persists it in its data volume. The nodes are immediately available in the node picker — search "Arduino" or "UNO Q". <blockquote>Note on the hostname: the compose file defaults <code class="code">N8N_HOST </code>and <code class="code">WEBHOOK_URL </code>to <code class="code">linucs.local </code>(my development board's hostname). Set them to your board's actual hostname or IP before starting, otherwise AI Chat and Webhook nodes will advertise an unreachable URL. </blockquote><h3>The four nodes</h3>Arduino UNO Q Call — the straightforward one. Configure a method name and parameters (typed fields or raw JSON array), run the node, get the MCU's response as a workflow item. Equivalent to an HTTP Request node, but for your microcontroller. Arduino UNO Q Trigger — fires a workflow when the MCU sends a call or notification. Two sub-modes: <ol><li>Notification mode : the MCU sends <code class="code">Bridge.notify("button_pressed", pin, state) </code>→ N8N workflow fires immediately. Fire-and-forget; no response. Multiple workflows can all listen for the same event. </li></ol><ol><li>Request mode : the MCU sends <code class="code">Bridge.call("ask_database", key) </code>→ N8N workflow fires, looks up the value, and returns it to the MCU. Two response options: Acknowledge Immediately (return a fixed ack and run the workflow in parallel) or Wait for Respond Node (hold the RPC connection open until a Respond node computes the answer). </li></ol>Arduino UNO Q Respond — the companion to Trigger's Wait for Respond Node mode. Once the workflow has computed an answer (fetched from a database, generated by an LLM, looked up in a spreadsheet), drop this node at the end and it closes the open RPC request. Same pattern as N8N's built-in "Respond to Webhook" node, over the router socket instead of HTTP. Arduino UNO Q Method — the interesting one. Set <code class="code">usableAsTool: true </code>in its declaration so N8N's AI Agent can use it as a callable tool. Wire it to the Agent's Tool port, write a plain-English description, configure the method name and parameters, and the LLM can now call your MCU method as part of its reasoning loop. <h3>The AI Agent: an LLM that can touch hardware</h3>N8N's Tools AI Agent orchestrates an LLM that can call tools in a loop until it has an answer. Normally those tools are HTTP endpoints or database queries. With the Method node, they can be MCU methods. Here's what the nodes' configuration looks like for a temperature-and-fan workflow: Tool 1 — read_temperature : <ol><li>Description : Reads the current temperature in Celsius from the onboard sensor. Safe to call any time; no side effects. </li><li>Method : <code class="code">read_temperature </code></li><li>Parameters - (none) </li><li>Idempotent : ✓ (a read is always safe to replay) </li></ol>Tool 2 — set_fan_speed : <ol><li>Description : Sets the fan speed (0–100). Call with 0 to stop. Retrying with the same value is safe — absolute, not relative. </li><li>Method : <code class="code">set_fan_speed </code></li><li>Parameters - Type: <code class="code">Number </code>, Value: <code class="code">{{ $fromAI('speed', 'Fan speed 0–100', 'number') }} </code></li><li>Idempotent : ✓ </li></ol>Wire both to the Agent's Tool port. Give the agent the prompt: "Check the temperature. If it's above 28°C, turn on the fan at 70%. Otherwise turn it off." The model calls <code class="code">read_temperature </code>, evaluates the result, and calls <code class="code">set_fan_speed </code>appropriately — without any explicit branching logic in the workflow. Spoiler: I'm not that good at hardware ;-) so I decided to go for a minimal setup, consisting of a simple pushbutton - here's the proof: <figure><img src="https://projects.arduinocontent.cc/e413e392-9012-4599-bc3a-346e3d9fa159.png"/><figcaption>My Uno Q working hard for the tests - my cats' hair were almost everywhere :D</figcaption></figure> <h3>Reliability: idempotency, method guard, and rate limiting</h3>Letting software control hardware requires thinking about what happens when things go wrong. Idempotent flag : when the router socket drops mid-call, the MCU may have already executed the method but the response never arrived. A naïve retry fires the actuator twice. The Idempotent checkbox on Call and Method nodes tells the bridge whether a replay is safe. If yes, it auto-retries on <code class="code">ConnectionError </code>within the remaining timeout budget. If no (the default — fail-closed), it surfaces the error and lets the workflow decide. <pre>set_valve(closed) → idempotent ✓ — closing an already-closed valve is fine </pre><pre>move_stepper(+100) → idempotent ✗ — replaying moves the motor again </pre> Method Guard : an optional JavaScript body that runs at invocation time — before every call reaches the MCU — with <code class="code">method </code>(the MCU function being called) and <code class="code">params </code>(the parameters being passed by the LLM) in scope. Return a string to reject with that exact message; when wired to an Agent, the LLM receives the rejection as tool output and can self-correct. Useful for clamping LLM-supplied values, time-of-day gating, or external-state checks: <pre>// Clamp speed and block outside operating hours </pre><pre>if (params[0] &lt; 0 || params[0] &gt; 100) </pre><pre>	 return `Refused: speed must be 0–100, got ${params[0]}`; </pre><pre>const hour = new Date().getHours(); </pre><pre>if (hour &lt; 8 || hour &gt;= 18) </pre><pre>	 return 'Refused: outside operating hours (8:00–18:00)'; </pre><pre>return true; </pre> Rate Limit : cap invocations in a sliding window (e.g. max 10 calls per minute). Excess calls return a <code class="code">{ refused: true, error: "Retry in ~Xs" } </code>the LLM can read. The Method Guard also has a <code class="code">budget </code>object ( <code class="code">budget.used('minute'), budget.remaining </code>) for softer, traffic-aware policies.<h3>Connecting to a remote UNO Q</h3>When n8n runs on a different machine from the Q — or on a Q sitting behind a NAT — the <code class="code">arduino-router</code> Unix socket isn't directly reachable. Three relay variants ship with the repo, all using the same nodes and credential type:<ol><li>A — using <code class="code">socat</code> (use on a trusted LAN -home network): a container on the Q exposes the router socket as a plain TCP endpoint on port 5775. No encryption.</li></ol><ol><li>B — reverse SSH (use when the device is behind NAT with no inbound port): the Q dials out via <code class="code">autossh</code> to an embedded SSH server running inside n8n. n8n routes traffic back to the Q over the existing session. No port forwarding required on the Q's router.</li><li>C — <code class="code">stunnel</code> + mTLS (use on an untrusted network or internet path): same TCP relay as A) but wrapped in mutual TLS. The repo includes a PKI wrapper (<code class="code">./pki setup</code>, <code class="code">./pki add device</code> etc.) that issues the certificates for you.</li></ol>Each variant has its own <code class="code">deploy/relay-*/</code> directory with an <code class="code">install.sh</code> script that handles the Q-side setup. On the n8n side, create an Arduino UNO Q Router credential, pick the matching transport (Unix socket / TCP / SSH Relay), fill in the endpoint details, and run Test Connection — the nodes then behave identically to the local setup.<h3>What's next</h3>The packages are published on npm at v0.4.0 (<a href="https://www.npmjs.com/package/n8n-nodes-uno-q">n8n-nodes-uno-q</a>) and the GitHub repo (<a href="https://github.com/RAAS-Impact/n8n-uno-q">raas-impact/n8n-uno-q</a>) has design docs, the docker-compose file, relay tooling, and the integration test sketch.A companion package, <a href="https://www.npmjs.com/package/n8n-nodes-arduino-cloud">n8n-nodes-arduino-cloud</a>, also brings the hosted Arduino Cloud into the same picture: read, write, and stream property values from any Cloud-connected Thing, with the same Property Guard and Rate Limit primitives — so an AI Agent can query a Cloud sensor without you having to worry about quota exhaustion or out-of-range writes. That package has its own Project Hub entry.The next milestone might be submitting a PR to <code class="code">arduino/app-bricks-py </code>(I think that's the proper way...) to get an official N8N Brick shipped in App Lab — a containerized N8N with the community nodes pre-installed, available directly from the App Lab interface. Beyond the practical automation use cases, there is something genuinely satisfying about this setup: the UNO Q stops feeling like a fixed device and starts feeling like something you shape. Wiring the Linux side with N8N flows and watching the MCU respond is, at the end of the day, just a new way to program an Arduino — and a pretty fun one. </body></html>

N8N Workflow Automation on the UNO Q — Sensors, GPIO, and AI Agent Control

Connect n8n workflows to one or more UNO Qs — locally or remotely over TCP, mTLS, or reverse SSH, no proxy needed — and let an AI Agent decide when to read sensors or fire actuators.