convert — API

This page is for developers. For a plain-English explanation, see the introduction.

convert is one method registered with openremap.api — a plain command (one cohesive operation). Everything the CLI can do, the API can do too.

Input schema

{
    "path":   {"type": "str", "required": True,  "description": "Path to the input file."},
    "format": {"type": "str", "default": "auto", "description": "auto | ihex | srec | bin."},
}

Defaults and validation live in the schema, in the registry — not in the CLI or any client. Every consumer reads the same contract via list_methods.

Calling it in-process (Python)

import openremap.api as api

result = api.call("convert", {"path": "boot.hex"})
# result is a plain JSON-serialisable dict

print(result["format"])        # "ihex"
print(result["format_name"])   # "Intel HEX"
print(result["size"])          # 4194304

One difference from the CLI --json summary: the full API result also carries the converted bytes as base64 text under data_b64 — that is what the CLI decodes when it writes the .bin file:

import base64

flat = base64.b64decode(result["data_b64"])
open("boot.bin", "wb").write(flat)

Force the interpretation the same way the CLI does:

raw_result = api.call("convert", {"path": "weird.bin", "format": "bin"})

Calling it over JSON-RPC

The same call over the stdio server — usable from any language:

echo '{"id": 1, "method": "convert", "params": {"path": "boot.hex"}}' \
  | python -m openremap.api.transport.stdio

Response (one JSON object per line — data_b64 holds the flat bytes):

{"id": 1, "result": {"format": "ihex", "format_name": "Intel HEX", "size": 4194304, "data_b64": "AAECAwQFBg==", "segments": 1, "warnings": []}}

Errors come back as JSON-RPC error objects — clients branch on code:

{"id": 1, "error": {"code": -32602, "message": "convert: missing required param 'path'"}}

An empty file, an invalid --format value, or an image that fails to decode raises a guard error (-32000) — a clean client-facing rejection, never a traceback.

Error handling

Code	Meaning	Example message
`-32602`	Invalid params (schema validation)	`convert: missing required param 'path'`
`-32601`	Method not registered	`Unknown method: 'convertx'`
`-32000`	Guard rejection (business rule, not a bug)	`Binary file 'boot.hex' is empty.` · `--format must be one of: auto, ihex, srec, bin.`
`-32603`	Unexpected internal failure	—

Discovery — `list_methods`

import openremap.api as api

catalogue = api.call("list_methods", {})
meta = next(m for m in catalogue["methods"] if m["name"] == "convert")
print(meta["kind"])   # "command"
print(meta["input_schema"])

Quick smoke test

echo '{"id": 1, "method": "ping", "params": {}}' | python -m openremap.api.transport.stdio
# → {"id": 1, "result": {"ok": true}}