Web API

Created On15.05.2018

bywpincyma

Kwikwai 2.0r899 (2020-04-04)

The web API is used by kwikwai’s web interface and supports most of its features.

Kwikwai answers to standard HTTP/1.0 queries on port 80 (https is not supported). All calls return JSON data. POST (along with CSRF protection) is used for any requests having side effects.

Note

Kwikwai’s Web Interface (for K1-10x models) mainly uses this API; it may however use URLs or objects which are not documented below. Anything not documented is private and may change or disappear between firmware revisions of kwikwai.
JSONP is supported. Append parameter “callback” to any get request (f.e. GET /ARI?callback=<function_to_call>).

GET /ARI

Returns a JSON object representing kwikwai’s current configuration, containing the following name/value pairs:

version

firmware version of kwikwai, for example “1.0r345”

name

Name assigned to kwikwai, for example “KWIKWAI”

sntp

time server ip address or name, for example “time.windows.com”

timezone_offset

offset in seconds between UTC and local time, for example “-32400” (for Alaska)

utc_time

time in UTC (in milliseconds) as known to kwikwai, for example “1262951839000”

random

random value, used to secure POST requests

MAC

MAC address (serial number) of kwikwai, for example “00:50:C2:AD:80:00”

ip

current IP address, for example “192.168.1.23”. If use_fixed_ip is true, then this has the same value than fixed_ip below.

mask

current mask, for example “255.255.255.0”. If use_fixed_ip is true, then this has the same value than fixed_mask below.

gateway

IP address of the current default gateway, for example “192.168.1.1”. If use_fixed_ip is true, then this has the same value than fixed_gateway below.

dns

IP address of the current DNS server, for example “192.168.1.1”. If use_fixed_ip is true, then this has the same value than fixed_dns below.

use_fixed_ip

“false” if using DHCP, “true” if using the fixed ip parameters below

fixed_ip

fixed IP address to use (if use_fixed_ip is true), for example “192.168.1.23”

fixed_mask

fixed mask to use (if use_fixed_ip is true), for example “255.255.255.0”

fixed_gateway

IP address of the gateway to use (if use_fixed_ip is true), for example “192.168.1.1”

fixed_dns

IP address of the DNS server to use (if use_fixed_ip is true), for example “192.168.1.1”

controller_uses_serial

“false” if using serial port for CLI, “true” if using it using the parameters below

baudrate

baudrate of the serial port (when used in react serial mode)

serial_config

bitmap defining the serial port configuration (when used in react serial mode). Only 96 (=8N1), 104 (=8N2) and 102 (=8E1) are supported today.

serial_mintimtrm

Min interval between transmissions in milliseconds. Max 9999.

controller_rules

Array of objects (max 6) containing the following name/value pairs:

bus

“A” or “_” to disable the command

condition

One of the following values:

+5V raising
+5V falling
HPD raising (Hot Plug Detect)
HPD falling
CEC filter

cec_filter

String containing the pseudo regexp to filter messages triggering the command. Hex string separated by ‘:’. The first byte may have ? to indicate any source/dest. The string may be terminated by “:*” to match any message length.

output

Output port to use for the command. One of the following values:

CEC
Serial

delay

Delay in 1/10th of a second before sending the command.

command

The command string (in hex) to send in case of a match. Spaces in the string are allowed and ignored.

signals

Object containing the following name/value pairs:

5V

Value of 5V signal.

HPD

Value of the HPD signal.

GET /ARD

Returns a JSON object describing the devices discovered on the CEC bus, containing the following name/value pairs:

bus: Always “A” in kwikwai model k1-100
devices: Array of 15 objects (0x00 to 0x0E), each containing either ‘null’ or an object containing the following name/value pairs:
osd_name: If known, the name of the device. Kwikwai used to automatically query device names but this is disabled in recent builds so this field is always empty.
will_ack: If true, kwikwai acks this logical address.

In other terms, the command returns something like:

{
 "bus":"A",
 "devices":
  [
    {},                             <- the TV at 0x00 has no name but exists
    null,                           <- no 0x01 device found
    {"will_ack":"true"},                 <- kwikwai acks 0x02
    null,
    { "osd_name":"DVDP"},           <- a player at 0x04 named "DVDP"
    ...
  ]
}

GET /ART

Reads the connected device E-EDID and returns the raw data, or an error. Kwikwai shall be connected between a source and a sink for this to succeed. For bus “A” (the only one) in kwikwai k1-100.

The returned object contains the following name/value pairs:

error: “timeout error”; This name/value pair is only present in case of error.
ddc: [0,255,255,255,255,255,255,0, …; JSON array of 256 JSON numbers. This name/value pair is only returned in case of success.
bus: always “A” in this version

GET /ARK

Returns CEC messages exchanged on the CEC bus. Uses long polling and only returns when messages are available (or times out).

Parameters:

index: Index of the last received message (or 0), f.e. GET /ARK?index=23.

Returns

Returned name/value pairs:

next: Index to use for next call to GET /ARK
messages: Returns an array of message object, each containing the following name/value pairs:
type: Type of the message; 1 for CEC messages or 4 for signals (HPD/5V)
timestamp: Date and time of arrival (in millisecond) of the message/event
ack: ‘1’ if the message (as a whole) is acknowledged. To be ignored for signals.
sent: ‘true’ if the message was sent by kwikwai. To be ignored for signals.
blocks: For CEC messages, array of message blocks as JSON number. Each block is 2 bytes, in order to encode the full 10 bits of the CEC blocks (see HDMI spec). For signals, the first block is 1 for 5V and 2 for HDP. The second block provides the pin value.
matches: Array of indexes matching react filters
bus: Always “A” in this version
timeout: Returned with value ‘1’ instead of messages in case of time out.

Below is a sample object.

{
 "messages":
 [
  {
    "timestamp":1281801681920,
    "ack":0,
    "blocks":[65344, 29248, 192],
    "bus":"A"
   }
  ],
 "next":12
}

POST /SF

Change general settings. Expects all of the following parameters (encoded as application/x-www-form-urlencoded in the POST message body):

random: must be equal to the random value returned by the last call to #GET /ARI and provided in all cases
name: Name
sntp: time server name or IP address
timezone: offset in seconds from UTC
fixed: ‘true’ to used fixed IP address settings below (that must be provided) or ‘false’ to use DHCP
ip: fixed IP address
mask: fixed mask
gateway: fixed default gateway IP address
dns: fixed DNS name server IP address
password-current: current password
password-new: new password
password-new-repeat: new password repeated

Returns

Returns a JSON object containing the following name/value pairs:

error: Any value different than 0 means an error in changing the settings
reconfig: Set to 1 if the saving the settings caused a reconfiguration of the IP stack, which may result in kwikwai changing its IP address.

POST /AF

Change controller settings. Expects all of the following parameters (encoded as application/x-www-form-urlencoded in the POST message body):

random

must be equal to the random value returned by the last call to #GET /ARI and provided in all cases

controller_uses_serial

‘true’ to send commands via serial, ‘false’ to use the serial port for the CLI.

baudrate

serial baudrate to use to send serial commands.

serialconfig

serial bits and parity configuration. One of 96 (=8N1), 104 (=8N2) or 102 (=8E1).

smtt

Min interval between transmissions in milliseconds. Smaller or equal to 9999 ms.

bus<x>

’_‘to disable or ’A’ in this version. <x> is 0 to 5 in this and the following fields.

condition<x>

One of the following values:

+5V raising
+5V falling
HPD raising (Hot Plug Detect)
HPD falling
CEC filter

cf<x>

output<x>

Output to use for the command. One of the following values:

CEC
Serial

delay<x>

Delay before sending the command, in 1/10th of a second. Smaller or equal to 99.

cmd<x>

The command string (in hex) to send. For serial commands, spaces in the string are allowed and ignored. CEC commands are formatted as usual (with a seperating ‘:’).

logical_address_list_bus

“A” for model k1-100

logical_address_list

A string of hex bytes separated by ‘,’ (comma), for example ‘1,2,B’. Kwikwai will ack these devices ID on the bus logical_address_list_bus.

Returns

Returns a JSON object containing the following name/value pairs:

error: Any value different than 0 means an error in changing the settings

POST /CEC

Sends a CEC message. Expects 3 parameters (encoded as application/x-www-form-urlencoded in the POST message body):

bus: “A” for model k1-100
random: Must be equal to the random value returned by the last call to #GET /ARI
message: A string of hex bytes separated by ‘:’, for example ‘0F:36’

Returns

Returns a JSON object containing the following name/value pairs:

error: Any value different than 0 means an error in sending the message. 8 indicates collision. 7 indicates timeout. In both cases, the sender should try re-sending the message.

POST /TEST

Sends the command linked to a controller rule, over CEC or serial. Expects 2 parameters (encoded as application/x-www-form-urlencoded in the POST message body):

random: Must be equal to the random value returned by the last call to #GET /ARI
index: A number between 0 and 5 corresponding to the rule to test.

Returns

Returns a JSON object containing the following name/value pairs:

error: Any value different than 0 means an error in sending the message. 66 is returned if the rule refers to a serial command but the serial port is not assigned to the controller (see controller\_uses\_serial field in POST /AF above)

POST /ACK

This command is deprecated. Please use #POST /AF.

Changes the list of Logical Addresses being acknowledged by kwikwai. Expects 3 parameters (encoded as application/x-www-form-urlencoded in the POST message body):

bus: “A” for model k1-100
random: Must be equal to the random value returned by the last call to #GET /ARI
logical_address_list: A string of hex bytes separated by ‘,’ (comma), for example ‘1,2,B’

Returns

Returns a JSON object containing the following name/value pairs:

error: Any value different than 0 means an error in changing the list
devices: Same content as returned by #GET /ARD.

Web API

Kwikwai Web API

Kwikwai 2.0r899 (2020-04-04)

GET /ARI

GET /ARD

GET /ART

GET /ARK

Returns

POST /SF

Returns

POST /AF

Returns

POST /CEC

Returns

POST /TEST

Returns

POST /ACK

Returns