Kwikwai Command Line Interface (CLI)

Kwikwai 1.0r529 (2011–12–21)

The Command Line Interface is a text based protocol that can be used over TCP/IP, serial and/or USB. It supports most of the features of kwikwai and is designed to be easy to implement in Home Automation or other embedded controllers.

Notes

The USB port and the serial port of kwikwai k1–100 are one and the same. You can use both ports at the same time, but you should be prepared to get on both ports the answers to commands sent by either port.
To use the USB port, a driver available on the FTDI website is required.
Multiple individual connections are possible via TCP/IP.
Some commands are only available via TCP/IP (for example, exit).
Most logging messages are only sent on the serial/USB port.

Protocol basics

Connection

To connect via serial or USB, use 38400 bauds, no parity, 8 data bits, a stop bit (a.k.a 38400 8-N–1) and no flow control. Note that for interactive session, you may want to activate local echo. Also note that kwikwai accepts any combination of Carriage Return (CR, ASCII 0x0D) and Line Feed (LF, ASCII 0x0A) on input but answers with a single CR.

To connect via TCP/IP, open a connection to kwikwai’s IP address on port 9090. To try commands, you can use the telnet client of most operating systems.

Commands & replies

Client sends commands in the form:

  command <param1> <param2> ... <CR>

On success, kwikwai answers with:

  OK command <answer1> <answer2> ... <CR>

On failure, kwikwai answers with:

  ERR command <error_id> <string> <CR>

where <string> is some text describing the error (this text can contains spaces).

For example, the command to send some message on the bus is cec:send. It expects 2 parameters, the bus to send the command to and the message:

  cec:send A FF:36
  OK cec:send A FF:36

If there is an error in the message, for example targeting an inexistent bus:

  cec:send B FF:36
  ERR cec:send 4 Bus ID must be A in this version

Asynchronous messages

Kwikwai may also send two sorts of asynchronous messages:

for logging messages (on serial/usb, as controlled by the verbose:set command)
```
  ! <string>
```
As an example, the message provided to remember entering the password once connected through telnet :
```
  ! Password required
```

for events (as controlled by the cec:listen:set command)

  * command <data1> <data2>

A typical CEC message

  * cec:message A 00:02:09.380 4F:82:10:00#

Notes

For the client, examining the first char of the received message is enough to determine its type. Many implementations may safely discard anything starting with “!”.
Replies repeat the command, which enables the sender to “forget” its requests and only manage kwikwai’s answers. In other terms, kwikwai answers “done that” to the “do that” request, not just “done”.

Available commands

System level commands

`password <password>`

Authorize the telnet connection. If a password is required (i.e. the password is not empty in the settings), this must be the first command exchanged upon connection, otherwise kwikwai drops the connection.

        password kwikwai
        OK password

`version:get`

Returns kwikwai’s firmware version.

        version:get
        OK version:get 1.0r304

`mac:get`

Returns kwikwai’s MAC address.

        mac:get
        OK mac:get 00:50:C2:AD:80:00

`reboot:upgrade`

Reboots the device in the firmware upgrade mode. The telnet session is disconnected and the device waits for a firmware file to be uploaded through XMODEM or the web interface.

        reboot:upgrade
        OK reboot:upgrade

`exit`

TCP/IP only: terminates the TCP/IP connection.

        exit
        OK exit
        Connection closed by foreign host.
        unix$

Settings commands

`name:get`

Returns kwikwai’s network name.

        name:get
        OK name:get KWIKWAI

`name:set <name>`

Sets the network name. Max 15 alphanumerical characters.

        name:set myprecious
        OK name:set myprecious

`verbose:get`

Returns the verbosity level of the logging function. Debug messages are only sent over serial/USB.

        verbose:get
        OK verbose:get 0

`verbose:set <0|1|2|3|4>`

Sets the verbosity level of the logging function. 4 is the maximum level. Debug messages are only sent over serial/USB.

        verbose:set 4
        OK verbose:set 4

`ipsettings:get`

Returns the network settings: “DHCP” or “STATIC”, the ip address, mask, gateway and dns (the ip address, mask gateway and dns information are only relevant for static configurations).

        ipsettings:get
        OK ipsettings:get DHCP 192.168.10.200 255.255.255.0 192.168.10.1 192.168.10.1

`ipsettings:set <"DHCP"|"STATIC"> <ip> <mask> <gwy> <dns>`

Sets the network settings: “DHCP” or “STATIC”, the ip address, mask, gateway and dns. When done over telnet, the connection may be disconnected if kwiwai must be reconfigured.

        ipsettings:set STATIC 192.168.1.100 255.255.255.0 192.168.1.1 192.168.1.1
        OK ipsettings:set STATIC 192.168.1.100 255.255.255.0 192.168.1.1 192.168.1.1

`ipconfig:get`

Returns the currently allocated ip address, mask, gateway and dns.

        ipconfig:get
        OK ipconfig:get 192.168.1.61 255.255.255.0 192.168.1.1 192.168.1.1

`time:local:get`

Returns the local time

        time:local:get
        OK time:local:get 15:06:50

`time:local:set <HH:MM:SS>`

Sets the local time. If enabled, this time configuration is overwritten by the SNTP synchronization.

        time:local:set 12:34:56
        OK time:local:set 12:34:56

`time:offset:get`

Returns the offset (in seconds) between utc and local time.

        time:offset:get
        OK time:offset:get 0

`time:offset:set <offset_in_seconds>`

Configures the offset (in seconds) between utc and local time.

        time:offset:set 3600
        OK time:offset:set 3600

`time:sntp:get`

Returns the name or ip address of the Simple Network Time Protocol (SNTP) server kwikwai contacts regularly to get accurate time. If the string is empty, the feature is disabled.

        time:sntp:get
        OK time:sntp:get time.windows.com

`time:sntp:set <server_name>`

Sets the Simple Network Time Protocol (SNTP) server name. The synchronization is done regularly. Use an empty string to disable the synchronization. Name length is limited to 47, forbidden characters are controls, space and “\ / : * ? " ; | .”.

        time:sntp:set time.apple.com
        OK time:sntp:set time.apple.com

`cec:ack:get <bus_id>`

Returns the list of Destination Logical Addresses whose frames are acknowledged by kwikwai. Logical addresses are separated by commas and in hex.

        cec:ack:get A
        OK cec:ack:get A 5,7,8

`cec:ack:set <bus_id> <logical_address_list>`

Defines the list of Destination Logical Addresses whose frames are acknowledged by kwikwai.This enables kwikwai to emulate a CEC device (for example to add CEC to an HDMI device lacking the feature, like a PC video card). Logical addresses to acknowledge shall be in hex separated by commas. An empty lists clears all adresses (i.e. send cec:ack:set A.)

        cec:ack:set A 2,3,B
        OK cec:ack:set A 2,3,B

`cec:listen:get`

Returns the state of the listening feature for CEC messages.

        cec:listen:get
        OK cec:listen:get 0

`cec:listen:set <0|1|>`

Enables or disables the listening feature for CEC messages. Use 1 to enable, 0 to disable, and nothing to toggle.

        cec:listen:set 1
        OK cec:listen:set

The listening feature results in CEC frames being sent asynchronously to the client as follows

        * cec:message <bus_id> <HH:MM:SS:MS> <frame>

where is the bus, is the local time including milliseconds, and frame is a sequence of bytes separated by “:”, generally followed by “#” to indicate the frame was acknowledged. For example:

        * cec:message A 00:02:09.380 4F:82:10:00#

`cec:send [<bus_id>] <cec_string>`

Sends the CEC frame cec_string on bus bus_id. Currently only bus “A” is supported (“A”). The frame shall be formatted as byte:byte:byte:…

        cec:send A FF:36
        OK cec:send A FF:36

`ddc:read[<bus_id>] [<page_no>]`

Reads the DDC information from the sink connected to bus bus_id (“A” for kwikwai k1–100). page_no is the ddc page number (which can be useful for a rare device having multiple pages - most don’t.) The results are returned asynchronously by 128-bytes blocks.

        ddc:read
        OK ddc:read A 0
        ...
        * OK ddc:read A 0 0x00 00:ff:ff:ff:ff:ff:ff:00:...
        * OK ddc:read A 0 0x80 00:b3:00:95:00:01:01:02:...

Error codes

Not authentified
Unknown command
Too many arguments (8 max.)
Bad argument
DDC time out

Kwikwai Command Line Interface (CLI)

Certified Executive Chefs

Kwikwai 1.0r529 (2011–12–21)

Notes

Protocol basics

Connection

Commands & replies

Asynchronous messages

Notes

Available commands

System level commands

password <password>

version:get

mac:get

reboot:upgrade

exit

Settings commands

name:get

name:set <name>

verbose:get

verbose:set <0|1|2|3|4>

ipsettings:get

ipsettings:set <"DHCP"|"STATIC"> <ip> <mask> <gwy> <dns>

ipconfig:get

time:local:get

time:local:set <HH:MM:SS>

time:offset:get

time:offset:set <offset_in_seconds>

time:sntp:get

time:sntp:set <server_name>

HDMI related commands

cec:ack:get <bus_id>

cec:ack:set <bus_id> <logical_address_list>

cec:listen:get

cec:listen:set <0|1|>

cec:send [<bus_id>] <cec_string>

ddc:read[<bus_id>] [<page_no>]

Error codes

`password <password>`

`version:get`

`mac:get`

`reboot:upgrade`

`exit`

`name:get`

`name:set <name>`

`verbose:get`

`verbose:set <0|1|2|3|4>`

`ipsettings:get`

`ipsettings:set <"DHCP"|"STATIC"> <ip> <mask> <gwy> <dns>`

`ipconfig:get`

`time:local:get`

`time:local:set <HH:MM:SS>`

`time:offset:get`

`time:offset:set <offset_in_seconds>`

`time:sntp:get`

`time:sntp:set <server_name>`

`cec:ack:get <bus_id>`

`cec:ack:set <bus_id> <logical_address_list>`

`cec:listen:get`

`cec:listen:set <0|1|>`

`cec:send [<bus_id>] <cec_string>`

`ddc:read[<bus_id>] [<page_no>]`