energy-device-simulator

Tool v0.4.0 TypeScript MIT

Local protocol simulator for IAMMETER, Shelly, and Fronius test flows, with a compact browser console and deterministic runtime data for gateway and dashboard validation.

View on GitHub Docs →
energy-device-simulator

Project overview

energy-device-simulator is the test-bench companion for the rest of the stack. It exists for the moments when you need repeatable protocol behavior, but you do not want to depend on a real meter or inverter being online, correctly configured, and physically available.

Instead of pretending to be a huge lab environment, the simulator stays focused on the behaviors that matter most during integration work:

  • serving realistic local protocol responses
  • switching between supported source-device profiles quickly
  • exposing a small browser console for control
  • keeping output deterministic enough for validation and troubleshooting

That makes it useful for development, demos, regression checks, and first-pass integration work.

Why it matters

Real energy hardware is valuable, but it is also inconvenient during routine software work. A simulator helps when you want to:

  • test parser changes without touching a live install
  • reproduce a gateway or dashboard workflow locally
  • compare behavior between device families quickly
  • validate browser UI logic before field deployment
  • keep development moving even when the real meter is offline or unavailable

Real simulator screenshots

energy-device-simulator desktop console

The desktop console keeps the simulator intentionally compact: select the active device profile, review the live payload shape, and confirm what an edge bridge or gateway should see.

energy-device-simulator mobile console

The mobile view shows that the local console remains usable even when the simulator is being checked from a phone or a narrow viewport during setup and testing.

Supported simulated device families

The project is currently aimed at the device families used by the broader EnergyMeterHub tooling:

  • IAMMETER WEM3080T
  • Shelly Pro 3EM
  • Fronius SunSpec

The benefit is not just protocol coverage. It is the ability to switch those profiles quickly while keeping the rest of the test workflow stable.

Where it fits best

energy-device-simulator is especially helpful when you are:

  • building or testing energy-device-edge
  • validating energy-device-gateway
  • checking how a dashboard handles different sources
  • preparing demos without relying on customer hardware
  • writing deterministic tests around protocol translation logic

Local runtime requirements

The simulator is designed for ordinary development machines. You do not need dedicated lab hardware to get value from it.

A normal setup is:

  • Node.js on a workstation, laptop, or small server
  • one browser for the local console
  • optional companion tools such as energy-device-edge or energy-device-gateway pointed at the simulator instead of real hardware

Basic startup path

npm install
npm run typecheck
npm test
npm start

The default mode uses a non-privileged IAMMETER-oriented config on port 1502, which makes first-run testing easier on normal machines.

Alternate startup modes

Useful built-in variants include:

  • npm run start:iammeter
  • npm run start:shelly
  • npm run start:fronius

This makes it easy to switch the simulated source without rebuilding the surrounding test setup from scratch.

Browser console access

After startup, open the local console and confirm which source profile is active before connecting any companion service. That small habit saves time when you are comparing parsing or UI behavior across multiple device families.

Practical first workflow

A good first test session usually looks like this:

  1. Start the simulator in one profile.
  2. Open the browser console and check the active source.
  3. Point the gateway, edge bridge, or dashboard at the simulator host and port.
  4. Verify the received values.
  5. Switch the simulator profile and repeat.

No physical wiring required

energy-device-simulator is a software-only lab tool. There is no mains-side wiring step because the project simulates already-networked devices and protocol responses.

A practical local test stack usually looks like this:

  1. Run the simulator on a workstation or small server.
  2. Keep the browser console open for visibility.
  3. Point energy-device-edge, energy-device-gateway, or another local consumer at the simulator host and port.
  4. Validate the received data and behavior before moving to real hardware.

What to validate before leaving the simulator stage

  • the client can reach the simulator at the expected host and port
  • the selected device profile matches the test you think you are running
  • payload shape and units are accepted by the downstream service
  • UI states and upload logic behave correctly when the profile changes

When to move on to real hardware

The simulator is most useful at the beginning and middle of the workflow. Once the local logic looks right, the next step should be validation against the real source device so network quirks, firmware behavior, and live operating conditions are also covered.

Device profiles and ports

The simulator provides a small number of realistic device profiles rather than a huge menu of loosely maintained templates. That is a strength for testing because it keeps the runtime behavior easier to understand.

Examples include:

  • IAMMETER-style Modbus TCP flows
  • Shelly local RPC output
  • Fronius SunSpec-oriented behavior

What the console is for

The browser console is intentionally small. It is there to help you:

  • confirm the selected device family
  • inspect the current output shape
  • switch test context quickly
  • pair the simulator with another local service without guesswork

What the simulator is not trying to be

This project is not a replacement for field testing with real hardware. Instead, it gives you a controlled first stage where:

  • protocol changes can be tested repeatedly
  • UI work can move forward without customer equipment
  • gateway and edge logic can be validated before moving into a live install

Deterministic testing value

One of the biggest advantages here is repeatability. When a dashboard, gateway, or parser behaves differently after a change, the simulator gives you a stable local reference point that is much easier to reason about than a live system with changing loads and conditions.

← Back to our projects