Very Simple Control Protocol

The Very Simple Control Protocol (VSCP) is a free automation protocol suitable for all sorts of automation task where building- or home-automation is in the main focus.

Its main advantage is that each VSCP-node can work completely autonomous, being part of distributed network of other nodes.

VSCP is independent from the physical layer (e.g. CAN bus, Ethernet, RS-485, RS-232, MiWi) connecting the individual nodes to form the automation network bus. On the bus there can be nodes reading switches, controlling lighting, blinds, windows or information displays, broadcasting physical measurements (e.g. temperature, luminosity, power consumption, etc.), multimedia control, burglar- or fire-alarm, etc.

There is a subset of the protocol (Level I) that is very much tailored to the CAN bus and resource restricted microcontrollers. Protocol Level II is designed for Ethernet (UDP, TCP and own Ethernet-type Raw-Ethernet) and wireless physical layers. All share the same common message fields and framework and can be connected through gateways.

Event

VSCP is based on events. Each time an event occurs it is broadcast towards all other nodes. Each node on the network will receive the event and will decide if this event needs to be handled or not.

The example given in the diagram describes a button being pressed. This will result in node 1 sending an event message onto the bus informing all others the button is pressed. Node 2 receives the message but decides this button should not trigger an event for node 2. Node 3 receives the message and decides this button should trigger lamp 2 to turn on.

There can be events for all sorts of things happening: an event can be a button pressed, a presence sensor being triggered, or the sun setting. Events can also be sent periodically, for instance a temperature reading every minute. VSCP predefines many events that could be happening. These events are defined into classes and types. Whether or not an event received should be handled is determined by the decision matrix or DM in short. Also the DM is explained further.

Event Class and Type

Events are organized into Classes. A class is a collection of events that somehow belong together. There are classes for ALARM, MEASUREMENTS, CONTROL, INFORMATION, etc. Currently VSCP specifies about 25 classes, but has room for many more 1. Each class is on its turn subdivided into types. A type further specifies the event within the class. For instance, events of Class 20 (0x14) are INFORMATION events. In this class there is a subtype 1 (0x01) BUTTON signaling a button being pressed. In this same INFORMATION class there are also types to signal ON, OFF, BELOW LIMIT, etc. Likewise in class measurements there are types to signal temperature, current, voltage, etc. Having all these classes and types defined makes the nodes speak the same language. For a full list of pre-defines classes & types check the VSCP wiki.

VSCP event datagram structure

Events that are broadcast contain a number of fields together forming one VSCP datagram. Exactly how these fields are mapped onto the physical layer is specified for a number of physical layer protocols such as CAN, Ethernet, TCP, etc. For others it is not yet defined, but it is in general not difficult to map these fields onto a physical layer protocol. There are 2 levels of the VSCP protocol called LEVEL I & LEVEL II. They are both basically the same protocol but differ in size of the different fields.

Level I is intended to run on nodes with more constrained resources and fields are defined a bit more conservatively. Level I is in fact a subset of level II, and with an appropriate gateway events can transverse between a Level I & II network.

VSCP datagram level I

Priority	Hardcoded ID	CLASS	TYPE	SenderNickID	DataSize	Payload	CRC
3 bits	1 bit	9 bits	8 bits	8 bits	4 bits	0 to 8 bytes	16 bits

Level II is intended to be run on nodes that have little resource constraints and can easily cope with larger message sizes.

VSCP datagram level II

Priority	Hardcoded ID	CLASS	TYPE	SenderGUID	DataSize	Payload	CRC
3 bits	1 bit	16 bits	16 bits	128 bits	16 bits	0 to 487 bytes	16 bits

Decision matrix

VSCP class/event mask & filter

When events are received by a node the node needs to determine if it needs to execute a task based on that event. This is done by evaluating the decision matrix or DM in short. The DM matrix is made of a number of IF ... THEN ... conditions. Each such IF/THEN condition is called a line and multiple lines make up the decision matrix.

The Class and Type of the incoming message is always evaluated by a DM line. Evaluating Class & Type is done by passing the Class/Type through a mask first and then comparing with a filter. This method allows multiple class/Types to trigger a valid condition for 1 line of the DM. The other conditions for the DM line (SenderGUID, Zone, Subzone) are optionally evaluated. If the DM line is valid then the ACTION is executed. Together with the ACTION there is an ACTION parameters. An example ACTION would be: turn-on relay 6 with 6 being the action parameter. Exactly which ACTIONs are possible by the receiving node is determined by the design of the node itself. It is up to the firmware developer to define which actions can be executed. By then documenting the possible action in the MDF file (see later) the configuration SW will know how to select this action. The DM can be modified by setting the appropriate node configuration registers. A convenient way to do this is using the VSCPWorks configuration SW.

DataPayload

An event being sent can also carry a data payload. The content & organization of this payload is depending on the class and type of the event. For example, an event of class 10 (measurement) and type 6 (temperature) will carry the temperature data (with coding determined by byte 0, degrees or Celsius) in its payload. A button event will carry information about the button & button zone/subzone in its datapayload. For each class/type the data formatting is determined in the spec, please consult the wiki for details.

Zone/subzone

Some (quite some) events contain a field zone and a field subzone in their datapayload. This functionality is present to make grouping of nodes possible. For instance we could determine that all buttons controlling a certain lamp are part of the same group. This simplifies the DM for certain scenarios. Instead of having one DM line as the lamp node for each button (1 line per button: IF button x then turn-on lamp) we could have 1 DM line only saying IF (zone match) THEN turn-on lamp. Making multiple node switches part of a group is done by configuring the nodes, the firmware of the node will support this functionality.

Configuring a VSCP node

A node needs to be configured appropriately before it will execute its function. Each VSCP node provides its own set of configuration registers tailored for its function. A button node would have some possibility to configure the zone/subzones the buttons belong to. A temperature node would have some possibility to set trigger values. Also configuring the DM is part of configuring a node.

Configuration registers

VSCP register space

Configuring a node is done by writing to registers. Each (Level I) node provides access to 256 registers. The highest 128 registers are reserved for VSCP core functions. In these 128 registers we find items such as node GUID, Nickname, MDF and a paging register. The lower 128 registers are free for application specific use. If 128 registers are not sufficient then there is a 16bit paging possibility. This allows for 65536 x 128 8bit registers for application use. Writing/reading these registers is done using CLASS 0 events. Class 0 events are VSCP protocol functionality messages intended for configuring and managing nodes.

Module Description File

Keeping track of which register serves what purpose can be a challenge, especially for the application specific registers. But this is where the module description file or MDF comes in. The MDF file is a machine-readable XML file describing the function of each register of a module, giving the configuration options for that register, etc. This file is used by configuration software (VSCPWorks) to show configuration options specific for the module addressed. The MDF file can be stored on the node itself and fetched from there by VSCPWorks, but more commonly the MDF file will be an XML file hosted on a webserver somewhere. A node then just needs to inform VSCPWorks where (URL) the XML file can be found. This URL is present in the VSCP reserved registers 0xE0-0xFF.

VSCPWorks

Screenshot of VSCPworks

VSCPworks is the PC (Linux & Windows)-based tool to configure and manage the nodes. VSCPWorks allows reading/setting registers presenting those registers in a human-readable format by parsing the MDF file automatically. VSCPWorks also provides wizards to set the decision matrix.

VSCP & Friends

If VSCP is the protocol VSCP & Friends is used to name a software API, schema and abstraction layer built around VSCP. VSCP & Friends allow for layered abstractions of legacy devices by using drivers that make them look like VSCP devices. This means any device can be controlled and monitored with the VSCP & Friends framework. VSCP & Friends solves four common IoT and M2M problems

• Uniform device discovery and identification.
• Uniform device configuration.
• Autonomous/distributed device functionality.
• Uniform way to update/maintain device firmware.

External links

• Homepage of the VSCP project
• VSCP Specification
• VSCP Documentation
• VSCP modules