Kwikwai Web API

Kwikwai 1.0r754 (2014-05-30)

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”

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
    {"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.

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:
timestamp: Date and time of arrival (in millisecond) of the message
ack: ‘1’ if the message (as a whole) is acknowledged
sent: ‘true’ if the message was sent by kwikwai
blocks: 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).
bus: Always “A” in this version
timeout: Returned with value ‘1’ instead of messages in case of time out.

Below is a sample object. Following its reception, the client should call GET /ARK12 (12 being the value of next below):

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

Note: The previous method of adding the index after ARK (i.e. GET /ARK23) is deprecated and is not compatible with jsonp.

POST /SF

Change settings. Expects all or a subset 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 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 /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 a JSON object containing the following name/value pairs:

error: Any value different than 0 means an error in sending the message

POST /ACK

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 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.