FreeMASTER Lite JSON-RPC API

Interacts with a running FreeMASTER Lite instance over its WebSocket JSON-RPC interface. Covers the full state sequence from WebSocket session setup through target communication and variable access.

When to use

• Connecting to a running FreeMASTER Lite service over WebSocket.
• Calling JSON-RPC methods: GetAppVersion, StartComm, StopComm, IsCommPortOpen, ReadELF, ReadTSA, DefineVariable, GetVariableInfo, ReadVariable, WriteVariable, Exit.
• Distinguishing service reachability from target communication state.
• Interpreting JSON-RPC errors and building a basic call sequence.

Do not use this skill to create .fmcfg files (freemaster-lite-configuration-file), launch or stop the process (freemaster-lite-start-server / freemaster-lite-stop-server), or build browser PCM clients (freemaster-lite-web-application).

State Model

Keep these three states distinct:

1. Process running — fmlite.exe has been launched.
2. Service reachable — WebSocket session opened to the service.
3. Target communication active — StartComm succeeded and IsCommPortOpen returns true.

A reachable service does not mean the embedded target is connected.

Quick start

1. open a WebSocket session                          -- connect to the service
2. call GetAppVersion {}                             -- confirm service alive
3. call StartComm {}                                 -- open target comm port
4. call IsCommPortOpen {}                            -- must return true
5. call ReadELF {}                                   -- load symbols (or ReadTSA)
6. call DefineVariable {"variable": {...}}           -- if not in .fmcfg
7. call GetVariableInfo {"name": "x"}                -- verify addr resolved
8. call ReadVariable {"name": "x"}                   -- read value
9. call WriteVariable {"name": "x", "value": 10.0}
10. call StopComm {}                                 -- release comm port

Session Setup

Open a WebSocket session to the service.
Input: host (default: "localhost"), port (default: 8090)
Output: { "session_id": "ws-session-id" }

Safe to reconnect or switch to a different instance.

Method Reference

All operations call a JSON-RPC method:

Input: method (string), params (dict or {})
Output: full JSON-RPC response; "result" on success, "error" on failure

Method	params	result
GetAppVersion	{}	version string
StartComm	{}	true
StopComm	{}	true
IsCommPortOpen	{}	true / false
ReadELF	{}	true
ReadTSA	{}	true
DefineVariable	{"variable": {...}}	true
GetVariableInfo	{"name": "<name>"}	variable descriptor
ReadVariable	{"name": "<name>"}	current value
WriteVariable	{"name": "<name>", "value": <number>}	true
Exit	{}	true (terminates process)

DefineVariable — variable object fields

Field	Type	Required	Description
name	string	yes	Variable name
addr	number | string	yes	Address or ELF symbol name
type	string	yes	int, uint, float, double, fract, ufract
size	number	yes	1, 2, 4, or 8
shift	number	no	Right-shift for integer types
mask	number	no	AND mask after shifting
q_n	number	fract/ufract	Fractional bits
q_m	number	fract/ufract	Integer bits

After DefineVariable, call GetVariableInfo to confirm the definition resolved to a numeric address (not just a symbol name) before reading or writing.

Error Handling

On failure, the response contains error instead of result:

{ "jsonrpc": "2.0", "id": 3,
  "error": { "code": -32602, "message": "Variable not found: g_unknown" } }

Always check for error before using result.

Guardrails

Scope

• This skill calls the FreeMASTER Lite JSON-RPC API only. It does not modify .fmcfg files or embedded firmware.

Destructive actions

• WriteVariable modifies live target memory. Confirm the variable name and value with the user before writing, especially for safety-critical variables.
• Exit terminates the FreeMASTER Lite process. Use freemaster-lite-stop-server for process lifecycle management.

Secrets

• No credentials involved in JSON-RPC calls.

Refuse-and-escalate

• If IsCommPortOpen returns false after StartComm, stop and diagnose the connection settings before attempting variable access.
• If GetVariableInfo shows no numeric address after DefineVariable, do not attempt ReadVariable or WriteVariable — the symbol was not resolved.

Validation loop

1. GetAppVersion must return a non-empty version string after the session opens.
2. IsCommPortOpen must return true before any variable operation.
3. After DefineVariable, GetVariableInfo must show a numeric addr field.
4. ReadVariable result must be a number, not an error object.
5. After WriteVariable, read back the value with ReadVariable to confirm the write was accepted.

Out of scope

• .fmcfg file creation — use freemaster-lite-configuration-file.
• Process launch or shutdown — use freemaster-lite-start-server / freemaster-lite-stop-server.
• Browser-side PCM client — use freemaster-lite-web-application.

See Also

• freemaster-lite-start-server — launch the service before connecting
• freemaster-lite-stop-server — terminate the process via Exit
• freemaster-lite-web-application — browser-side PCM API for the same operations