K8090 Protocol Manual

K8090/VM8090 Protocol Manual

Technical Guide

K8090/VM8090 PROTOCOL MANUAL

Table of contents

Introduction..........................................................................................................................................2

Packet Composition.........................................................................................................................2

Checksum.........................................................................................................................................2

Communication....................................................................................................................................3

Serial IO...........................................................................................................................................3

Basic commands...................................................................................................................................4

Switch relay ON (11h).....................................................................................................................4

Switch relay OFF (12h)...................................................................................................................4

Toggle relay (14h)............................................................................................................................5

Set button mode (21h)......................................................................................................................6

Start relay timer (41h)......................................................................................................................7

Set relay timer delay (42h)...............................................................................................................7

Query commands..................................................................................................................................8

Query relay status (18h)...................................................................................................................8

Query timer delay (44h)...................................................................................................................9

Query button mode (22h)...............................................................................................................10

Event commands.................................................................................................................................11

Button status (50h).........................................................................................................................11

Relay status (51h)..........................................................................................................................11

System commands..............................................................................................................................12

Reset factory defaults (66h)...........................................................................................................12

Jumper status (70h)........................................................................................................................12

Firmware version (71h).................................................................................................................13

Command List....................................................................................................................................14

Notes...................................................................................................................................................15

Velleman Projects Page 1 August 20, 2010

K8090/VM8090 PROTOCOL MANUAL

Introduction

This is a detailed guide of the K8090 protocol. This guide also applies to the VM8090 which is the

pre-built version of the K8090.

Packet Composition

Packets for the K8090 are 7 bytes in size. Each packet is delimited by the STX (04h) and ETX

(0Fh) bytes. Validity of the packet can be checked by verifying the checksum byte (CHK).

8 bits

STX (04h)

CMD

MASK

PARAM1

PARAM2

CHK

ETX (0Fh)

1. K8090 Packet Diagram

The function of each packet is decided by the command byte (CMD), for a list of possible values

refer to the chapter 'Command List'.

Each packet has a mask byte (MASK), and two parameter bytes (PARAM1 and PARAM2), however

their meaning differs for each command. The mask byte is usually a bit field indicating which relays

or buttons should be affected by a command, while the two parameter bytes are simply command

parameters.

Checksum

The K8090 uses the two's complement for its checksum. This means adding all bytes up to and

including param2, negating the result and adding 1.

-(STX + CMD + MASK + PARAM1 + PARAM2) + 1

Velleman Projects Page 2 August 20, 2010

K8090/VM8090 PROTOCOL MANUAL

Communication

Serial IO

The K8090 board is an USB CDC device that communicates over a virtual serial port (COM), using

the Windows built-in driver 'usbser.sys'.

The following serial communication settings should be used when connecting to the K8090:

Baud rate 19200

Data bits 8

Parity None

Stop bits 1

Flow control None

2. Serial Communication Settings

Packets may be sent to the board to request information and the board may respond with one or

more packets to transfer this information back to the client.

The board is event-driven, meaning that any change in the board's state is sent directly to the client

through status packets. Clients should be prepared to handle this information in an appropriate

manner. See the 'Event commands' chapter for more details. Polling is not necessary, although it

may be required to retrieve the initial state of the board once.

Velleman Projects Page 3 August 20, 2010

K8090/VM8090 PROTOCOL MANUAL

Basic commands

Switch relay ON (11h)

Switch on one or more relays. Relay one and eight correspond with the least and most significant bit

of the mask parameter. Settings these bits will mark the corresponding relay(s) to be switched on.

Parameters:

cmd 11h

mask bit 0-7: Relay 1..8

param1 Ignored

param2 Ignored

This command may trigger a 'Relay status (51h)' event command if the state of one or more relays

changes.

Switch relay OFF (12h)

Switch off one or more relays. Relay one and eight correspond with the least and most significant

bit of the mask parameter. Settings these bits will mark the corresponding relay(s) to be switched

off. If a timer is active on a relay that is switched off, that timer is also disabled.

Parameters:

cmd 12h

mask bit 0-7: Relay 1..8

param1 Ignored

param2 Ignored

This command may trigger a 'Relay status (51h)' event command if the state of one or more relays

changes.

Velleman Projects Page 4 August 20, 2010

K8090/VM8090 PROTOCOL MANUAL

Toggle relay (14h)

Toggle one or more relays. Relay one and eight correspond with the least and most significant bit of

the mask parameter. Settings these bits will mark the corresponding relay(s) to be toggled. If a timer

is active on a relay that is switched off, that timer is also disabled.

Parameters:

cmd 14h

mask bit 0-7: Relay 1..8

param1 Ignored

param2 Ignored

This command may trigger a 'Relay status (51h)' event command if the state of one or more relays

changes.

Velleman Projects Page 5 August 20, 2010

K8090/VM8090 PROTOCOL MANUAL

Set button mode (21h)

Configure the mode of each of the buttons. Available modes are momentary, toggle and timed. The

following table describes the actions taken for each different mode when a button is pressed. Note

that this behavior can be turned off by setting the 'Event' jumper.

Momentary The relay stays on as long as the button remains pressed.

Toggle Toggles the corresponding relay.

Timed The relay is switched on and the timer for the relay is started. If the

timer is already running, the timer is aborted and the relay is switched

off.

Parameters:

cmd 21h

mask Enable momentary mode

bit 0-7: Relay 1..8

param1 Enable toggle mode

bit 0-7: Relay 1..8

param2 Enable timed mode

bit 0-7: Relay 1..8

In case of duplicate assignments, momentary mode has priority over toggle mode, and toggle mode

has priority over timed mode.

Mode settings are saved to EEPROM memory and thus remembered when the board loses power.

Velleman Projects Page 6 August 20, 2010

K8090/VM8090 PROTOCOL MANUAL

Start relay timer (41h)

Start a timer for the selected relay(s). The relay(s) are switched on and their timer is started. The

relays will stay in the on state until the timer for the corresponding relay expires or until the user

actively switches the relay off. If a timer was already running for a relay, that timer is restarted.

Parameters:

cmd 41h

mask bit 0-7: Relay 1..8

param1 High-byte of the timer delay (optional)

param2 Low-byte of the timer delay (optional)

If param1 and param2 are not zero, their value is used as a temporary timer delay, otherwise the

default timer delay is used. The default timer delay can be set using the 'Set relay timer delay (42h)'

command.

Timer delay is a 16-bit integer, indicating the delay time in seconds, for which param1 is the high-

byte and param2 is the low-byte value.

This command may trigger a 'Relay status (51h)' event command if the state of one or more relays

changes.

Set relay timer delay (42h)

Set a timer delay for one or more relays. Timer length is a 16-bit integer, indicating the delay time

in seconds, for which param1 is the high-byte and param2 is the low-byte value. The timer can be

activated with the 'Start relay timer (41h)' command. When the timer expires, the relay will be

switched off.

Parameters:

cmd 42h

mask bit 0-7: Relay 1..8

param1 High-byte of the timer delay

param2 Low-byte of the timer delay

Maximum timer delay is 18 hours (65535 seconds).

Timer delay values are saved to EEPROM memory and thus remembered when the board loses

power.

Velleman Projects Page 7 August 20, 2010

K8090/VM8090 PROTOCOL MANUAL

Query commands

Query relay status (18h)

Query the current status of all relays (on/off) and their timers (active/inactive).

Request parameters:

cmd 18h

mask Ignored

param1 Ignored

param2 Ignored

The board will respond with a 'Relay status (51h)' packet.

Velleman Projects Page 8 August 20, 2010

K8090/VM8090 PROTOCOL MANUAL

Query timer delay (44h)

Query the current timer delay for one or more relays. The device will respond with one or more

packets depending on how many relays have been queried.

Request parameters:

cmd 44h

mask bit 0-7: Relay 1..8

param1 bit 0: Retrieve total delay time

bit 1: Retrieve remaining delay time

bit 2-7: Ignored

param2 Ignored

Response parameters:

cmd 44h

mask bit 0-7: Relay 1..8

param1 High-byte of the timer delay

param2 Low-byte of the timer delay

The timer delay field in the response is a 16-bit integer, indicating the requested delay time in

seconds, for which param1 is the high-byte and param2 is the low-byte value.

Velleman Projects Page 9 August 20, 2010

K8090/VM8090 PROTOCOL MANUAL

Query button mode (22h)

Query the current mode of each button. Possible modes are momentary, toggle and timed. The mode

for each button can be set using the 'Set button mode (21h)' command.

Request parameters:

cmd 22h

mask Ignored

param1 Ignored

param2 Ignored

Response parameters:

cmd 22h

mask Button is in momentary mode

bit 0-7: Relay 1..8

param1 Button is in toggle mode

bit 0-7: Relay 1..8

param2 Button is in timed mode

bit 0-7: Relay 1..8

Velleman Projects Page 10 August 20, 2010

K8090/VM8090 PROTOCOL MANUAL

Event commands

Button status (50h)

This event is sent when a button is pressed or released. Intercept this command to create an event-

driven application that monitors the status of the buttons.

Parameters:

cmd 50h

mask bit 0-7: State of button 1..8. If the bit is set, the

corresponding button is pressed.

param1 bit 0-7: Button 1..8 has been pressed

param2 bit 0-7: Button 1..8 has been released

Relay status (51h)

This event is sent every time the status of one or more relays changes. Intercept this command to

create an event-driven application that monitors the status of the relays. The relay status can also be

queried manually by sending the 'Query relay status (18h)' command; both commands return the

same response.

Parameters:

cmd 51h

mask bit 0-7: Previous state of each relay

param1 bit 0-7: Current state of each relay

param2 bit 0-7: State of the relay timers (active/inactive)

By comparing the previous and current state, it can be determined which relays have just been

turned on or off.

Formulas:

Switched ON = (mask XOR param1) AND param1

Switched OFF = (mask XOR param1) AND mask

Velleman Projects Page 11 August 20, 2010

K8090/VM8090 PROTOCOL MANUAL

System commands

Reset factory defaults (66h)

Reset the board to factory defaults.

Parameters:

cmd 66h

mask Ignored

param1 Ignored

param2 Ignored

All buttons are set to toggle mode and all timer delays are set to 5 seconds.

Jumper status (70h)

Checks the position of the 'Event' jumper. If the jumper is set, the buttons no longer interact with the

relays but button events are still sent to the computer.

Request parameters:

cmd 70h

mask Ignored

param1 Ignored

param2 Ignored

Response parameters:

cmd 70h

mask Reserved

param1 >1: The jumper is set

param2 Reserved

Velleman Projects Page 12 August 20, 2010

K8090/VM8090 PROTOCOL MANUAL

Firmware version (71h)

Queries the firmware version of the board. The version number consists of the year and week

combination of the date the firmware was compiled.

Request parameters:

cmd 71h

mask Ignored

param1 Ignored

param2 Ignored

Response parameters:

cmd 71h

mask Reserved

param1 Year (10 = 2010)

param2 Week (1 = first week of Year)

Velleman Projects Page 13 August 20, 2010

K8090/VM8090 PROTOCOL MANUAL

Command List

This is a list of all available commands sent or received by the K8090 board.

Command Value

Switch relay ON 11h

Switch relay OFF 12h

Toggle relay 14h

Query relay status 18h

Set button mode 21h

Query button mode 22h

Start relay timer 41h

Set relay timer delay 42h

Query timer delay 44h

Button status 50h

Relay status 51h

Reset factory defaults 66h

Jumper status 70h

Firmware version 71h

Velleman Projects Page 14 August 20, 2010

K8090/VM8090 PROTOCOL MANUAL

Notes

.......................................................................................

Velleman Projects Page 15 August 20, 2010

K8090 Protocol Manual

Navigation menu

Versions of this User Manual:

Views

Navigation