1. Home
  2. Utility API sandbox
  3. IEC 61968-9 HES simulator

Solution

IEC 61968-9 HES simulator for MDM and field integrations

Last updated

This free IEC 61968-9-style HES simulator plays the head-end in a meter exchange. A meter installed through the sandbox billing APIs appears as an EndDevice, moves from Registered to Communicating, and produces daily register reads and device events. Read them in JSON or XML with cursor paging, and switch on failures such as a meter that never communicates.

What it's for

Commissioning is the step that turns an installed meter into one that bills. The meter has to reach the head-end system (HES) and start sending reads. This simulator lets you test the MDM or field-app side of that step before a real HES is available. It shares state with the billing surfaces of the utility API sandbox, so a meter swapped through billing shows up here.

India's CEA interoperability guidelines name an IEC 61968-based interface between the HES and the MDM. The names on this simulator (EndDevice, UsagePoint, MeterReadings, EndDeviceEvents, ReadingType) follow that vocabulary. The payloads are simplified JSON and XML, not the full IEC message envelope.

Get started

Create a workspace, then authenticate with an API key (x-api-key: sandbox-api-key) or an OAuth 2.0 bearer token from /oauth/token in your workspace:

curl -X POST https://sandbox.piebench.com/workspaces
curl -H "x-api-key: sandbox-api-key" "https://sandbox.piebench.com/ws_…/hes/api/v1/EndDevices"

The list starts empty. Meters appear once they're registered, which happens when an exchange is completed through the SAP-style or Oracle-style billing API.

Endpoints

EndpointDoes
GET /EndDevicesRegistered meters with status and usage point
GET /EndDevices/{mRID}One meter
POST /EndDevicesRegister an installed meter: {"mRID": "NEW0001", "UsagePoint": {"mRID": "SP0001"}}
GET /MeterReadingsRegister reads, optionally for one meter (?mRID=) between startTime and endTime (ISO 8601)
GET /EndDeviceEventsDevice events, optionally for one meter

The commissioning lifecycle

StatusMeans
UnknownInstalled in billing but never registered on the head-end
RegisteredKnown to the head-end, not yet communicating
CommunicatingSending reads. A meter starts communicating 15 simulated minutes after registration
DecommissionedRemoved in a later exchange

Once communicating, a meter produces one cumulative kWh register read per simulated day, starting from its installation reading. Events follow the lifecycle: DEVICE_REGISTERED, COMMUNICATION_ESTABLISHED, COMMUNICATION_LOST (while the hes_offline switch is on) and DEVICE_REMOVED.

Use POST /_control/clock on your workspace to fast-forward simulated time and generate a month of reads in one call.

JSON or XML

Send Accept: application/xml to get MeterReadings and EndDeviceEvents as XML. The next cursor then comes in the x-next-cursor response header. In JSON, it's the next_cursor field.

curl -H "x-api-key: sandbox-api-key" -H "Accept: application/xml" "https://sandbox.piebench.com/ws_…/hes/api/v1/MeterReadings?mRID=NEW0001"

Paging

Paging is cursor-based. Pass the next_cursor value back as ?cursor= until it's null. limit defaults to 20 meters or 100 reads and events, with a maximum of 50 and 500. A malformed cursor returns INVALID_CURSOR.

Failure cases

  • Billing never tells the head-end. With desync_same_day on, an exchange completes in billing but the new meter stays Unknown here. Your integration has to notice and register it with POST /EndDevices. SAP describes this failure, a same-day removal and installation not passed to the meter data system, in support note 2520360.
  • A meter that never communicates. With hes_offline on, registered meters stay Registered, produce no reads and raise COMMUNICATION_LOST.
  • Transport failures. rate_limit, server_error, slow and duplicate_ids apply here as on the billing surfaces.

What it doesn't do

It doesn't speak DLMS/COSEM or any meter protocol, run validation, estimation and editing (VEE), or send the full IEC 61968-100 message envelope. Open-source tools already cover the meter-protocol layer. This simulator covers the back-office side. For how a field app connects to a real HES or MDM, see HES and MDM integration.

Built to integrate with your systems

HES, MDM, SAP IS-U, Oracle CC&B and billing systems, over REST, OAuth or a direct SQL connection. How integrations work

Questions buyers ask

Is this a full IEC 61968-9 implementation?

No. It uses IEC 61968-9 names (EndDevice, UsagePoint, MeterReadings, EndDeviceEvents, ReadingType) with simplified JSON and XML payloads. It doesn't produce the full IEC 61968-100 message envelope or validate against the official XSDs.

How do meters get onto the HES simulator?

Complete an exchange through the SAP-style or Oracle-style billing API. The new meter is registered automatically, unless the desync_same_day switch is on. You can also register an installed meter yourself with POST /EndDevices.

How do I get a month of meter reads quickly?

Fast-forward simulated time with POST /_control/clock on your workspace, for example {"advance_hours": 720}. Each communicating meter then has one register read per simulated day.

Can I simulate a non-communicating meter?

Yes. Switch on hes_offline with PUT /_control/faults. Registered meters stop moving to Communicating, produce no reads and report COMMUNICATION_LOST.

Does it support DLMS/COSEM?

No. It simulates the head-end's back-office API, not the meter protocol. Use a DLMS simulator for meter-to-head-end testing.

Sources

Free trial · no card

See it with your own crew

Start a free trial, or ask us for a walkthrough of your rollout.

Related