cncjs-pendant-alexa 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cassio Simoes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,147 @@
+# cncjs-pendant-alexa
+
+Voice jog control for [cncjs](https://github.com/cncjs/cncjs) through a custom
+Alexa skill:
+
+> One-shot: "Alexa, **ask mill x plus 20**" — or open CNC mode: "Alexa,
+> open **mill**" … "**x plus 20**" … "**position x 130 y 100**" … "**close**"
+>
+> One-shot: "Alexa, **peça pra fresa xis mais vinte**" — ou modo CNC:
+> "Alexa, abrir **fresa**" … "**xis mais vinte**" … "**fechar**"
+
+Numbers are millimeters. The pendant connects to the cncjs server's socket.io
+API (like any other `cncjs-pendant-*`), sends Grbl `$J=` jog commands and
+exposes a small HTTPS-tunneled endpoint that your own Alexa developer skill
+calls. No cloud service in the middle besides Alexa itself; no skill-store
+publication needed (a development-mode skill works forever on the Echos of
+your Amazon account, for free).
+
+Interaction models for **en-US** and **pt-BR** are included, ready to paste.
+
+## Safety model
+
+Voice is a lossy input, so the pendant refuses instead of trusting:
+
+- Only `$J=` jog commands are ever sent — cancellable instantly, no parser
+  state pollution. Never raw `G0/G1`.
+- Per-command travel limits (default: 50 mm on X/Y, 10 mm on Z). Asking for
+  200 mm gets a spoken refusal, not a move.
+- Jogs are refused unless the controller is `Idle`/`Jog` **and** the cncjs
+  workflow is idle — a running job can never be disturbed.
+- `Alarm` is reported, never auto-unlocked by voice.
+- Z uses a slower feed rate than X/Y (defaults: F300 vs F1000).
+- "halt" / "para" (and exiting the skill) send Grbl jog-cancel (`0x85`).
+- Every request is cryptographically verified as coming from Alexa
+  (certificate + timestamp) and, with `--skill-id`, from *your* skill only.
+
+## Install
+
+```
+npm install -g thcasssio/cncjs-pendant-alexa
+```
+
+(Installs straight from GitHub; an npm registry release will follow.)
+
+Run it on the same host as the cncjs server (it reads the `secret` from the
+server's `~/.cncrc` to authenticate, exactly like the other community
+pendants):
+
+```
+cncjs-pendant-alexa --port /dev/ttyUSB0 --skill-id amzn1.ask.skill.xxxx
+```
+
+Options: `--baudrate 115200`, `--cncjs-url ws://127.0.0.1:8000`,
+`--http-port 8977`, `--http-path /alexa`, `--secret-file /home/cnc/.cncrc`,
+`--max-xy 50 --max-z 10 --feed-xy 1000 --feed-z 300`,
+`--controller-type Grbl`.
+
+Sanity check (connects, prints machine state as JSON, exits):
+
+```
+cncjs-pendant-alexa --port /dev/ttyUSB0 --check
+```
+
+## Set up the Alexa skill (one time, ~15 min, free)
+
+1. **HTTPS tunnel** — Alexa must reach your endpoint over public HTTPS with a
+   valid certificate. Easiest free option: [ngrok](https://ngrok.com) with the
+   one free **static domain** every account gets
+   (`ngrok http 8977 --url=yourname.ngrok-free.app`). Alternatives: Cloudflare
+   Tunnel (if you own a domain) or Tailscale Funnel. See
+   `examples/systemd/alexa-tunnel-ngrok.service`.
+2. Go to the [Alexa developer console](https://developer.amazon.com/alexa/console/ask)
+   → **Create Skill** → name it (e.g. "CNC Pendant") → primary locale
+   **English (US)** or **Portuguese (BR)** → type **Custom** → host
+   **Provision your own**.
+3. In **Build → Interaction Model → JSON Editor**, paste
+   [`models/en-US.json`](models/en-US.json) or
+   [`models/pt-BR.json`](models/pt-BR.json) (add the other locale under
+   **Language Settings** if you want both) → **Save Model** → **Build Model**.
+4. In **Build → Endpoint**, choose **HTTPS**, set the default region to
+   `https://yourname.ngrok-free.app/alexa`, and pick the SSL certificate type
+   that matches your host — **this choice matters and the errors it causes are
+   silent**:
+   - Behind **Cloudflare** (or any host whose certificate covers your
+     subdomain via a wildcard like `*.example.com`): pick *"My development
+     endpoint is a sub-domain of a domain that has a wildcard certificate"*
+     (`Wildcard`).
+   - Only if the certificate names your exact hostname: *"...has a certificate
+     from a trusted certificate authority"* (`Trusted`).
+
+   With the wrong type, Alexa rejects the TLS handshake before any request
+   reaches you, and the simulator only says "endpoint error". The
+   [skill invocation API](https://developer.amazon.com/en-US/docs/alexa/smapi/skill-invocation-api.html)
+   is the one tool that reports the real reason (e.g. *"Certificate for host
+   contains wildcard"*).
+5. Copy **Your Skill ID** (top of the Endpoint page) and pass it to the
+   pendant via `--skill-id`.
+6. In **Test**, enable testing in **Development**. The skill is now live on
+   every Echo logged into your account — no certification, no publication.
+
+## Run as a service
+
+Copy the units from `examples/systemd/`, edit port/skill-id/domain:
+
+```
+sudo cp examples/systemd/*.service /etc/systemd/system/
+sudo systemctl daemon-reload
+sudo systemctl enable --now cncjs-pendant-alexa alexa-tunnel-ngrok
+```
+
+`GET /healthz` on the HTTP port reports the live machine state for monitoring.
+
+## Voice reference
+
+The default invocation name is **"mill"** (pt-BR: **"fresa"**) — change the
+`invocationName` in the model JSON to whatever you prefer before pasting it. Every command
+works one-shot ("Alexa, ask my mill x plus 20") or inside CNC mode ("Alexa, open
+c. n. c.", then bare commands). While CNC mode is open, unrelated phrases get
+a spoken reminder that Alexa is in CNC mode and how to leave; Alexa closes an
+idle session on its own after a few seconds of silence (platform limit — a
+custom skill cannot hold the microphone open indefinitely).
+
+| Intent | en-US | pt-BR |
+|---|---|---|
+| Move (relative) | "x plus 20", "move y minus 5" | "xis mais vinte", "mover y menos cinco" |
+| Go to (absolute, 1-3 axes) | "position x 130 y 100 z 5", "go to x 50" | "posição x 130 y 100 z 5", "vai para x 50" |
+| Cancel jog | "halt", "stop moving" | "para", "pare" |
+| Position | "where are you", "position" | "onde está", "posição" |
+| Help | "help" | "ajuda" |
+| Exit CNC mode | "close", "exit cnc mode" | "fechar", "sair do modo cnc" |
+
+Absolute moves use work coordinates and the same per-axis travel limits,
+measured from the current position.
+
+## Development
+
+```
+npm test          # unit tests (jog math, state gating, slot parsing)
+node bin/cncjs-pendant-alexa --port /dev/ttyUSB0 --no-verify   # local testing
+```
+
+`--no-verify` disables Alexa signature verification so you can `curl` synthetic
+request envelopes at the endpoint. Never expose an unverified endpoint.
+
+## License
+
+MIT

package/bin/cncjs-pendant-alexa

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+require('../src/cli').main(process.argv);

package/examples/systemd/alexa-tunnel-ngrok.service

@@ -0,0 +1,15 @@
+[Unit]
+Description=HTTPS tunnel for the Alexa pendant endpoint (ngrok free static domain)
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+# One free static domain per ngrok account: https://dashboard.ngrok.com/domains
+# First run once: ngrok config add-authtoken <token>
+User=cncjs
+ExecStart=/usr/local/bin/ngrok http 8977 --url=REPLACE-ME.ngrok-free.app
+Restart=always
+RestartSec=5
+
+[Install]
+WantedBy=multi-user.target

package/examples/systemd/cncjs-pendant-alexa.service

@@ -0,0 +1,20 @@
+[Unit]
+Description=cncjs Alexa voice pendant
+After=network-online.target cncjs.service
+Wants=network-online.target
+
+[Service]
+# Must run as a user that can read the cncjs server's ~/.cncrc (the "secret"),
+# or pass --secret-file pointing at it.
+User=cncjs
+ExecStart=/usr/bin/env cncjs-pendant-alexa \
+    --port /dev/ttyUSB0 \
+    --baudrate 115200 \
+    --cncjs-url ws://127.0.0.1:8000 \
+    --http-port 8977 \
+    --skill-id amzn1.ask.skill.REPLACE-WITH-YOUR-SKILL-ID
+Restart=always
+RestartSec=5
+
+[Install]
+WantedBy=multi-user.target

package/models/en-US.json

@@ -0,0 +1,254 @@
+{
+  "interactionModel": {
+    "languageModel": {
+      "invocationName": "mill",
+      "intents": [
+        {
+          "name": "AMAZON.CancelIntent",
+          "samples": []
+        },
+        {
+          "name": "AMAZON.HelpIntent",
+          "samples": []
+        },
+        {
+          "name": "AMAZON.StopIntent",
+          "samples": []
+        },
+        {
+          "name": "AMAZON.NavigateHomeIntent",
+          "samples": []
+        },
+        {
+          "name": "AMAZON.FallbackIntent",
+          "samples": []
+        },
+        {
+          "name": "MoveIntent",
+          "slots": [
+            {
+              "name": "axis",
+              "type": "AXIS_TYPE"
+            },
+            {
+              "name": "direction",
+              "type": "DIRECTION_TYPE"
+            },
+            {
+              "name": "distance",
+              "type": "AMAZON.NUMBER"
+            }
+          ],
+          "samples": [
+            "{axis} {direction} {distance}",
+            "{axis} {direction} {distance} millimeters",
+            "{axis} {direction} {distance} millimeter",
+            "move {axis} {direction} {distance}",
+            "move the {axis} axis {direction} {distance}",
+            "jog {axis} {direction} {distance}",
+            "axis {axis} {direction} {distance}"
+          ]
+        },
+        {
+          "name": "StopJogIntent",
+          "samples": [
+            "halt",
+            "stop moving",
+            "stop the move",
+            "cancel the move",
+            "cancel the jog"
+          ]
+        },
+        {
+          "name": "StatusIntent",
+          "samples": [
+            "where are you",
+            "where is the spindle",
+            "position",
+            "what is the position",
+            "status"
+          ]
+        },
+        {
+          "name": "CloseIntent",
+          "samples": [
+            "close",
+            "close cnc",
+            "exit",
+            "exit cnc mode",
+            "leave cnc mode"
+          ]
+        },
+        {
+          "name": "GotoIntent",
+          "slots": [
+            {
+              "name": "xVal",
+              "type": "AMAZON.NUMBER"
+            },
+            {
+              "name": "yVal",
+              "type": "AMAZON.NUMBER"
+            },
+            {
+              "name": "zVal",
+              "type": "AMAZON.NUMBER"
+            }
+          ],
+          "samples": [
+            "position x {xVal}",
+            "position y {yVal}",
+            "position z {zVal}",
+            "position x {xVal} y {yVal}",
+            "position x {xVal} z {zVal}",
+            "position y {yVal} z {zVal}",
+            "position x {xVal} y {yVal} z {zVal}",
+            "go to x {xVal}",
+            "go to x {xVal} y {yVal}",
+            "go to x {xVal} y {yVal} z {zVal}",
+            "go to position x {xVal} y {yVal} z {zVal}",
+            "go to z {zVal}"
+          ]
+        },
+        {
+          "name": "OpenIntent",
+          "samples": [
+            "open",
+            "start",
+            "enter cnc mode",
+            "cnc mode"
+          ]
+        },
+        {
+          "name": "UpDownIntent",
+          "slots": [
+            {
+              "name": "updown",
+              "type": "UPDOWN_TYPE"
+            },
+            {
+              "name": "distance",
+              "type": "AMAZON.NUMBER"
+            }
+          ],
+          "samples": [
+            "{updown} {distance}",
+            "{updown} {distance} millimeters"
+          ]
+        },
+        {
+          "name": "ZMoveIntent",
+          "slots": [
+            {
+              "name": "direction",
+              "type": "DIRECTION_TYPE"
+            },
+            {
+              "name": "distance",
+              "type": "AMAZON.NUMBER"
+            }
+          ],
+          "samples": [
+            "z {direction} {distance}",
+            "zed {direction} {distance}",
+            "zee {direction} {distance}",
+            "z axis {direction} {distance}",
+            "z {direction} {distance} millimeters"
+          ]
+        }
+      ],
+      "types": [
+        {
+          "name": "AXIS_TYPE",
+          "values": [
+            {
+              "id": "X",
+              "name": {
+                "value": "x",
+                "synonyms": [
+                  "ex"
+                ]
+              }
+            },
+            {
+              "id": "Y",
+              "name": {
+                "value": "y",
+                "synonyms": [
+                  "why"
+                ]
+              }
+            },
+            {
+              "id": "Z",
+              "name": {
+                "value": "z",
+                "synonyms": [
+                  "zee",
+                  "zed"
+                ]
+              }
+            }
+          ]
+        },
+        {
+          "name": "DIRECTION_TYPE",
+          "values": [
+            {
+              "id": "PLUS",
+              "name": {
+                "value": "plus",
+                "synonyms": [
+                  "positive",
+                  "forward"
+                ]
+              }
+            },
+            {
+              "id": "MINUS",
+              "name": {
+                "value": "minus",
+                "synonyms": [
+                  "negative",
+                  "back"
+                ]
+              }
+            }
+          ]
+        },
+        {
+          "name": "UPDOWN_TYPE",
+          "values": [
+            {
+              "id": "UP",
+              "name": {
+                "value": "up",
+                "synonyms": [
+                  "raise",
+                  "go up",
+                  "move up"
+                ]
+              }
+            },
+            {
+              "id": "DOWN",
+              "name": {
+                "value": "down",
+                "synonyms": [
+                  "lower",
+                  "go down",
+                  "move down"
+                ]
+              }
+            }
+          ]
+        }
+      ],
+      "modelConfiguration": {
+        "fallbackIntentSensitivity": {
+          "level": "HIGH"
+        }
+      }
+    }
+  }
+}