meshcore-ts

TypeScript library for connecting to and working with MeshCore companion devices. Supports communication over Web Serial, Web Bluetooth (BLE), and any custom transport you implement.

Installation

npm install meshcore-ts
# or
pnpm add meshcore-ts

Quick start

Connect over Web Serial (browser)

import { WebSerialConnection } from "meshcore-ts";

// Prompts the user to pick a serial port (115200 baud).
const conn = await WebSerialConnection.open();
if (!conn) throw new Error("No port selected");

conn.on("connected", async () => {
    console.log("Connected to companion!");

    // Fetch device info
    const info = await conn.sendCommandDeviceQuery();
    console.log("Device info:", info);

    // Get all contacts
    const contacts = await conn.sendCommandGetContacts();
    console.log("Contacts:", contacts);
});

conn.on("disconnected", () => {
    console.log("Disconnected.");
});

Connect over BLE (browser)

import { WebBleConnection } from "meshcore-ts";

// Shows the browser Bluetooth device picker.
const conn = await WebBleConnection.open();
if (!conn) throw new Error("No device selected");

conn.on("connected", async () => {
    const info = await conn.sendCommandDeviceQuery();
    console.log("Device info:", info);
});

Send a direct message to a contact

import { WebSerialConnection, Constants } from "meshcore-ts";

const conn = await WebSerialConnection.open();

conn.on("connected", async () => {
    const contacts = await conn.sendCommandGetContacts();
    const alice = contacts.find(c => c.advName === "Alice");
    if (!alice) return;

    await conn.sendCommandSendTxtMsg(
        Constants.CommandCodes.SendTxtMsg, // txtType
        0,                                 // attempt
        Math.floor(Date.now() / 1000),     // senderTimestamp
        alice.publicKey.slice(0, 6),       // pubKeyPrefix
        "Hello from meshcore-ts!",         // text
    );
});

Send a channel message

conn.on("connected", async () => {
    const channelIndex = 0;
    await conn.sendCommandSendChannelTxtMsg(
        0,                               // txtType
        channelIndex,
        Math.floor(Date.now() / 1000),
        "Hello channel!",
    );
});

Listen for incoming messages

conn.on("contactMessage", (msg) => {
    console.log(`[DM from ${msg.senderPubKeyPrefix}]:`, msg.text);
});

conn.on("channelMessage", (msg) => {
    console.log(`[Channel ${msg.channelIdx}]:`, msg.text);
});

Parse an advertisement

import { Advert } from "meshcore-ts";

const raw = new Uint8Array([ /* raw advertisement bytes */ ]);
const advert = Advert.fromBytes(raw);

console.log("Node name:", advert.parsed.name);
console.log("Node type:", advert.parsed.type); // "CHAT" | "REPEATER" | "ROOM" | "SENSOR" | "NONE"
console.log("Location:", advert.parsed.lat, advert.parsed.lon);

const valid = await advert.isVerified();
console.log("Signature valid:", valid);

Parse a mesh packet

import { Packet } from "meshcore-ts";

const raw = new Uint8Array([ /* raw packet bytes */ ]);
const packet = Packet.fromBytes(raw);

console.log("Route type:", packet.route_type_string);    // "DIRECT" | "FLOOD" | ...
console.log("Payload type:", packet.payload_type_string); // "TXT_MSG" | "ADVERT" | ...

Decode Cayenne LPP telemetry

import { CayenneLpp } from "meshcore-ts";

const raw = new Uint8Array([ /* raw LPP bytes */ ]);
const records = CayenneLpp.decode(raw);

for (const record of records) {
    console.log(`ch=${record.channel} type=${record.type} value=${JSON.stringify(record.value)}`);
}

Derive a hashtag region transport key

import { TransportKeyUtil } from "meshcore-ts";

const key = await TransportKeyUtil.getHashtagRegionKey("#mygroup");
console.log("Key (hex):", Buffer.from(key).toString("hex"));

API reference

WebSerialConnection

Transport over the browser Web Serial API.

| Member | Description | |--------|-------------| | static open() | Prompts user for port → returns a connected instance | | close() | Closes the serial port | | (all Connection methods) | Inherited |

WebBleConnection

Transport over the browser Web Bluetooth API.

| Member | Description | |--------|-------------| | static open() | Shows Bluetooth device picker → returns a connected instance | | (all Connection methods) | Inherited |

Connection (base class)

Provides the full companion protocol command/response API.

| Method | Returns | Description | |--------|---------|-------------| | sendCommandAppStart() | Promise<void> | Initiates the companion app handshake | | sendCommandDeviceQuery() | Promise<DeviceInfoResponse> | Queries firmware/hardware info | | sendCommandGetContacts(since?) | Promise<MeshContactRecord[]> | Fetches the contact list | | sendCommandSendTxtMsg(...) | Promise<SentResponse> | Sends a direct text message | | sendCommandSendChannelTxtMsg(...) | Promise<SentResponse> | Sends a channel text message | | sendCommandGetDeviceTime() | Promise<CurrTimeResponse> | Reads device clock | | sendCommandSetDeviceTime(ts) | Promise<OkResponse> | Sets device clock | | sendCommandSendSelfAdvert() | Promise<OkResponse> | Broadcasts a self-advertisement | | sendCommandSetAdvertName(name) | Promise<OkResponse> | Sets the node's advertised name | | sendCommandGetBatteryVoltage() | Promise<BatteryVoltageResponse> | Reads battery voltage | | sendCommandGetChannel(idx) | Promise<ChannelDataResponse> | Reads a stored channel | | sendCommandSetChannel(idx, ...) | Promise<OkResponse> | Writes a channel | | sendCommandReboot() | Promise<void> | Reboots the companion | | (more…) | — | See source for full list |

Events emitted by Connection

| Event | Payload type | Fired when | |-------|-------------|------------| | "connected" | — | Transport connected and handshake done | | "disconnected" | — | Transport disconnected | | "contactMessage" | ContactMessageResponse | A direct message arrived | | "channelMessage" | ChannelMessageResponse | A channel message arrived | | "telemetry" | TelemetryResponsePush | Telemetry push received | | "traceData" | TraceDataPush | Trace-path data received | | "statusResponse" | StatusResponsePush | Status response push | | "logRxData" | LogRxDataPush | Raw RX log data | | "rx" | ByteArrayLike | Raw inbound frame (debugging) | | "tx" | ByteArrayLike | Raw outbound frame (debugging) |

Advert

Parses MeshCore advertisement packets.

const advert = Advert.fromBytes(bytes);
advert.parsed.name    // string | null
advert.parsed.type    // "CHAT" | "REPEATER" | "ROOM" | "SENSOR" | "NONE" | null
advert.parsed.lat     // number | null
advert.parsed.lon     // number | null
await advert.isVerified() // boolean — ed25519 signature check

Packet

Parses raw mesh packets.

const packet = Packet.fromBytes(bytes);
packet.route_type_string    // "DIRECT" | "FLOOD" | "TRANSPORT_DIRECT" | "TRANSPORT_FLOOD" | null
packet.payload_type_string  // "TXT_MSG" | "ADVERT" | "PATH" | "TRACE" | … | null
packet.payload              // Uint8Array — raw payload bytes
packet.path                 // Uint8Array — routing path

CayenneLpp

Decodes Cayenne LPP binary telemetry.

const records = CayenneLpp.decode(bytes);
// records: Array<{ channel: number, type: number, value: number | { latitude, longitude, altitude } }>

Constants

All protocol constants grouped into nested objects:

• Constants.CommandCodes.* — outbound command byte values
• Constants.ResponseCodes.* — inbound response byte values
• Constants.PushCodes.* — async push notification byte values
• Constants.Ble.* — BLE service/characteristic UUIDs
• Constants.SerialFrameTypes.* — serial frame type bytes
• Constants.StatsTypes.* — stats frame sub-types
• Constants.DataTypes.* — datagram data-type values

BufferUtils

BufferUtils.bytesToHex(bytes)       // Uint8Array → "deadbeef"
BufferUtils.hexToBytes("deadbeef")  // → Uint8Array
BufferUtils.base64ToBytes(str)      // → Uint8Array
BufferUtils.areBuffersEqual(a, b)   // → boolean

MeshCorePath

const path = MeshCorePath.fromPathAndLength(pathBytes, pathLen);
path?.toHexStrings()  // string[] — one hex string per hop

TransportKeyUtil

const key = await TransportKeyUtil.getHashtagRegionKey("#region");
// key: Uint8Array (32 bytes)

Publishing a new version

1. Bump the version in package.json.
2. Commit and push: git commit -m "chore: release vX.Y.Z".
3. Create and push a tag: git tag vX.Y.Z && git push --tags.
4. The publish.yml GitHub Action will build, test, and publish to npm automatically.

Required secret: add NPM_TOKEN to your repository's Settings → Secrets and variables → Actions.

Development

pnpm install
pnpm test          # run tests with coverage
pnpm run typecheck # type-check only
pnpm run lint      # type-check + ESLint
pnpm run build     # produce dist/

Test coverage

100% coverage is enforced on all metrics (branches, functions, lines, statements) except src/index.ts and src/connection/connection_types.ts (type-definition and re-export files).

License

MIT

Browser requirements

• Chrome or Edge desktop with Web Serial support.
• localhost or HTTPS.
• A MeshCore device running companion USB firmware.

Safari and Firefox are not supported for this Web Serial path.

Commands

pnpm install
pnpm run dev
pnpm run build
pnpm run lint

Implementation notes

• The app uses @liamcottle/meshcore.js as the first transport and protocol layer.
• Snapshot commands are issued sequentially to avoid overlapping companion protocol requests.
• Stored routed contacts are actively probed for trace responses after snapshots and topology refreshes, and can also be retraced from the dashboard.
• The current graph is based on companion-visible route state. It is not yet a full network-wide routing model.

Next steps

• Verify the data surface on real hardware.
• Extend the analytics store with repeater status, telemetry parsing, and route history.
• Decide later whether a BLE fallback or a lower-level protocol integration is needed.