BMCLI remote-bmapi

Reference version: BMCLI 1.6.3. Command names, parameters and machine-readable fields retain their source spelling.

Expose physical CAN, CAN FD, and LIN channels through the deployed GWR remote BMAPI UDP protocol. An upper computer uses the normal public BMAPI calls BM_EnumerateRemote, BM_OpenEx, BM_Read, and BM_Write; it does not need a BMCLI-specific client or protocol adapter.

BMCLI owns the GWR-compatible UDP listeners and wire parser directly. It does not reverse BM_OpenRemote into a server API. Control records are translated to BM_Control on the daemon’s existing physical handles; generic-I/O records are translated between UDP and BM_Write/RxBroker. This keeps the ordinary BMAPI remote-client path independent from gateway-server routing.

The initial implementation has one configured consumer IPv4 address and uses UDP control port 3502 plus generic-I/O port 2502. The protocol has no authentication, authorization, encryption, or replay protection. Run it only on an isolated or otherwise trusted engineering network with host firewall rules restricted to the intended client.

remote-bmapi start

# Export two cross-connected CAN FD channels to a Linux upper computer
bmcli remote-bmapi start \
  --channel=10356/0,10357/0 \
  --target=192.168.65.129 \
  --advertise=192.168.65.1 \
  --nbitrate=500 --dbitrate=2000 --termination=120

# Export a LIN master/slave pair
bmcli remote-bmapi start \
  --channel=10356/6,10357/4 \
  --target=192.168.65.129 \
  --bitrate=19200 --mode=slave --power=off

Option	Default	Description
`--channel`	existing daemon channels	Physical channels to export; required when the command creates a daemon
`--target`	required	IPv4 address of the intended remote BMAPI consumer
`--advertise`	route-selected local IPv4	Gateway address shown in remote channel names
`--name`	`BMCLI Remote BMAPI`	Remote server display name
daemon bus options	capability defaults	Applied only when `remote-bmapi start` creates the daemon; query runtime Help for the exact current list

When no daemon is running, remote-bmapi start creates one, opens the requested channels, and owns that daemon. A later remote-bmapi stop then also stops it. If a daemon already exists, every channel already open in it is exported and an optional --channel list must match that complete set. The pre-existing daemon remains running after remote-bmapi stop.

Only physical channels may be exported. Remote and virtual channels are rejected to avoid forwarding loops. Export order is deterministic: first-opened physical device order, then ascending physical port within each device. Remote clients use the returned remote channel information rather than assuming a particular numeric index.

Gateway startup does not claim a channel. While no explicit claim exists, local and legacy remote protected controls retain their historical last-writer-wins behavior. RxBroker fans each received frame independently to the gateway, local message recv, host logging, signal decoding, and Web streams. Ordinary local and remote message send is also shared.

For deterministic control, local automation uses channel claim; a new remote BMAPI client uses BM_QueryRemoteSession and BM_ClaimRemoteSession. The remote session lazily owns a channel on its first protected write. A conflicting configuration, close, TX Task, route, LIN schedule/response, replay, ISO-TP, or UDS operation returns busy, while send and passive monitoring remain available. Remote BM_Close completes the deployed ordered neutralization sequence and returns that one channel without releasing the other channels in the session.

remote-bmapi status

bmcli remote-bmapi status --format=json

Returns the state, configured target and advertised addresses, exported channel count, cumulative local_to_remote, remote_to_local, dropped, errors, and generation_recoveries counters, plus session_claimed, owner metadata, claimed channel count, lease expiry, and configuration generation. These counters cover the current Gateway run and reset to zero when Gateway starts.

generation_recoveries increments only after stale asynchronous-TX identities exhaust the usable identity pool and BMCLI successfully crosses a trusted physical channel generation boundary: close/reopen, notification and RxBroker attachment, then Gateway cursor rebind into the new generation. It does not count ordinary frames or retries and is not proof that a message was delivered. A nonzero value means that recovery occurred; repeated growth should be investigated for missing TX completion/TEF events, bus faults, or device/USB instability.

remote-bmapi stop

bmcli remote-bmapi stop --format=json

Stops forwarding, closes UDP listeners 3502/2502, and releases the gateway’s RxBroker cursors. It also stops the daemon only when that daemon was auto-created by the matching remote-bmapi start. Stopping an inactive service returns an error without cancelling CAN send or replay. For a running service, cleanup drains channels owned by its remote session; stopping an auto-created daemon drains all its work before closing.

Remote BMAPI client sequence

BM_Init()
BM_EnumerateRemote(gateway_ipv4, channel_info_array, ...)
BM_QueryRemoteSession(gateway_ipv4, ...)          # recommended capability check
BM_ClaimRemoteSession(&session, gateway_ipv4, ...) # new clients; starts heartbeat
BM_OpenEx(... remote channel info ...)
BM_GetNotification() / BM_WaitForNotifications()
BM_Read() and BM_Write()
BM_Close()
BM_ReleaseRemoteSession(session)
BM_UnInit()

Opening a remote channel applies the client’s requested CAN or LIN mode, bitrate, termination/pull-up, and power settings to the corresponding physical channel. The gateway translates remote logical channel numbers to physical ports in both control requests and data headers.

In CAN NoACK mode the firmware does not provide a transmit-completion event to BMAPI. The Gateway therefore treats a successful BM_Write(..., 0) only as accepted, sends physical SEQ 0, and does not allocate, cancel, consume, or synthesize a completion-map entry. Switching from normal mode to NoACK is busy until the preceding normal-mode completion map is empty (or a new physical Broker generation has retired it). Raw remote CAN send remains available for sustained accepted-only traffic; UDS suppressed-positive-response and daemon isotp send, which require a real transmit completion, fail before transmit.

Old BMAPI clients that never claim remain compatible in unlocked mode. A new client connecting to an old GWR receives unsupported/timeout from the session query and must explicitly decide whether unlocked fallback is acceptable. A failed claim never silently falls back. The public declarations, structures, enums, error mappings, wire opcode, and compatibility rules are normative in bmcli_multi_endpoint_control_design.md, section Public BMAPI additions.

Source of truth: BMCLI 1.6.3 repository documentation. Run bmcli help <category> <action> --format=json for the exact contract of the installed version.