cncjs-pendant-alexa 0.1.0 → 0.2.0

package/README.md

@@ -37,11 +37,9 @@ Voice is a lossy input, so the pendant refuses instead of trusting:
 ## Install
 
 ```
-npm install -g thcasssio/cncjs-pendant-alexa
+npm install -g 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):

package/assets/icon.svg

@@ -0,0 +1,15 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="512" height="512" viewBox="0 0 512 512">
+  <rect width="512" height="512" rx="96" fill="#0f172a"/>
+  <!-- XY axes -->
+  <line x1="96" y1="288" x2="336" y2="288" stroke="#38bdf8" stroke-width="18" stroke-linecap="round"/>
+  <line x1="216" y1="168" x2="216" y2="408" stroke="#38bdf8" stroke-width="18" stroke-linecap="round"/>
+  <polygon points="336,288 300,268 300,308" fill="#38bdf8"/>
+  <polygon points="216,168 196,204 236,204" fill="#38bdf8"/>
+  <!-- spindle (top view) -->
+  <circle cx="216" cy="288" r="52" fill="none" stroke="#e2e8f0" stroke-width="16"/>
+  <circle cx="216" cy="288" r="14" fill="#f59e0b"/>
+  <!-- voice arcs -->
+  <path d="M 356 208 A 84 84 0 0 1 356 368" fill="none" stroke="#f59e0b" stroke-width="20" stroke-linecap="round"/>
+  <path d="M 396 168 A 140 140 0 0 1 396 408" fill="none" stroke="#f59e0b" stroke-width="20" stroke-linecap="round" opacity="0.6"/>
+  <path d="M 436 128 A 196 196 0 0 1 436 448" fill="none" stroke="#f59e0b" stroke-width="20" stroke-linecap="round" opacity="0.35"/>
+</svg>

package/cloud/.aws-sam/build/SkillFunction/index.js

@@ -0,0 +1,152 @@
+// Alexa endpoint for the published "FluidNC CNCJS Control" skill.
+// Mirrors the local pendant skill (same intents, same speech via the shared
+// lib/ modules copied by cloud/build.sh) but transports commands through the
+// relay to whichever pendant the Alexa account paired with. Adds
+// PairIntent/UnpairIntent for the pairing-code flow.
+
+const Alexa = require('ask-sdk-core');
+const { parseMove, parseGoto, slotId } = require('./lib/intent');
+const { forLocale } = require('./lib/strings');
+const speech = require('./lib/speech');
+const machine = require('./machine');
+
+function t(handlerInput) {
+    return forLocale(Alexa.getLocale(handlerInput.requestEnvelope));
+}
+
+function isOneShot(handlerInput) {
+    const env = handlerInput.requestEnvelope;
+    return Alexa.getRequestType(env) === 'IntentRequest'
+        && !!(env.session && env.session.new)
+        && Alexa.getIntentName(env) !== 'OpenIntent';
+}
+
+function speak(handlerInput, text, { end = false } = {}) {
+    const builder = handlerInput.responseBuilder.speak(text);
+    if (end || isOneShot(handlerInput)) {
+        return builder.withShouldEndSession(true).getResponse();
+    }
+    return builder.reprompt(t(handlerInput).reprompt).getResponse();
+}
+
+function intentHandler(name, handle) {
+    return {
+        canHandle: (h) => Alexa.getRequestType(h.requestEnvelope) === 'IntentRequest'
+            && Alexa.getIntentName(h.requestEnvelope) === name,
+        handle
+    };
+}
+
+async function act(h, action, params) {
+    const s = t(h);
+    const userId = Alexa.getUserId(h.requestEnvelope);
+    const pairing = await machine.getPairing(userId);
+    if (!pairing) {
+        return speak(h, s.needsPairing);
+    }
+    const result = await machine.run(pairing, action, params);
+    return speak(h, speech.forAction(action, result, s));
+}
+
+const LaunchRequestHandler = {
+    canHandle: (h) => Alexa.getRequestType(h.requestEnvelope) === 'LaunchRequest',
+    handle: async (h) => {
+        const pairing = await machine.getPairing(Alexa.getUserId(h.requestEnvelope));
+        return speak(h, pairing ? t(h).launched : t(h).needsPairing);
+    }
+};
+
+const MoveIntentHandler = intentHandler('MoveIntent',
+    (h) => act(h, 'move', parseMove(h.requestEnvelope.request.intent)));
+
+const UpDownIntentHandler = intentHandler('UpDownIntent', (h) => {
+    const slots = (h.requestEnvelope.request.intent || {}).slots || {};
+    const dir = slotId(slots.updown);
+    const sign = dir === 'UP' ? 1 : (dir === 'DOWN' ? -1 : null);
+    const distance = slots.distance && slots.distance.value ? Number(slots.distance.value) : NaN;
+    return act(h, 'move', { axis: 'Z', sign, distance });
+});
+
+const ZMoveIntentHandler = intentHandler('ZMoveIntent',
+    (h) => act(h, 'move', { ...parseMove(h.requestEnvelope.request.intent), axis: 'Z' }));
+
+const GotoIntentHandler = intentHandler('GotoIntent',
+    (h) => act(h, 'goto', { targets: parseGoto(h.requestEnvelope.request.intent) }));
+
+const OpenIntentHandler = intentHandler('OpenIntent', async (h) => {
+    const pairing = await machine.getPairing(Alexa.getUserId(h.requestEnvelope));
+    return speak(h, pairing ? t(h).launched : t(h).needsPairing);
+});
+
+const StopJogIntentHandler = intentHandler('StopJogIntent', (h) => act(h, 'stop'));
+
+const StatusIntentHandler = intentHandler('StatusIntent', (h) => act(h, 'status'));
+
+const PairIntentHandler = intentHandler('PairIntent', async (h) => {
+    const s = t(h);
+    const slots = (h.requestEnvelope.request.intent || {}).slots || {};
+    const raw = slots.code && slots.code.value ? String(slots.code.value) : '';
+    const code = raw.replace(/\D/g, '').padStart(6, '0');
+    if (!/^\d{6}$/.test(code)) {
+        return speak(h, s.pairBadCode);
+    }
+    const result = await machine.pair(Alexa.getUserId(h.requestEnvelope), code);
+    return speak(h, result.ok ? s.pairOk : s.pairBadCode);
+});
+
+const UnpairIntentHandler = intentHandler('UnpairIntent', async (h) => {
+    await machine.unpair(Alexa.getUserId(h.requestEnvelope));
+    return speak(h, t(h).unpairOk, { end: true });
+});
+
+const HelpIntentHandler = intentHandler('AMAZON.HelpIntent', (h) => speak(h, t(h).help));
+
+const ExitHandler = {
+    canHandle: (h) => Alexa.getRequestType(h.requestEnvelope) === 'IntentRequest'
+        && ['CloseIntent', 'AMAZON.StopIntent', 'AMAZON.CancelIntent', 'AMAZON.NavigateHomeIntent']
+            .includes(Alexa.getIntentName(h.requestEnvelope)),
+    handle: async (h) => {
+        const userId = Alexa.getUserId(h.requestEnvelope);
+        const pairing = await machine.getPairing(userId);
+        if (pairing) {
+            await machine.run(pairing, 'stop', {});
+        }
+        return speak(h, t(h).bye, { end: true });
+    }
+};
+
+const FallbackIntentHandler = intentHandler('AMAZON.FallbackIntent',
+    (h) => speak(h, isOneShot(h) ? t(h).fallbackOneShot : t(h).fallback));
+
+const SessionEndedRequestHandler = {
+    canHandle: (h) => Alexa.getRequestType(h.requestEnvelope) === 'SessionEndedRequest',
+    handle: (h) => h.responseBuilder.getResponse()
+};
+
+const ErrorHandler = {
+    canHandle: () => true,
+    handle: (h, error) => {
+        console.error('skill error:', error);
+        return speak(h, t(h).fallback);
+    }
+};
+
+exports.handler = Alexa.SkillBuilders.custom()
+    .addRequestHandlers(
+        LaunchRequestHandler,
+        MoveIntentHandler,
+        UpDownIntentHandler,
+        ZMoveIntentHandler,
+        GotoIntentHandler,
+        OpenIntentHandler,
+        StopJogIntentHandler,
+        StatusIntentHandler,
+        PairIntentHandler,
+        UnpairIntentHandler,
+        HelpIntentHandler,
+        ExitHandler,
+        FallbackIntentHandler,
+        SessionEndedRequestHandler
+    )
+    .addErrorHandlers(ErrorHandler)
+    .lambda();

package/cloud/.aws-sam/build/SkillFunction/lib/intent.js

@@ -0,0 +1,74 @@
+// Pure slot parsing for the Alexa intents. Prefers entity-resolution ids
+// (stable across locales) and falls back to matching the raw spoken value.
+
+const AXIS_WORDS = {
+    x: 'X', xis: 'X', ex: 'X',
+    y: 'Y', 'ípsilon': 'Y', ipsilon: 'Y', why: 'Y',
+    z: 'Z', 'zê': 'Z', ze: 'Z', zee: 'Z', zed: 'Z'
+};
+
+const DIRECTION_WORDS = {
+    mais: 1, positivo: 1, plus: 1, positive: 1,
+    menos: -1, negativo: -1, minus: -1, negative: -1, less: -1
+};
+
+function slotId(slot) {
+    const auths = slot && slot.resolutions && slot.resolutions.resolutionsPerAuthority;
+    if (Array.isArray(auths)) {
+        for (const auth of auths) {
+            if (auth.status && auth.status.code === 'ER_SUCCESS_MATCH'
+                && auth.values && auth.values[0] && auth.values[0].value) {
+                return auth.values[0].value.id;
+            }
+        }
+    }
+    return null;
+}
+
+function parseAxis(slot) {
+    const id = slotId(slot);
+    if (id) {
+        return id;
+    }
+    const raw = slot && slot.value ? String(slot.value).trim().toLowerCase() : '';
+    return AXIS_WORDS[raw] || null;
+}
+
+function parseDirection(slot) {
+    const id = slotId(slot);
+    if (id === 'PLUS') {
+        return 1;
+    }
+    if (id === 'MINUS') {
+        return -1;
+    }
+    const raw = slot && slot.value ? String(slot.value).trim().toLowerCase() : '';
+    return DIRECTION_WORDS[raw] || null;
+}
+
+// -> { axis: 'X'|'Y'|'Z'|null, sign: 1|-1|null, distance: number|NaN }
+function parseMove(intent) {
+    const slots = (intent && intent.slots) || {};
+    const axis = parseAxis(slots.axis);
+    const sign = parseDirection(slots.direction);
+    const distance = (slots.distance && slots.distance.value !== undefined
+        && slots.distance.value !== null && slots.distance.value !== '')
+        ? Number(slots.distance.value)
+        : NaN;
+    return { axis, sign, distance };
+}
+
+// -> { X?: number, Y?: number, Z?: number } (absent = axis not spoken)
+function parseGoto(intent) {
+    const slots = (intent && intent.slots) || {};
+    const out = {};
+    for (const [slot, axis] of [['xVal', 'X'], ['yVal', 'Y'], ['zVal', 'Z']]) {
+        const s = slots[slot];
+        if (s && s.value !== undefined && s.value !== null && s.value !== '') {
+            out[axis] = Number(s.value);
+        }
+    }
+    return out;
+}
+
+module.exports = { parseMove, parseGoto, parseAxis, parseDirection, slotId };

package/cloud/.aws-sam/build/SkillFunction/lib/jog.js

@@ -0,0 +1,105 @@
+// Pure jog logic: validation, state gating and $J= command formatting.
+// Everything here is testable without a network or a machine.
+
+const AXES = ['X', 'Y', 'Z'];
+
+const DEFAULT_LIMITS = {
+    maxXY: 50, // mm per single voice command
+    maxZ: 10,
+    feedXY: 1000, // mm/min
+    feedZ: 300
+};
+
+// Grbl-style jog is only safe when nothing else owns the machine:
+// the sender workflow must be idle and the controller Idle (or already
+// jogging — Grbl 1.1 reports "Jog" while a $J= move runs).
+function canJog({ activeState, workflowState }) {
+    if (workflowState && workflowState !== 'idle') {
+        return { ok: false, reason: 'running' };
+    }
+    if (activeState === 'Idle' || activeState === 'Jog') {
+        return { ok: true };
+    }
+    if (activeState === 'Alarm') {
+        return { ok: false, reason: 'alarm' };
+    }
+    if (!activeState) {
+        return { ok: false, reason: 'disconnected' };
+    }
+    return { ok: false, reason: 'busy' };
+}
+
+function validateMove({ axis, sign, distance }, limits = DEFAULT_LIMITS) {
+    const ax = String(axis || '').toUpperCase();
+    if (!AXES.includes(ax)) {
+        return { ok: false, reason: 'badAxis' };
+    }
+    if (sign !== 1 && sign !== -1) {
+        return { ok: false, reason: 'badDirection' };
+    }
+    const d = Number(distance);
+    if (!Number.isFinite(d) || d <= 0) {
+        return { ok: false, reason: 'badDistance' };
+    }
+    const max = (ax === 'Z') ? limits.maxZ : limits.maxXY;
+    if (d > max) {
+        return { ok: false, reason: 'tooFar', max };
+    }
+    return { ok: true, axis: ax, delta: sign * d };
+}
+
+// 20 -> "20", 20.5 -> "20.5", 0.1234 -> "0.123"
+function formatMm(n) {
+    return String(Math.round(n * 1000) / 1000);
+}
+
+function buildJog(axis, delta, limits = DEFAULT_LIMITS) {
+    const feed = (axis === 'Z') ? limits.feedZ : limits.feedXY;
+    return `$J=G91 G21 ${axis}${formatMm(delta)} F${feed}`;
+}
+
+// Absolute goto in work coordinates ("posição x 130 y 100 z 5").
+// targets: { X?: number, Y?: number, Z?: number } — at least one axis.
+// The same per-axis travel limits apply, measured from the CURRENT work
+// position, so a voice mishearing can never produce a longer move than a
+// relative jog could.
+function validateGoto(targets, wpos, limits = DEFAULT_LIMITS) {
+    const entries = Object.entries(targets).filter(([, v]) => v !== undefined && v !== null);
+    if (entries.length === 0) {
+        return { ok: false, reason: 'missingSlots' };
+    }
+    if (!wpos) {
+        return { ok: false, reason: 'disconnected' };
+    }
+    const clean = {};
+    for (const [axis, value] of entries) {
+        const ax = String(axis).toUpperCase();
+        const target = Number(value);
+        const current = Number(wpos[ax.toLowerCase()]);
+        if (!AXES.includes(ax)) {
+            return { ok: false, reason: 'badAxis' };
+        }
+        if (!Number.isFinite(target)) {
+            return { ok: false, reason: 'badDistance' };
+        }
+        if (!Number.isFinite(current)) {
+            return { ok: false, reason: 'disconnected' };
+        }
+        const max = (ax === 'Z') ? limits.maxZ : limits.maxXY;
+        if (Math.abs(target - current) > max) {
+            return { ok: false, reason: 'tooFar', max, axis: ax };
+        }
+        clean[ax] = target;
+    }
+    return { ok: true, targets: clean };
+}
+
+function buildGoto(targets, limits = DEFAULT_LIMITS) {
+    const feed = (targets.Z !== undefined) ? limits.feedZ : limits.feedXY;
+    const parts = AXES.filter((a) => targets[a] !== undefined)
+        .map((a) => `${a}${formatMm(targets[a])}`)
+        .join(' ');
+    return `$J=G90 G21 ${parts} F${feed}`;
+}
+
+module.exports = { AXES, DEFAULT_LIMITS, canJog, validateMove, buildJog, validateGoto, buildGoto, formatMm };

package/cloud/.aws-sam/build/SkillFunction/lib/speech.js

@@ -0,0 +1,64 @@
+// Renders action results (actions.js) into spoken text. Shared verbatim by
+// the local skill endpoint and the cloud relay Lambda so both modes answer
+// identically.
+
+const { formatMm } = require('./jog');
+const { speakNumber } = require('./strings');
+
+function refusal(result, s) {
+    switch (result.reason) {
+        case 'running': return s.running;
+        case 'alarm': return s.alarm;
+        case 'busy': return s.busy;
+        case 'disconnected': return s.disconnected;
+        case 'tooFar': return s.tooFar(result.max);
+        case 'badDistance': return s.badDistance;
+        default: return s.missingSlots;
+    }
+}
+
+function moveSpeech(result, s) {
+    if (!result.ok) {
+        return refusal(result, s);
+    }
+    const dirWord = (result.delta > 0) ? s.dirPlus : s.dirMinus;
+    const dist = speakNumber(formatMm(Math.abs(result.delta)), s);
+    return s.moved(s.axisNames[result.axis], dirWord, dist);
+}
+
+function gotoSpeech(result, s) {
+    if (!result.ok) {
+        return refusal(result, s);
+    }
+    const parts = Object.entries(result.targets)
+        .map(([axis, v]) => `${s.axisNames[axis]} ${speakNumber(v, s)}`)
+        .join(', ');
+    return s.goingTo(parts);
+}
+
+function statusSpeech(result, s) {
+    if (!result.ok) {
+        return refusal(result, s);
+    }
+    return s.position(
+        speakNumber(result.wpos.x, s),
+        speakNumber(result.wpos.y, s),
+        speakNumber(result.wpos.z, s)
+    );
+}
+
+function stopSpeech(result, s) {
+    return result.ok ? s.stopped : refusal(result, s);
+}
+
+function forAction(action, result, s) {
+    switch (action) {
+        case 'move': return moveSpeech(result, s);
+        case 'goto': return gotoSpeech(result, s);
+        case 'status': return statusSpeech(result, s);
+        case 'stop': return stopSpeech(result, s);
+        default: return refusal(result || { reason: 'missingSlots' }, s);
+    }
+}
+
+module.exports = { forAction, refusal };

package/cloud/.aws-sam/build/SkillFunction/lib/strings.js

@@ -0,0 +1,82 @@
+// Spoken responses per locale. Numbers are localized (decimal comma for pt).
+
+const LOCALES = {
+    'pt': {
+        decimalComma: true,
+        minusWord: 'menos',
+        axisNames: { X: 'xis', Y: 'ípsilon', Z: 'zê' },
+        launched: 'Modo CNC ativo. Pode mandar, por exemplo: xis mais vinte. Fale fechar para sair.',
+        reprompt: 'Modo CNC ativo. Mande o próximo movimento ou fale fechar.',
+        moved: (axis, dirWord, dist) => `Movendo ${axis} ${dirWord} ${dist} milímetros.`,
+        goingTo: (parts) => `Indo para ${parts}.`,
+        dirPlus: 'mais',
+        dirMinus: 'menos',
+        tooFar: (max) => `Isso passa do limite de ${max} milímetros por comando. Não vou mover.`,
+        running: 'A máquina está executando um trabalho. Não vou mover.',
+        alarm: 'A máquina está em alarme. Destrave pelo painel antes de mover.',
+        busy: 'A máquina está ocupada agora. Tente quando ela estiver parada.',
+        disconnected: 'Estou sem conexão com a máquina.',
+        stopped: 'Parado.',
+        position: (x, y, z) => `Posição de trabalho: xis ${x}, ípsilon ${y}, zê ${z}.`,
+        missingSlots: 'Não entendi o movimento. Diga o eixo, a direção e a distância. Por exemplo: xis mais vinte.',
+        badDistance: 'Não entendi a distância. Diga um número de milímetros maior que zero.',
+        help: 'Diga um eixo, uma direção e uma distância em milímetros. Por exemplo: xis mais vinte. Para o eixo zê, o mais fácil é: sobe dez, ou desce cinco. Diga para, para cancelar um movimento, ou posição, para saber onde o spindle está.',
+        bye: 'Saindo do modo CNC.',
+        fallback: 'Alexa está em modo CNC. Fale fechar para sair do modo CNC. Para mover, diga por exemplo: xis mais vinte.',
+        fallbackOneShot: 'Não entendi o comando. Diga por exemplo: peça para fresa xis mais vinte, ou zeta mais dez.',
+        needsPairing: 'Sua Alexa ainda não está pareada com uma máquina. Instale o pendant cncjs pendant alexa no computador do cncjs com a opção cloud, pegue o código de seis dígitos que ele mostra, e diga: parear, seguido do código.',
+        pairOk: 'Pareado com sucesso. Pode mandar, por exemplo: xis mais vinte.',
+        pairBadCode: 'Código inválido ou expirado. Confira o código de seis dígitos no pendant e diga: parear, seguido do código.',
+        unpairOk: 'Pareamento desfeito.'
+    },
+    'en': {
+        decimalComma: false,
+        minusWord: 'minus',
+        axisNames: { X: 'x', Y: 'y', Z: 'z' },
+        launched: 'CNC mode active. Try, for example: x plus twenty. Say close to exit.',
+        reprompt: 'CNC mode active. Send the next move or say close.',
+        moved: (axis, dirWord, dist) => `Moving ${axis} ${dirWord} ${dist} millimeters.`,
+        goingTo: (parts) => `Going to ${parts}.`,
+        dirPlus: 'plus',
+        dirMinus: 'minus',
+        tooFar: (max) => `That exceeds the limit of ${max} millimeters per command. Not moving.`,
+        running: 'The machine is running a job. Not moving.',
+        alarm: 'The machine is in alarm. Unlock it from the panel before moving.',
+        busy: 'The machine is busy right now. Try when it is idle.',
+        disconnected: 'I have no connection to the machine.',
+        stopped: 'Stopped.',
+        position: (x, y, z) => `Work position: x ${x}, y ${y}, z ${z}.`,
+        missingSlots: 'I did not get that move. Say the axis, the direction and the distance. For example: x plus twenty.',
+        badDistance: 'I did not get the distance. Say a number of millimeters greater than zero.',
+        help: 'Say an axis, a direction and a distance in millimeters. For example: x plus twenty, or z minus five. Say stop to cancel a move, or position to know where the spindle is.',
+        bye: 'Leaving CNC mode.',
+        fallback: 'Alexa is in CNC mode. Say close to exit CNC mode. To move, say for example: x plus twenty.',
+        fallbackOneShot: 'I did not get that command. Say for example: ask mill x plus twenty.',
+        needsPairing: 'Your Alexa is not paired with a machine yet. Install the cncjs pendant alexa on your cncjs computer with the cloud option, take the six digit code it shows, and say: pair, followed by the code.',
+        pairOk: 'Paired successfully. Try, for example: x plus twenty.',
+        pairBadCode: 'Invalid or expired code. Check the six digit code on the pendant and say: pair, followed by the code.',
+        unpairOk: 'Unpaired.'
+    }
+};
+
+function forLocale(locale) {
+    const lang = String(locale || 'en').slice(0, 2).toLowerCase();
+    return LOCALES[lang] || LOCALES.en;
+}
+
+// "25.500" -> "25.5" / "-2.000" -> "menos 2" (spoken-friendly)
+function speakNumber(value, t) {
+    let n = Number(value);
+    if (!Number.isFinite(n)) {
+        return String(value);
+    }
+    n = Math.round(n * 1000) / 1000;
+    const negative = n < 0;
+    let s = String(Math.abs(n));
+    if (t.decimalComma) {
+        s = s.replace('.', ',');
+    }
+    return negative ? `${t.minusWord} ${s}` : s;
+}
+
+module.exports = { forLocale, speakNumber };

package/cloud/.aws-sam/build/SkillFunction/machine.js

@@ -0,0 +1,164 @@
+// Pairing resolution and command transport for the skill Lambda.
+// Two machine kinds: a real pendant (command over WebSocket, correlated
+// response polled from DynamoDB) and the DEMO machine (simulated in the
+// pairing item) used by Amazon certification testers and curious users.
+
+const crypto = require('crypto');
+const { DynamoDBClient } = require('@aws-sdk/client-dynamodb');
+const { DynamoDBDocumentClient, GetCommand, PutCommand, UpdateCommand, DeleteCommand } = require('@aws-sdk/lib-dynamodb');
+const { ApiGatewayManagementApiClient, PostToConnectionCommand } = require('@aws-sdk/client-apigatewaymanagementapi');
+const { validateMove, validateGoto, DEFAULT_LIMITS } = require('./lib/jog');
+
+const ddb = DynamoDBDocumentClient.from(new DynamoDBClient({}));
+const mgmt = new ApiGatewayManagementApiClient({ endpoint: process.env.WS_ENDPOINT });
+
+const PENDANTS = process.env.PENDANTS_TABLE;
+const PAIRINGS = process.env.PAIRINGS_TABLE;
+const CODES = process.env.CODES_TABLE;
+const RESPONSES = process.env.RESPONSES_TABLE;
+
+const DEMO_CODE = '123456';
+const DEMO_PENDANT = 'DEMO';
+const RESPONSE_TIMEOUT_MS = 6000;
+const POLL_MS = 150;
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const fmt = (n) => (Math.round(n * 1000) / 1000).toFixed(3);
+
+async function getPairing(userId) {
+    const item = (await ddb.send(new GetCommand({
+        TableName: PAIRINGS, Key: { userId }
+    }))).Item;
+    return item || null;
+}
+
+async function pair(userId, code) {
+    let pendantId;
+    if (code === DEMO_CODE) {
+        pendantId = DEMO_PENDANT;
+    } else {
+        const item = (await ddb.send(new GetCommand({
+            TableName: CODES, Key: { code }
+        }))).Item;
+        if (!item || item.ttl < Math.floor(Date.now() / 1000)) {
+            return { ok: false };
+        }
+        pendantId = item.pendantId;
+        await ddb.send(new DeleteCommand({ TableName: CODES, Key: { code } }));
+    }
+    await ddb.send(new PutCommand({
+        TableName: PAIRINGS,
+        Item: { userId, pendantId, demo: { x: 0, y: 0, z: 0 }, pairedAt: Date.now() }
+    }));
+    if (pendantId !== DEMO_PENDANT) {
+        await ddb.send(new UpdateCommand({
+            TableName: PENDANTS,
+            Key: { pendantId },
+            UpdateExpression: 'SET pairedUserId = :u',
+            ExpressionAttributeValues: { ':u': userId }
+        }));
+        const pendant = (await ddb.send(new GetCommand({
+            TableName: PENDANTS, Key: { pendantId }
+        }))).Item;
+        if (pendant && pendant.connectionId) {
+            try {
+                await mgmt.send(new PostToConnectionCommand({
+                    ConnectionId: pendant.connectionId,
+                    Data: JSON.stringify({ type: 'paired' })
+                }));
+            } catch (err) { /* pendant offline; it learns on next register */ }
+        }
+    }
+    return { ok: true };
+}
+
+async function unpair(userId) {
+    const pairing = await getPairing(userId);
+    if (pairing && pairing.pendantId !== DEMO_PENDANT) {
+        await ddb.send(new UpdateCommand({
+            TableName: PENDANTS,
+            Key: { pendantId: pairing.pendantId },
+            UpdateExpression: 'SET pairedUserId = :n',
+            ExpressionAttributeValues: { ':n': null }
+        }));
+    }
+    await ddb.send(new DeleteCommand({ TableName: PAIRINGS, Key: { userId } }));
+}
+
+// Demo machine: same validation rules as a real pendant, position kept in
+// the pairing item so reviewers get coherent status readouts.
+async function runDemo(pairing, action, params) {
+    const pos = pairing.demo || { x: 0, y: 0, z: 0 };
+    const wpos = { x: fmt(pos.x), y: fmt(pos.y), z: fmt(pos.z) };
+    if (action === 'status') {
+        return { ok: true, wpos, activeState: 'Idle' };
+    }
+    if (action === 'stop') {
+        return { ok: true };
+    }
+    let next = { ...pos };
+    let result;
+    if (action === 'move') {
+        const valid = validateMove(params, DEFAULT_LIMITS);
+        if (!valid.ok) {
+            return valid;
+        }
+        next[valid.axis.toLowerCase()] += valid.delta;
+        result = { ok: true, axis: valid.axis, delta: valid.delta };
+    } else if (action === 'goto') {
+        const valid = validateGoto(params.targets || params, wpos, DEFAULT_LIMITS);
+        if (!valid.ok) {
+            return valid;
+        }
+        for (const [axis, value] of Object.entries(valid.targets)) {
+            next[axis.toLowerCase()] = value;
+        }
+        result = { ok: true, targets: valid.targets };
+    } else {
+        return { ok: false, reason: 'badAction' };
+    }
+    await ddb.send(new UpdateCommand({
+        TableName: PAIRINGS,
+        Key: { userId: pairing.userId },
+        UpdateExpression: 'SET demo = :d',
+        ExpressionAttributeValues: { ':d': next }
+    }));
+    return result;
+}
+
+async function runRemote(pairing, action, params) {
+    const pendant = (await ddb.send(new GetCommand({
+        TableName: PENDANTS, Key: { pendantId: pairing.pendantId }
+    }))).Item;
+    if (!pendant || !pendant.connectionId) {
+        return { ok: false, reason: 'disconnected' };
+    }
+    const id = crypto.randomUUID();
+    try {
+        await mgmt.send(new PostToConnectionCommand({
+            ConnectionId: pendant.connectionId,
+            Data: JSON.stringify({ type: 'cmd', id, action, params })
+        }));
+    } catch (err) {
+        return { ok: false, reason: 'disconnected' };
+    }
+    const deadline = Date.now() + RESPONSE_TIMEOUT_MS;
+    while (Date.now() < deadline) {
+        await sleep(POLL_MS);
+        const item = (await ddb.send(new GetCommand({
+            TableName: RESPONSES, Key: { id }
+        }))).Item;
+        if (item) {
+            return item.result;
+        }
+    }
+    return { ok: false, reason: 'disconnected' };
+}
+
+function run(pairing, action, params) {
+    return (pairing.pendantId === DEMO_PENDANT)
+        ? runDemo(pairing, action, params)
+        : runRemote(pairing, action, params);
+}
+
+module.exports = { getPairing, pair, unpair, run, DEMO_CODE };