MeterMate SDK

Official SDK for communicating with the MeterMate WiFi P1 dongle over TCP.

Overview

metermate-sdk provides a clean, high-level JavaScript API for provisioning and communicating with the MeterMate WiFi P1 dongle.

It abstracts:

• TCP socket communication
• JSON protocol encoding/decoding
• Transport differences (React Native vs Mock)
• Command number mapping
• Basic connection lifecycle

The SDK exposes a single public class:

import { DongleClient } from "metermatesdk";

Architecture

High-Level Design

The SDK consists of:

• DongleClient (public API facade)
• Transport layer (pluggable runtime-specific IO)
• Protocol helpers (JSON encoding/decoding)
• Command constants (numeric mapping)

Application
     │
     ▼
DongleClient (public API)
     │
     ▼
Transport (react-native | mock | node*)
     │
     ▼
TCP Socket
     │
     ▼
MeterMate Dongle (JSON protocol)

Public API Layer

DongleClient:

• Owns host and port (default: 10.0.0.1:9999)
• Delegates IO to a selected transport
• Exposes high-level provisioning methods

Transport Layer

Supported modes:

• "react-native" — real TCP via react-native-tcp-socket
• "mock" — simulated dongle for tests
• "node" — reserved for future Node TCP support

Transports implement:

connect(host, port)
sendCommand(commandId, params)
close()

Protocol

The dongle protocol is JSON-based.

Each request is sent as:

{
  "msgType": <commandId>,
  ...params
}

Responses are expected to be JSON objects.

Installation

React Native

npm install metermatesdk react-native-tcp-socket react-native-wifi-reborn

You must use a dev-client or bare workflow. Expo Go does NOT support raw TCP sockets.

Node (Mock Testing Only)

npm install metermatesdk

Usage

React Native Example

import { DongleClient } from "metermatesdk";

const client = await DongleClient.create("react-native");

await client.connect();

const wifiList = await client.getWifiList();

await client.selectWifiNetwork("MySSID", "password123");

const internetOk = await client.checkInternet();

console.log("Internet OK?", internetOk);

client.close();

Mock Mode Example (Testing)

import { DongleClient } from "metermatesdk";

const client = await DongleClient.create("mock");

await client.connect();

const wifiList = await client.getWifiList();
console.log(wifiList.APList);

await client.selectWifiNetwork("TestSSID", "TestPw");

const ok = await client.checkInternet();
console.log(ok);

client.close();

API Reference

DongleClient.create(mode, host?, port?)

Creates a client using the selected transport.

| Mode | Description | |------|-------------| | "react-native" | Real TCP transport | | "mock" | Simulated transport | | "node" | Reserved for future Node TCP transport |

Optional:

• host (default 10.0.0.1)
• port (default 9999)

client.connect()

Establishes a TCP connection to the dongle.

Must be called before sending commands.

Throws if connection fails.

client.getWifiList()

Scans for available WiFi networks.

Returns

{
  APList: [
    {
      ssid: string,
      rssi: number,
      security: number
    }
  ]
}

client.selectWifiNetwork(ssid, password, isHidden?, securityType?)

Sends WiFi credentials to the dongle.

Parameters:

• ssid: string
• password: string
• isHidden: boolean (default false)
• securityType: number (default 3)

Returns

{
  ok?: boolean,
  selected?: string
}

client.checkInternet()

Checks whether the dongle successfully connected to the provided WiFi network.

Returns

boolean

Internally interprets dongle field:

{ "RESULT_HOMEAP": 1 }

client.reboot()

Reboots the dongle.

Returns

{
  ok: boolean,
  rebooting: boolean
}

client.close()

Closes the underlying transport connection.

Should be called when provisioning flow is complete.

Command Mapping

The SDK maps high-level methods to numeric command IDs:

| Method | Command ID | |--------|------------| | getWifiList() | 3 | | selectWifiNetwork() | 1 | | checkInternet() | 2 | | reboot() | 7 |

Lifecycle Best Practices

Typical provisioning flow:

sequenceDiagram
    participant App
    participant Phone
    participant Dongle

    Note over Phone: User connects phone to<br/>Dongle WiFi network

    App->>Dongle: DongleClient.create("react-native")
    App->>Dongle: connect()

    App->>Dongle: getWifiList()
    Dongle-->>App: { APList: [...] }

    App->>Dongle: selectWifiNetwork(ssid, password)
    Dongle-->>App: { ok: true }

    App->>Dongle: checkInternet()
    Dongle-->>App: { RESULT_HOMEAP: 1 }

    App->>Dongle: reboot()
    Dongle-->>App: { rebooting: true }

    App->>Dongle: close()

Always call close() after finishing.

Error Handling

The SDK throws when:

• TCP connection fails
• Socket errors occur
• JSON response cannot be parsed
• Transport not connected

You should wrap provisioning flows in try/catch.

Example:

try {
  await client.connect();
  await client.selectWifiNetwork(ssid, password);
} catch (err) {
  console.error("Provisioning failed:", err);
}

Limitations

• Assumes strict request → single response pattern
• No multiplexing
• No built-in retry logic
• No internal timeout management
• "node" transport may not yet be implemented

Extending the SDK

To add a new dongle command:

1. Add command ID in core/commands.js
2. Add a wrapper method in DongleClient
3. Call transport.sendCommand(commandId, params)

To add a new transport:

1. Implement connect, sendCommand, close
2. Register it in DongleClient.create()

License

Commercial © Jemac Sweden AB