LCcommand API

LCcommand API v1 — firmware v1.7.0

The LCcommand API lets third-party software read status, set filter values, select fine/step adjustment, lock local controls, inspect battery state, configure output damping and read calibration diagnostics on KipperTie LCminiND, LCcineND and LCminiFX products.

Commands are small UTF-8 JSON objects. Bluetooth, USB serial, USB network and USB MIDI carry the same supported JSON commands; only their delivery and framing differ. MIDI is a transport, not a second command language.

Print API reference

Version and compatibility

The device continues to report the integer api:1. Firmware 1.7.0, JSON API generation 1, and MIDI envelope version 01 are separate identifiers. This reference does not introduce an api:1.1 value or require existing clients to change their JSON schema.

Start each connection with api.info and api.limits. Do not infer capabilities solely from a higher firmware number: v1.7.0 is not a superset of every experimental branch. The separate v1.6.0 beta’s input_api, source, policy and ctrl.source.* features are not implemented in this v1.7.0 firmware.

Damping and the USB transports below describe v1.7.0. An older device reporting api:1 may not support them. There is no new damping-capability flag in api.info; use documented firmware compatibility and handle unknown_cmd when probing a read-only feature. Do not require a C/D prefix in fw_ver.

Firmware installation compatibility is separate from API compatibility. Use the matching LCcineND, LCminiND or LCminiFX firmware page for update eligibility. Do not use API numbers to choose an OTA package or assume an old ZIP is a supported downgrade.

Quick start

1. Choose the intended control mode on the LC. For USB, save CDC, NCM or MIDI in startup setup, then select USB mode.
2. Open that transport. Subscribe/connect the receive side before sending.
3. Send {"cmd":"api.info"}; check status, api, fw_ver and dev_type.
4. Send {"cmd":"api.limits"}, then {"cmd":"dev.status"}.
5. Where damping is needed, read ctrl.softening.get before showing its setting.
6. Send one request at a time and await its response before the next request to that LC.

Example identity response from an LCminiND:

{"status":"ok","cmd":"api.info","api":1,"fw_ver":"1.7.0","dev_type":"LCminiND"}

Physical modes and USB setup

Each power-on starts in Local. The USB type persists and defaults to CDC if no valid choice exists. Saving a USB type does not itself select USB control mode. USB charging is independent of control selection.

1. Turn the LC on with the usual button hold, then release.
2. During the three-second splash, make a second, separate short button press.
3. Turn the wheel to choose CDC, NCM or MIDI. The outline is the cursor; the dotted border marks the stored choice.
4. Press once to save. Two filled flashes acknowledge selection. A changed type restarts the LC; saving the existing type closes setup without a restart.
5. Use the normal hold-and-release control to select Local, Bluetooth or USB. The main screen says USB for all USB types.

Normal Local/Bluetooth/USB transitions do not reboot, but USB endpoints disappear/reappear as USB mode is left/entered. Re-enumerate and reconnect instead of retaining a stale port. cfg.usb.set remains reserved: there is no public command to read/set the saved USB type or remotely switch the active control source.

Fine/step mode is adjustment granularity, not connection selection. Lock suppresses local adjustment and the local short-press granularity toggle, not authorised remote commands. In Local, the first complete wheel detent acts immediately after OLED sleep; the sleeping display’s first button click remains wake-only.

Products, stops and percentages

All three report step:true. Read api.limits rather than hard-coding ranges. Example ND and FX replies:

{"status":"ok","cmd":"api.limits","nd_min":0,"nd_max":240,"pct":false,"step":true}

{"status":"ok","cmd":"api.limits","nd_min":0,"nd_max":240,"pct":true,"step":true,"pct_min":0,"pct_max":99}

nd is an integer public control code, not a DAC voltage or displayed optical-density number. For ND products:

internal_index = nd + 96
displayed_ND = (nd + 96) / 160
displayed_stops = (nd + 96) / 48

One code is 1/48 stop (0.00625 ND). Split the derived stops value into whole/fractional parts for a display; do not round to whole stops before sending. Direct API ND commands use integer codes; local step mode does not turn every remote adjustment into a stop-sized move.

For LCminiFX, present effect percentage rather than describing diffusion as measured optical ND. The API range is 0–99. For a UI using 1–100, explicitly convert api_pct = ui_percent - 1 and ui_percent = api_pct + 1; never send pct:100.

LCminiFX internal_index = 96 + floor(pct * 240 / 99)
LCminiFX reported_pct = floor(nd * 99 / 240)

Integer mapping can make the returned percentage one code lower than requested. A request of pct:50 produces nd:121 and can report pct:49. Show returned state rather than assuming exact percentage round-tripping. Send either nd or pct, not both.

JSON format, size and errors

Each request is one JSON object with a case-sensitive string cmd. Use documented JSON number/boolean/string types. Keep the complete UTF-8 request to 239 bytes or fewer: count bytes, not characters. For MIDI this includes trailing padding spaces but excludes the seven-byte LC header. Responses use a 240-byte firmware buffer including its internal string terminator; that terminator is not sent.

Ordinary v1 successes include status and cmd. Most decoded command errors include status, cmd and reason:

{"status":"ok","cmd":"ctrl.set","nd":48}

{"status":"err","cmd":"ctrl.set","reason":"range"}

Do not require cmd/reason on every failure. Mode checks precede decoding; malformed requests can have an empty command string; empty/oversized requests may return only a status:

{"status":"err","reason":"usb_mode_required"}

{"status":"err","cmd":"","reason":"bad_json"}

{"status":"err"}

Detached transports or invalid MIDI frames may produce no reply. Distinguish API errors, HTTP errors and timeouts. A transaction ID correlates replies; it is not duplicate-command suppression.

Command reference

Discovery and status

Illustrative status replies (live values vary by device):

{"status":"ok","cmd":"dev.status","nd":48,"mode":"fine","lock":false,"battery":87,"charging":true}

{"status":"ok","cmd":"dev.status","nd":120,"mode":"fine","lock":false,"battery":92,"charging":false,"pct":49}

v1.7.0 does not include the v1.6 beta’s source/policy fields.

Set and adjust filter values

Set/adjust replies contain the resulting nd, and percentage operations also return pct. limited:true appears when limiting occurs. Omit clamp for strict ND range checking, or send clamp:true; do not rely on clamp:false as a strict-mode switch in this implementation. Percentage sets are range-checked, not clamped by the ND clamp option.

Mode, lock, configuration and reboot

Names must be 1–28 UTF-8 bytes with no quotes, backslashes or control characters; simple ASCII is recommended. Reboot defaults to false. Rename/reboot can terminate the connection. Do not assume a successful control reply guarantees every operational value was synchronously stored in flash. USB type and Bluetooth name are stored configuration; damping is deliberately volatile.

Battery feedback

battery is a calculated percentage, not millivolts. Charging is a separate boolean. The OLED indicator is coarser and includes discharge smoothing, so it need not change at exactly the same instant.

Damping and feedback

ctrl.softening.set accepts 0.0–5.0 seconds in exact 0.1-second increments. Zero bypasses damping. It resets to 0.0 after reboot. Unsupported precision returns bad_value; out-of-range values return range.

{"cmd":"ctrl.softening.set","damping":2.3}

{"status":"ok","cmd":"ctrl.softening.get","damping":2.3,"target_nd":48,"applied_nd":41.625,"moving":true,"remaining_ms":1375,"powered":true,"dac_code":1842,"error":0}

Both softening commands return this state with their own cmd echoed. Ordinary status/get/set replies still report target nd, not interpolated output. The independent output task runs approximately every 5 ms; a set reply does not mean the physical transition has completed.

For an isolated change, calibrated output moves symmetrically, reaches halfway at half the duration, and completes at the end. Continuously changing targets remain damped. Fractional positions interpolate neighbouring calibration entries before DAC output. This is not a measurement of actual transmission.

Poll softening state for applied-output feedback. On LCminiFX, applied_nd remains a code coordinate, not a new measured-percentage field.

Calibration diagnostics

cal.read is read-only: it does not write, restore or recalibrate. Never use returned table values as public filter-control values.

{"cmd":"cal.read","table":"current","offset":0,"count":12}

Table defaults to current; accepted strings are current and legacy. Offset defaults to 0. Count defaults to 12, is capped at 12, and must be positive. Offsets are zero-based. Current and legacy tables have 481 and 241 entries respectively when available.

Illustrative current-table reply:

{"status":"ok","cmd":"cal.read","table":"current","available":true,"entry_count":481,"offset":0,"count":12,"more":true,"next":12,"migrated":false,"values":[3000,2998,2996,2994,2992,2990,2988,2986,2984,2982,2980,2978]}

Continue with offset equal to returned next until more:false. Final replies use next:-1. The migrated flag appears for the current table, not legacy. Unavailable legacy data still returns status ok with available false, count 0, more false, next -1 and an empty values array.

cal.status, cal.write and cal.restore remain reserved. There is no public calibration-restore API.

Bluetooth LE

Select Bluetooth mode. Pair/authenticate with the configured passkey and enable TX notifications before writing RX. Use a write with response. Each request is one complete JSON object; each notification is one complete response without a newline. A successful GATT write is not the JSON command reply.

Ensure the negotiated ATT payload accommodates the complete request and reply. The handler does not reassemble JSON split across independent RX writes. Do not invent a chunking protocol; validate notification sizes on the intended platform, especially for calibration replies.

Native iOS Bluetooth clients use Core Bluetooth. The browser example applies only where Web Bluetooth is supported, not as a promise of iOS browser support.

USB CDC

Save CDC, then select USB mode and open the serial port. Use 115200 if a library requires a baud value. Send one JSON object followed by LF; read until LF. Replies end in \n. Surrounding whitespace and a trailing semicolon are accepted; JSON plus LF is simplest.

The port disappears when USB control is left. Physical cable attachment does not authorise control in Local/Bluetooth. Separate service text strings are not JSON commands.

USB NCM / HTTP

Save NCM and select USB mode on a host supporting USB NCM networking. Open the compact control page at http://192.0.2.1/. The host is offered 192.0.2.2/24, with no default gateway or DNS. A hardware-derived .local name is advertised where host discovery supports it.

POST /api/v1/command HTTP/1.1
Host: 192.0.2.1
Content-Type: application/json
Content-Length: 18

{"cmd":"api.info"}

Send exactly Content-Type: application/json, without a charset parameter, and a bounded body with content length. Native clients can call this local endpoint. Browsers must use the same origin: an Origin header, when present, must match the request’s HTTP host. There are no permissive CORS headers for unrelated hosted websites.

Check HTTP status and JSON status. Command errors normally return JSON; malformed HTTP can return plain text. Typical results: 200 success, 400 invalid command/value, 403 mode/origin rejection, 413 oversized body, 415 content type, 501 reserved operation, 503 busy. Do not assume every failure body is JSON.

NCM is unavailable in Local/Bluetooth on v1.7.0. Multiple NCM links reuse point-to-point addresses; do not assume this URL automatically routes to the correct unit on a multi-LC host. Use separate MIDI endpoints for the hub-based multi-device control design.

USB MIDI 2.0 / UMP SysEx8

Save MIDI and select USB mode. Use MIDI 2.0 Universal MIDI Packets (UMP), message type 0x5, group 0, SysEx8 stream ID 0. This is not MIDI 1.0 SysEx7. Do not add F0/F7, 7-bit packing, Base64, compression, newline or semicolon framing.

Logical message envelope

00 7D 00 4C 43 01 2A  followed by UTF-8 bytes of {"cmd":"api.info"}

The response repeats the seven-byte envelope and transaction ID, followed by JSON. Match endpoint, fixed header and transaction ID before accepting it. The ID is correlation, not authentication or replay protection. Client examples use 1–255 then wrap to 1. Keep one outstanding request per endpoint.

Packet assembly

Each SysEx8 UMP is 128 bits: four 32-bit words. The byte count includes the stream-ID byte, leaving at most 13 LC payload bytes. Use Complete for one packet, or Start, zero or more Continue packets and End.

First UMP byte: 50 (type 5, group 0). Second: status in the high nibble, payload byte count plus 1 in the low nibble. Third: stream ID 00. The final 13 bytes contain LC data and unused zero fill. Do not append unused fill to the assembled JSON.

A receive callback can contain only part of a message or several UMPs. Iterate all UMPs; track Start/Continue/End; bound assembly to 256 bytes; validate count, sequence, group and stream, then the LC header. The JSON portion including deliberate trailing spaces is limited to 239 bytes. Invalid envelopes or oversized MIDI requests can be silently discarded rather than answered with JSON.

Required USB padding

Before packetizing, join the seven-byte header and JSON. Calculate N = ceil(total_bytes / 13). If N is divisible by four, append ASCII spaces after the closing JSON brace until one additional UMP is required: pad total length to 13 * N + 1. A 51-byte payload therefore becomes 53 bytes, not 52.

This avoids the development USB MIDI class’s exact 64-byte OUT-boundary issue without changing the JSON object. Do not use NULs, newlines or another packing scheme. Use this padding with v1.7.0.

Multiple devices and identity

A USB hub presents each LC as a separate source/destination pair. Select the destination and matching source in the same Core MIDI entity. No configurable bus address or extra JSON device-address field is required. Never silently substitute the first LC when a stored identity is ambiguous.

The USB descriptor has a hardware-derived serial; UMP discovery exposes a hardware-derived Product Instance ID. Host endpoint IDs distinguish connected devices. Verify stability through unplug/replug, hub changes and the intended iOS version before using a host ID as a permanent installation identity.

USB / MIDI identifiers

OS endpoint display names can differ. Confirm the selected device using api.info instead of matching a friendly name alone.

Native iOS / macOS integration

The intended USB MIDI controller is a native application using Apple’s Core MIDI MIDI 2.0 APIs, not a browser Web MIDI implementation. See Apple’s MIDI 2 integration overview.

1. Create a long-lived Core MIDI client, a MIDI 2.0 input port with MIDIInputPortCreateWithProtocol / kMIDIProtocol_2_0, and an output port.
2. Enumerate endpoints; show device identity in the picker. Get the selected destination’s entity and connect input to the source in that same entity before sending.
3. Add four-word UMPs to a MIDIEventList and send using MIDISendEventList. Pass numeric UMP words, not a MIDI 1.0 byte stream.
4. When connected, send api.info. Suggested timeout: two seconds; retry that read-only handshake up to three times if the initial reply is missed.
5. Read limits, status and optional damping. Use a separate single-request queue for each LC.
6. Copy incoming UMPs promptly into a bounded parser/queue; update the UI on its UI thread, not in the high-priority receive callback.
7. Handle endpoint removal/reconnect notifications, cancel stale requests and reselect ambiguous devices.

Validate the intended iOS version, USB hub and power arrangement, device count and background behaviour for your integration.

Code examples

These demonstrate actual command/wire formats, not a complete production application. Substitute the port/endpoint, maintain one request queue and add discovery, lifecycle, disconnect handling and error UI.

Python USB CDC

import json
import serial

# Substitute the actual port; macOS commonly uses /dev/cu.usbmodem...
with serial.Serial("/dev/ttyACM0", 115200, timeout=2) as port:
    port.write(b'{"cmd":"api.info"}\n')
    line = port.readline()
    if not line.endswith(b"\n"):
        raise TimeoutError("No complete LC reply")
    reply = json.loads(line.decode("utf-8"))
    if reply.get("status") != "ok":
        raise RuntimeError(reply.get("reason", "LC command failed"))
    print(reply)

Same-origin browser HTTP / NCM

// Run on the LC's own NCM page/origin, not an unrelated website.
// Await each response before starting another request.
async function sendLC(command) {
  const response = await fetch('/api/v1/command', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(command),
    cache: 'no-store'
  });
  const text = await response.text();
  let reply;
  try { reply = JSON.parse(text); }
  catch { throw new Error('Non-JSON HTTP response: ' + response.status); }
  if (!response.ok || reply.status !== 'ok') {
    throw new Error(reply.reason || ('HTTP ' + response.status));
  }
  return reply;
}
const identity = await sendLC({ cmd: 'api.info' });
const limits = await sendLC({ cmd: 'api.limits' });
const state = await sendLC({ cmd: 'dev.status' });

Browser Bluetooth where supported

// Only for a browser/environment supporting Web Bluetooth.
// LC must already be in Bluetooth mode. Native iOS uses Core Bluetooth.
const SERVICE = '4ed4587e-5172-429c-8505-8cbe9c4f231f';
const RX = '523d6915-0ac2-40f6-a423-7d5b0a413d9b';
const TX = 'ac4493cf-becf-42de-9e3b-3ea076249af7';
const enc = new TextEncoder();
const dec = new TextDecoder();
const device = await navigator.bluetooth.requestDevice({
  filters: [{ services: [SERVICE] }], optionalServices: [SERVICE]
});
const server = await device.gatt.connect();
const service = await server.getPrimaryService(SERVICE);
const rx = await service.getCharacteristic(RX);
const tx = await service.getCharacteristic(TX);
let pending = null;
tx.addEventListener('characteristicvaluechanged', event => {
  if (!pending) return;
  let reply;
  try { reply = JSON.parse(dec.decode(event.target.value)); }
  catch (error) { pending.reject(error); return; }
  pending.resolve(reply);
});
await tx.startNotifications();

async function sendBLE(command) {
  if (pending) throw new Error('An LC request is already pending');
  let timer;
  const result = new Promise((resolve, reject) => {
    pending = { resolve, reject };
    timer = setTimeout(() => reject(new Error('LC timeout')), 2000);
  });
  result.catch(() => {}); // Handle rejection while write awaits.
  try {
    await rx.writeValueWithResponse(enc.encode(JSON.stringify(command)));
    const reply = await result;
    if (reply.status !== 'ok') throw new Error(reply.reason || 'LC error');
    return reply;
  } finally {
    clearTimeout(timer);
    pending = null;
  }
}
const info = await sendBLE({ cmd: 'api.info' });
// After a timeout/write failure, reconnect before sending again;
// a late old response must not be mistaken for a new reply.

Reference MIDI packetizer

This Python reference produces numeric UMP words for the byte layout and padding; it does not open Core MIDI. Implement equivalent packetization in your native send path.

import json
import struct

# Current engineering/beta manufacturer ID, not a production allocation.
PREFIX = bytes.fromhex("00 7d 00 4c 43 01")

def lc_request_umps(command, transaction_id):
    # Client convention: use 1..255, then wrap back to 1.
    if not 1 <= transaction_id <= 255:
        raise ValueError("transaction_id must be 1..255")
    body = json.dumps(command, separators=(",", ":"),
                      ensure_ascii=False).encode("utf-8")
    frame = PREFIX + bytes([transaction_id]) + body

    # Current USB-boundary workaround: avoid 4, 8, 12, ... UMPs.
    count = (len(frame) + 12) // 13
    if count % 4 == 0:
        frame += b" " * (count * 13 + 1 - len(frame))
    if not 1 <= len(frame) - 7 <= 239:
        raise ValueError("JSON including padding exceeds 239 bytes")

    words = []
    for offset in range(0, len(frame), 13):
        chunk = frame[offset:offset + 13]
        last = offset + len(chunk) == len(frame)
        if len(frame) <= 13:
            status = 0                     # Complete
        elif offset == 0:
            status = 1                     # Start
        elif last:
            status = 3                     # End
        else:
            status = 2                     # Continue
        # MT 5, group 0; count includes stream ID; stream ID 0.
        packet = bytes([0x50, (status << 4) | (len(chunk) + 1), 0])
        packet += chunk + bytes(13 - len(chunk))
        words.append(struct.unpack(">4I", packet))
    return words

# Numeric UMP words, not bytes to write to a serial port:
umps = lc_request_umps({"cmd": "api.info"}, 0x2A)

Read a complete calibration table

async function readCalibration(sendCommand, table = 'current') {
  const values = [];
  let offset = 0;
  for (;;) {
    const reply = await sendCommand({ cmd: 'cal.read', table, offset, count: 12 });
    if (reply.status !== 'ok') throw new Error(reply.reason || 'cal.read failed');
    if (!reply.available) return [];
    values.push(...reply.values);
    if (!reply.more) return values;
    if (!Number.isInteger(reply.next) || reply.next <= offset) {
      throw new Error('Invalid calibration pagination');
    }
    offset = reply.next;
  }
}
// sendCommand sends one request and returns its parsed JSON reply.

Legacy and service commands

Legacy JSON remains available with older response shapes. Prefer v1 for new integrations. Physical transport-mode restrictions still apply.

The following recognised names return not_implemented:

preset.list, preset.save, preset.load, preset.delete
ramp.start, ramp.stop, ramp.status
cal.status, cal.write, cal.restore
event.subscribe, event.unsubscribe
cfg.passkey.set, cfg.usb.set, sys.factory_reset, ota.status

These are not promised features. There is no unsolicited event subscription, public factory reset, JSON calibration write/restore or JSON USB-type selection.

Earlier firmware differences

This reference covers v1.7.0. Keep older behaviour version-scoped; a higher-looking number does not imply that all experiments were merged.

{"cmd":"ctrl.source.get"}

{"status":"ok","cmd":"ctrl.source.get","source":"usb","policy":"override"}

{"cmd":"ctrl.source.set","source":"usb","policy":"override"}

Implementation checklist

• Discover with api.info, then read api.limits and dev.status.
• Keep public codes, optical ND, stop labels and FX percentages distinct; use returned product limits and state.
• Distinguish API generation, visible firmware, numeric updater image version and MIDI envelope version.
• Connect the receive side first. Use one in-flight request per LC.
• Coalesce slider motion: retain the newest desired target while waiting, rather than flooding every intermediate event.
• No unsolicited control events are provided. Poll dev.status at a modest rate while visible, e.g. once per second. Poll softening state for applied-output feedback. Update existing UI values rather than rebuilding/flickering the interface.
• After timeout, reconnect and reconcile by reading. Do not blindly repeat relative adjustments, toggle, rename or reboot: the first request may already have run.
• For MIDI, match endpoint/header/transaction ID and apply the padding rule. For BLE/CDC, never associate a late old reply with a new request.
• Handle range, busy, unsupported commands, API errors, HTTP errors and disconnects separately.
• Separate target from applied state during damping; neither is measured optical output.
• Follow calibration pagination; never substitute diagnostic table entries for public control values.
• Confirm persistent writes, reboot and approved service actions with the user.
• Test the real OS, phone/desktop, hub, product, reconnect behaviour and multi-device targeting before production use.

Disclaimer

This reference is supplied for integration, testing and development. Applications must validate input, discover per-device limits, implement safe retries and test intended hardware/firmware.