DVB Adapters API

The adapter methods read and modify the adapter list of the configuration, start, stop and restart adapters, report their signal statistics and list the DVB devices of the host. Most of them are served on the POST /control/ entry point with the command name in cmd; the info and status methods are served on the path entry point. See How to call API methods for the entry points, authentication and roles. Every method on this page answers 200 with a JSON body: a failed command reports the failure inside the body, either as the value "er" under the command name or as an error field, never with an HTTP error status.

Adapter configuration

An adapter is a JSON object in the dvb_tune list of the configuration. The API stores the object as sent; the fields below are the ones the methods on this page and the adapter start-up read, every other option is passed through to the adapter when it starts. For the full option set see the adapter configuration articles: DVB Adapters Overview, DVB-S/S2, DVB-T/T2, DVB-C.

{
    "id": "a002",
    "name": "Astra 19.2E",
    "enable": true,
    "adapter": 0,
    "device": 0,
    "type": "S2",
    "tp": "11913:H:27500",
    "lnb": "9750:10600:11700"
}

id - string. Unique adapter identifier, the id of every method below. Streams address the adapter with the input dvb://a002. The methods compare the identifier as a string, so keep it a string.
name - string, optional. Shown in the status reports; the id is used when the name is absent.
enable - boolean. true starts the adapter when it is set; a disabled adapter is stored only.
adapter - number, or the string "N.M" with the adapter and device numbers. The system adapter number: /dev/dvb/adapterN. Required unless mac is set.
device - number, optional. The frontend number within the adapter: /dev/dvb/adapterN/frontendM. 0 when absent.
mac - string, optional. Replaces adapter and device: the device is looked up by its MAC address in the list returned by List DVB devices (compared in lower case). An adapter whose MAC is not found is logged and not started.
type - string. The delivery system, case-insensitive: S, S2, T, T2, C (same as C/A and C/AC), C/B, C/C, ATSC, ISDBT. Without type the device is opened without tuning the frontend; such an adapter is not registered for Get adapter status.
tp - string, optional. frequency:polarization:symbolrate, expanded into the fields frequency, polarization and symbolrate at start.
lnb - string, optional. lof1:lof2:slof, expanded into lof1, lof2 and slof.
unicable - string, optional. scr:frequency, expanded into uni_scr and uni_frequency.
no_event - boolean, optional. true disables the statistics collection of the adapter, so Get adapter status reports monitoring disabled for adapter.
satip - string, optional. A SAT>IP server address; the adapter is received from that server. Requires adapter and type.
virtual - string, optional. satip (same as satip), ci (an external CI adapter fed by a stream: requires adapter and stream) or mpts (an adapter fed by a stream address: requires address). Virtual adapters have no frontend: they push the analyzer verdict in the adapter_event message and are not registered for Get adapter status.

A running adapter reports its frontend statistics once per second to the WebSocket clients as an adapter_event message, and every start or stop of a device is pushed as adapter_status_update; see Events.

Get adapter configuration

Request: POST /control/. Control and observer.

{
    "cmd": "get-adapter",
    "id": "a002"
}

id - string, required. Adapter identifier.

Response:

{
    "get-adapter": "ok",
    "adapter": { "id": "a002", "name": "Astra 19.2E", "enable": true, "adapter": 0, "type": "S2" }
}

adapter - the stored adapter configuration object.

Unknown identifier:

{ "get-adapter": "er", "error": "adapter not found" }

Get adapter info

Request: GET /api/adapter-info or GET /api/adapter-info/{id}. Control only; an observer receives 404.

Without an identifier the reply lists every adapter:

{
    "instance": "server-1",
    "adapters": [
        { "id": "a002", "name": "Astra 19.2E", "enable": true, "adapter": 0, "type": "S2" }
    ]
}

instance - the host name of the machine, or the instance_name setting when it is defined.
adapters - array of the stored adapter configuration objects, [] when there are none.

With an identifier the reply is the stored adapter configuration object itself:

{ "id": "a002", "name": "Astra 19.2E", "enable": true, "adapter": 0, "type": "S2" }

Unknown identifier:

{ "error": "adapter not found" }

Create or update adapter

Request: POST /control/. Control only.

{
    "cmd": "set-adapter",
    "id": "a002",
    "adapter": {
        "id": "a002",
        "name": "Astra 19.2E",
        "enable": true,
        "adapter": 0,
        "type": "S2",
        "tp": "11913:H:27500",
        "lnb": "9750:10600:11700"
    }
}

id - string, optional. Identifier of the adapter to replace. When a stored adapter has this identifier it is stopped and removed from the list before the new object is inserted; when none has it, the new object is added. Without id the object is always added, even when a stored adapter carries the same adapter.id.
adapter - object, required. The adapter configuration; its own id field is the identifier the adapter is stored under. The handler does not check that adapter.id equals id: a different adapter.id renames the adapter (see below). A request without the adapter field is a Lua error in the handler and aborts the process.
gid - number, optional. Identifier generator counter of the interface: when present it is stored as gid in the configuration and echoed in the notification, so that every interface client continues the same sequence.
scan - array, optional. Stream configuration objects to add: each one is appended to the make_stream list, started unless its enable is false (a start failure, such as a missing name or empty input, is written to the log) and pushed to the WebSocket clients as {"scope": "set-stream", "stream": { ... }}. The interface sends here the channels selected after a DVB scan. The objects are stored as sent, without the table version fields that set-stream maintains.

Response:

{ "set-adapter": "ok" }

The reply is "ok" in every case, including an unknown id.

Side effects, in this order:

With id, the input list of every stream is read as address strings; a stream whose input holds an object instead of a string (see Streams API) makes the handler fail on parse_url and the process aborts, whatever the adapter. Every stream whose input list contains dvb://{id} is handled: a running one is stopped; when adapter.id differs from id the input is rewritten to dvb://{adapter.id}. The rewrite matches dvb://{id} as a Lua pattern, so an identifier with a pattern character such as - or % is not rewritten: the stream keeps the old address and is still pushed as updated. Use identifiers made of letters and digits.
With id, the running adapter with that identifier is closed, its statistics slot is freed and {"scope": "adapter_status_update", "adapter": N, "busy": false} is pushed.
With id, the stored object with that identifier is removed from dvb_tune and {"scope": "set-adapter", "adapter": {"id": "a002", "remove": true, "up": true}} is pushed; nothing is pushed when no stored adapter had the identifier.
The new object is appended to the end of the dvb_tune list, so a replaced adapter changes its position. WebSocket clients receive {"scope": "set-adapter", "gid": 466561, "adapter": { ... }} with the object as sent; gid is absent when the configuration holds none.
With enable set to true the adapter is started and {"scope": "adapter_status_update", "adapter": N, "busy": true} is pushed. An adapter is not started while the instance works as the fallback of a reachable master.
The stopped streams are started again from their stored configuration when they are enabled. A stream whose input was rewritten is pushed as {"scope": "set-stream", "stream": { ... }} with the updated object; a stream that kept its input is restarted silently.
The scan streams are added and started.
The configuration is saved.

Delete adapter

Request: POST /control/. Control only.

{
    "cmd": "set-adapter",
    "id": "a002",
    "adapter": {
        "remove": true
    }
}

id - string, required. Identifier of the adapter to delete.
adapter.remove - boolean, true. Other fields of adapter are ignored.

Response:

{ "set-adapter": "ok" }

Every stream with a dvb://a002 input is stopped, removed from the make_stream list and pushed as {"scope": "set-stream", "stream": {"id": "a001", "remove": true}}. The running adapter is closed (adapter_status_update with busy: false), the object is removed from the dvb_tune list, {"scope": "set-adapter", "adapter": {"id": "a002", "remove": true, "up": false}} is pushed and the configuration is saved. An unknown id changes nothing and is still answered "ok".

Toggle adapter

Turn an adapter on or off. Request: POST /control/. Control only.

{
    "cmd": "toggle-adapter",
    "id": "a002"
}

id - string, required. Adapter identifier.

Response:

{ "toggle-adapter": "ok" }

Unknown identifier:

{ "toggle-adapter": "er", "error": "adapter not found" }

Side effects: enable is inverted in the stored object (a missing enable becomes true). An adapter that was enabled is closed, its statistics slot is freed and adapter_status_update with busy: false is pushed; an adapter that is now enabled is started and adapter_status_update with busy: true is pushed. WebSocket clients receive {"scope": "set-adapter", "adapter": { ... }} with the updated object, without gid. The configuration is saved. Streams with an input on the adapter are not restarted.

Restart adapter

Request: POST /control/. Control only.

{
    "cmd": "restart-adapter",
    "id": "a002"
}

id - string, required. Adapter identifier.

Response:

{ "restart-stream": "ok" }

The reply key is restart-stream, not restart-adapter. Failure:

{ "restart-stream": "er", "error": "adapter not found" }

The failure reply is sent for an unknown identifier, for a disabled adapter, and while the instance works as the fallback of a reachable master. The restart reads the input list of every stream as address strings, with the same abort on an object item as set-adapter.

Every enabled stream with a dvb://a002 input is stopped, the running adapter is closed (statistics slot freed, adapter_status_update with busy: false), started again from its stored configuration (adapter_status_update with busy: true) and the streams are started again. The configuration is not changed and no set-adapter notification is sent.

Check adapter

Request: POST /control/. Control and observer.

{
    "cmd": "check-adapter",
    "id": "a002"
}

id - string, required. Adapter identifier.

Response:

{
    "check-adapter": "ok",
    "adapter": { "id": "a002", "name": "Astra 19.2E", "enable": true, "adapter": 0, "type": "S2" }
}

adapter - the stored adapter configuration object. The reply carries no runtime status; use Get adapter status or the adapter_event messages for that.

Unknown identifier:

{ "check-adapter": "er", "error": "adapter not found" }

Get adapter status

Signal statistics of a running adapter from the monitoring module. Request: GET /api/adapter-status/{id} with an optional query ?t={time}. Control only; an observer receives 404.

id - string, required in the path. Adapter identifier; the adapter must be running with a frontend (an adapter with a type, not a virtual one).
t - number, optional query parameter. 1 (default) returns the statistics of the last completed monitoring interval, 0 the latest one-second sample. Any other number is answered {"error": "not implemented"}; a value that is not a number counts as 1.

The monitoring interval is the tsdb_interval setting, 60 seconds when not defined.

Response:

{
    "instance": "server-1",
    "name": "Astra 19.2E",
    "timestamp": 1758240000,
    "lock": true,
    "signal": 78,
    "signal_db": -4520,
    "snr": 62,
    "snr_db": 1380,
    "ber": 0,
    "unc": 0,
    "bitrate": 41000
}

instance - the instance_name setting; absent when the setting is not defined.
name - the adapter name, or its id when the name is not set.
timestamp - Unix time. For t=1 the end of the reported interval, 0 before the first interval has completed; for t=0 the current time.
lock - true if the frontend reported lock in the last sample of the span.
signal - signal level as reported by the driver: percent with the DVB API v5 status, raw driver units with the dvbapi3 option. Average over the interval for t=1, the latest sample for t=0.
signal_db - signal level in dB multiplied by 100, the last sample of the span. 0 with the dvbapi3 option.
snr - signal to noise ratio in the same units as signal, averaged for t=1.
snr_db - signal to noise ratio in dB multiplied by 100, the last sample of the span. 0 with the dvbapi3 option.
ber - bit errors as reported by the driver, summed over the interval for t=1.
unc - uncorrected blocks as reported by the driver, summed over the interval for t=1.
bitrate - Kbit/s received from the device, averaged over the interval for t=1, the latest second for t=0.

Error replies, all with status 200:

{"error": "adapter id not defined"} - no identifier in the path.
{"id": "a002", "error": "adapter not found"} - the adapter is not running: unknown identifier, disabled adapter, an adapter without type, or a virtual adapter.
{"id": "a002", "error": "monitoring disabled for adapter"} - the adapter has no_event set.
{"error": "not implemented"} - t is a number other than 0 and 1.

List DVB devices

The DVB devices found under /dev/dvb on the host. Request: POST /control/. Control only.

{
    "cmd": "dvbls",
    "reset": true
}

reset - boolean, optional. true probes the devices again. Without it the list built at start-up is returned; the list is also built on the first call when the process started without a /dev/dvb directory.

Response: a JSON array, one entry per frontend.

[
    {
        "adapter": 0,
        "device": 0,
        "busy": true,
        "type": "S",
        "frontend": "Montage DS3103/TS2022",
        "mac": "00:17:42:00:00:00"
    },
    {
        "adapter": 1,
        "device": 0,
        "error": "failed to open [Permission denied]"
    }
]

adapter - number, the system adapter number (/dev/dvb/adapterN).
device - number, the frontend number (/dev/dvb/adapterN/frontendM).
busy - boolean, true while an adapter configuration of this instance uses the adapter number, or the frontend was already open when it was probed. Absent when the frontend could not be opened at all. The flag follows the adapter_status_update messages until the list is rebuilt with reset.
type - string, the frontend class: S, C, T or ATSC. Absent when error is present.
frontend - string, the frontend name reported by the driver. Absent when error is present.
mac - string, the MAC address of the adapter when the driver exposes one; absent otherwise. Usable as the mac field of the adapter configuration.
error - string, present instead of type and frontend when the probe failed: failed to open [<reason>], failed to get frontend type or unknown frontend type [N].

Without DVB devices the reply is [].