canonical: https://jentic.com/apis/mbus.local/mbus

# M-Bus HTTPD API

M-Bus HTTPD is a small HTTP server that exposes the wired M-Bus (Meter-Bus) protocol used to read utility meters such as gas, water, heat, and electricity. The seven endpoints let an agent control the M-Bus HAT power, scan a serial bus for connected meter addresses, and read single or multi-frame data records from a specific meter at a chosen baud rate. It targets industrial and building-automation deployments where utility consumption data needs to be polled programmatically rather than read off a physical display.

## For AI agents

Read utility meter data over M-Bus through an HTTP wrapper - power the HAT, scan for meters, and pull single or multi-frame meter readings.

## Scope

Does not handle billing, customer management, or wireless meter protocols - use for wired M-Bus meter scanning and frame reading only.

## Capabilities

- Power the M-Bus HAT on or off via HTTP
- Scan a serial bus to discover connected meter addresses
- Read a single data record from a specific meter at a chosen baud rate
- Read multiple frames from a meter for richer historical data
- Surface the M-Bus HTTPD service status for health checks
- Query the bus at any supported baud rate without manual configuration

## Use cases

### Scheduled Utility Meter Polling

Poll connected gas, water, heat, or electricity meters at a regular interval and write the readings to a time-series database for billing, analytics, or fault detection. The `/mbus/get` endpoint returns a single frame for a known meter address, which agents can run on a cron-like schedule. This replaces manual meter readings in district heating networks and multi-tenant buildings.

Example prompt: Every hour, call GET `/mbus/get/{device}/{baudrate}/{address}` for each meter in the configured list and write the parsed value plus timestamp to InfluxDB.

### Bus Discovery for New Installations

Discover what meters are physically connected to the M-Bus before configuring polling jobs. The `/mbus/scan` endpoint walks the bus at a chosen baud rate and returns the addresses of responding devices. Installation engineers and commissioning agents use this once at deployment to capture the device inventory without manually checking each meter.

Example prompt: Call GET `/mbus/scan/{device}/2400` and return the list of discovered meter addresses, then write each one to a meters table for later polling.

### Multi-Frame Historical Reads

Pull multiple frames from a meter that supports historical records, enabling agents to retrieve consumption history rather than just the latest value. The `/mbus/getMulti` endpoint accepts a maxframes parameter, returning as many records as the meter exposes. This supports retrospective billing reconciliation and gap-filling after a polling outage.

Example prompt: Call GET `/mbus/getMulti/{device}/{baudrate}/{address}/24` to retrieve up to 24 historical frames and store each with its frame index in the readings table.

### AI Agent for Building Energy Reporting

Build an agent that aggregates M-Bus readings across all meters in a building and produces a weekly energy report flagging anomalies. The agent searches Jentic for 'read M-Bus meter', loads the meter-read schema, and executes calls in parallel for each known meter address. The output is a summary highlighting unusual consumption patterns without an engineer manually pulling each meter.

Example prompt: For every meter address in the configured inventory, call GET `/mbus/get` and aggregate readings for the past 7 days, then return a markdown report flagging meters whose consumption is more than 20% above their 4-week average.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/mbus/api` | Service status and version |
| GET | `/mbus/hat` | Get HAT power state |
| GET | `/mbus/hat/on` | Power the HAT on |
| GET | `/mbus/hat/off` | Power the HAT off |
| GET | `/mbus/scan/{device}/{baudrate}` | Scan the bus for meters |
| GET | `/mbus/get/{device}/{baudrate}/{address}` | Single-frame meter read |
| GET | `/mbus/getMulti/{device}/{baudrate}/{address}/{maxframes}` | Multi-frame meter read |

## Key resources

- **API Status** — Health check for the M-Bus HTTPD service
- **HAT** — Power control for the physical M-Bus HAT
- **Scan** — Discovery of connected meter addresses
- **Get** — Single-frame meter reads
- **GetMulti** — Multi-frame meter reads for historical data

## Why Jentic

- **Setup:** Wiring the M-Bus HTTPD API by hand means reaching a local service that has no auth of its own and mapping its scan and frame-read operations yourself. Through Jentic you install once, import the M-Bus HTTPD API from the API Directory, configure the connection once, and your agent calls it without exposing the local service to the public internet.
- **Permission scoping:** M-Bus HTTPD takes device, baud rate, and address as path segments per request rather than as a stored resource you own, so you limit the agent to the operations it needs, such as scanning the bus or reading a meter frame. It calls only the operations you allow, so hat power controls are not included unless you add them.
- **Credential handling:** M-Bus HTTPD has no credentials of its own, so your own Jentic One instance mediates access and reaches the local service only through signed execution calls. No secret enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'read an M-Bus meter', and Jentic returns the matching M-Bus HTTPD operation with its input schema so the agent calls the right endpoint without reading the protocol documentation.

## Related APIs

- **TomTom** — Geospatial data for tagging meter readings with location context
- **Abstract APIs** — Email and IP utilities for sending consumption reports and validating recipients
- **GraphHopper** — Routing engine for dispatching field engineers to meter sites

## FAQ

### What authentication does the M-Bus HTTPD API use?

The M-Bus HTTPD spec defines no authentication scheme; the service is intended to run on a trusted local network behind whatever firewalling the deployment provides. When exposed through Jentic, agents reach the service via Jentic's connection layer rather than over the open internet.

### Can I discover connected meters with the M-Bus HTTPD API?

Yes. GET `/mbus/scan/{device}/{baudrate}` walks the bus and returns the addresses of responding meters. Run this once at commissioning and persist the inventory; subsequent polling uses GET `/mbus/get` against the discovered addresses.

### What are the rate limits for the M-Bus HTTPD API?

There are no published rate limits - the service is bound by serial-port bandwidth at the chosen baud rate (typically 300, 2400, or 9600). Practical limits are one read per meter per second; bus contention is the real constraint, not the HTTP layer.

### How do I read a meter with the M-Bus HTTPD API through Jentic?

Search Jentic for 'read an M-Bus meter', load the schema for GET `/mbus/get/{device}/{baudrate}/{address}`, and execute with the device path (e.g. `/dev/ttyAMA0`), baud rate, and meter address. Jentic routes the call to the local M-Bus HTTPD service.

### Does the M-Bus HTTPD API support multi-frame reads?

Yes. GET `/mbus/getMulti/{device}/{baudrate}/{address}/{maxframes}` returns up to maxframes historical records from a meter that supports them. Use this to back-fill readings after a polling outage or to capture richer consumption history at commissioning.

### Why do I need to power the HAT before reading?

The M-Bus HAT supplies the bus voltage that connected meters draw to communicate. GET `/mbus/hat/on` energises the bus before reads; GET `/mbus/hat/off` de-energises it. Agents typically power the HAT once at boot and only toggle it during fault recovery.

### Can I limit what my agent is allowed to do with the M-Bus HTTPD API?

Yes. Because you self-host Jentic One, your own rules decide which M-Bus HTTPD operations and connection details the agent may use, and it calls only the operations you allow. You can restrict it to read-only work such as scanning the bus with GET `/mbus/scan` and pulling single or multi-frame reads with GET `/mbus/get` and GET `/mbus/getMulti`, while withholding the HAT power controls (GET `/mbus/hat/on` and `/mbus/hat/off`) unless you explicitly add them. Since the device path, baud rate, and meter address are passed per request rather than stored, you keep the agent scoped to exactly the meters and operations it needs.