MUP1 JS Client

TypeScript library and tools for managing VelocityDRIVE-SP devices over the MUP1 management UART.

The core of the project is a shared library — MUP1 framing, CoAP with block-wise transfer (RFC 7959), and a YANG/SID codec (RFC 9254) — that is used by both the CLI tools and the browser UI:

• CLI tools: mup1-client (ping, config fetch, raw CoAP), yang-cc-util (YANG schema inspection, YAML/JSON ↔ CBOR conversion), mup1-switch-reg (switch register read/write)
• Browser UI: single self-contained HTML file, no server needed, runs in Chrome 89+ via the Web Serial API

Status — read this first

This is an unsupported engineering tool, published as-is. Use it if it helps you; do not rely on it, and do not expect help if it does not work or causes harm. See DISCLAIMER.md for the full statement.

• Developer/debug tool, not a product. It is a companion utility Microchip engineers use to debug VelocityDRIVE-SP devices. On its own it does nothing useful, and it is not intended for end users — it assumes you are a developer who will read the source.
• No SQA / QA process. Not verified, not validated, not feature-complete. Correctness in your environment is not guaranteed.
• Unsupported. No support channel, no SLA, no warranty. It may receive occasional updates at our discretion, but nothing is promised — no roadmap, no release cadence, no commitment.
• Bug reports and pull requests are not accepted — issues and PRs are not monitored (CONTRIBUTING.md). There is no security support (SECURITY.md).
• Use at your own risk. It can read, write, and modify device config, registers, and firmware. Not for production or safety/security-relevant use.
• Fork it — that is the intended model. Under the MIT License you are welcome to fork it and turn it into the tool you need. Your fork is yours to maintain.

License: MIT (see LICENSE).

What's included

Shared library (src/)

Module	Description
src/protocol/	Zero-I/O MUP1 framing, CoAP encode/decode, checksums
src/transport/	ITransport interface, Web Serial and Node.js serial implementations
src/client/	Mup1Client, CoapClient, ping() command
src/yang/	YANG/SID codec — YAML/JSON ↔ CBOR (RFC 9254)

Built artifacts (dist/ after npm run build)

File	Description
dist/cli	mup1-client — ping, config fetch, raw CoAP (get/put/fetch/ipatch)
dist/yang-cc-util	YANG/SID toolkit — schema inspection, YAML/JSON ↔ CBOR
dist/mup1-switch-reg	Switch register read/write utility
dist/mup1-client.html	Single-file browser app (Chrome 89+, Web Serial API)

Building

The recommended way to build is with dr, a thin Docker wrapper that provides a self-contained build environment with Node.js and all dependencies pre-installed — nothing to install on the host beyond Docker itself.

With dr (recommended)

Install dr once:

sudo curl -sSL https://raw.githubusercontent.com/microchip-ung/docker-run/main/dr \
  -o /usr/local/bin/dr && sudo chmod +x /usr/local/bin/dr

Build the Docker image once (requires internet; bakes in all npm dependencies):

./docker/docker-build

Then build and test at any time, offline:

dr npm run build     # produces dist/
dr npm test          # 387 YANG codec round-trip tests

Without dr (Node.js on host)

Requires Node.js 18+ and npm.

npm install
npm run build
npm test

See docs/docker.adoc for full details on the Docker environment.

Prerequisites

• Chrome 89+ (for the browser app only)

Quick start: CLI

# Verify connectivity
node dist/cli ping /dev/ttyUSB0

# Fetch running config (raw CBOR → pipe to cbor-diag for display)
node dist/cli config /dev/ttyUSB0 | cbor-diag

# Status leaves only (non-config)
node dist/cli config /dev/ttyUSB0 -q c=n | cbor-diag

# Save config to file
node dist/cli config /dev/ttyUSB0 -o running.cbor

# Raw CoAP GET with explicit Accept header
node dist/cli coap get /dev/ttyUSB0 c --accept 142 -q c=n | cbor-diag

Quick start: Browser

xdg-open dist/mup1-client.html   # Chrome only

Click Connect, select the VelocityDRIVE-SP UART port, then Ping to verify. The Yang-SHA button fetches the device YANG catalog automatically.

Quick start: Browser over TCP (no serial cable)

The browser app can connect to a device over TCP using a local WebSocket proxy. The proxy bridges the browser's WebSocket connection to the device's MUP1 TCP port, and also serves the YANG catalog on behalf of the browser (avoiding CORS restrictions that block direct downloads from the browser).

1. Start the proxy (in a terminal, once per session):

node dist/ws-proxy 192.168.1.10:4101

The proxy listens on ws://localhost:9101 by default. Use --port to change:

node dist/ws-proxy --port 9102 192.168.1.10:4101

2. Open the browser app in Chrome and connect:

1. Set Transport → TCP (WebSocket proxy)
2. Set Proxy URL → ws://localhost:9101 (adjust port if needed)
3. Click Connect — the YANG catalog downloads automatically via the proxy
4. Click Ping to verify

Windows + WSL: run the proxy in WSL, open mup1-client.html in Windows Chrome. WSL2 forwards localhost ports automatically, so ws://localhost:9101 reaches the proxy from the Windows browser.

Documentation

• docs/index.adoc — architecture, project layout, forking guide
• docs/api.adoc — TypeScript API, full CLI and yang-cc-util reference
• docs/coreconf.adoc — CoAP methods, CORECONF query flags, YAML/JSON request format
• docs/yang-catalog.adoc — catalog pipeline, encode/decode, test vectors
• docs/symreg.adoc — switch register access, CML files, mup1-switch-reg
• docs/extend.adoc — adding commands, transports, browser UI sections, CLI subcommands
• docs/protocol.adoc — MUP1 wire format, CoAP framing, Ruby reference mapping
• docs/docker.adoc — Docker build environment for offline builds

Forking

The project is layered so each level can be replaced independently:

Layer	Role
src/protocol/, src/transport/, src/client/, src/yang/	Shared library — import these directly in your own CLI scripts or UI
src/cli/	Starting point — add, remove, or replace subcommands
src/browser/	Starting point — replace with your own UI framework if desired

See docs/extend.adoc for step-by-step patterns.

Software Bill of Materials (SBOM)

A pre-generated SPDX SBOM of the runtime and build dependencies is committed as sbom.spdx.json. Regenerate it (from package-lock.json, offline, no extra tooling — npm produces it natively) with:

npm run sbom        # writes sbom.spdx.json (SPDX-2.3, JSON)

The committed SBOM is a point-in-time snapshot; treat package-lock.json as the authoritative dependency pin and regenerate the SBOM whenever dependencies change. These dependencies are not monitored for vulnerabilities here — see SECURITY.md.

Legal, disclaimer & license

• DISCLAIMER.md — what this is and is not; unsupported, no warranty, use at your own risk (please read).
• CONTRIBUTING.md — contributions are not accepted; the intended model is to fork.
• SECURITY.md — no security support; do not deploy in production.
• LICENSE — MIT. Copyright (c) 2026 Microchip Technology Inc. and its subsidiaries.

Microchip does not monetize this software and does not provide commercial support or vulnerability handling for it. It is published free of charge as a developer aid and is not placed on the EU market as a product with digital elements.