Every VSCP device have registers. Registers abstract the settings for any device. Actually a non VSCP device can have a driver that abstract the devices actual setup, whatever it is, into registers.
So what is a register? In VSCP it’s just a byte wide position that can be read or written. Hence to configure a device one simply write registers, to find out the configuration of a device one simply read registers. Two simple operations. Read and write a byte.
Registers is divided in two types. User registers and standard registers. The standard registers is you will find at the same location on every device, that is in position 80-255 on level I devices and at 0xffffff80 – 0xffffffff on Level II devices.
Standard registers contain information about a device. The most important information you can find here is the 16-byte GUID which is a globally unique id for the device and the MDF URL which locates the Module description file. You can find firmware version, alarm status and a lot of other information here as well (more info here) .
As the standard registers is at the same location on every device and they always have the same type of content they are easy to use without any more information. The user registers on the other hand can contain anything the maker of the device want them to contain. Actually we call the registers a register abstraction model as they often model a more complex setup that may look like it needs more than just a bunch of 8-bit registers.
For a level I device there are 128 user registers available in the range 0-127. But this register space is also paged into 65535 pages. Level II device use 0-0xffffff80 for user registers.
As the standard registers can contain anything there is a need for a description on their content. This information is available in the MDF (Module Description File). This XML files location is pointed out in the standard register space and can be fetched by software that need to configure the device. The pointer is a standard URL so the file usually is located on a standard web server.
You can read about the full content of the MDF here. An example real life MDF is here.
The register content of a device is specified in the MDF. Typically a record looks like this
<reg page="0" offset="11" bgcolor="0xFFFFCC">
<name lang="en">Relay 1 control register</nam> <description lang="en">The relay control bits enable/disable intelligent relay functionality:\n
Bit 0 - Enable pulse.\n
Bit 1 - If set: Alarm sent when protection timer triggers.\n
Bit 2 - Protection timer enable.\n
Bit 3 - Send On event when relay goes to active state.\n
Bit 4 - Send Off event when relay goes to inactive state.\n
Bit 5 - Send Started event when relay goes to active state.\n
Bit 6 - Send Stopped event when relay goes to active state.\n
Bit 7 - If set to one the relay is enabled.\n
</description><access>rw</access><bit pos="0" default="false"><name lang="en">Reserved</name><description lang="en">This bit is reserved</description></bit><bit pos="1" default="false"><name lang="en">Protection alarm</name><description lang="en">If set: Alarm sent when protection timer triggers.</description></bit><bit pos="2" default="false"><name lang="en">Protection timer enable</name><description lang="en">
If set: Protection timer is enabled and will deactivate relay channel when the timer times out.
</description></bit><bit pos="3" default="false"><name lang="en">On event on activate enable</name><description lang="en">
If set: An on event will be sent when the relay is turned on.
</description></bit><bit pos="4" default="false"><name lang="en">Off event on deactivate enable</name><description lang="en">
If set: An off event will be sent when the relay is turned off.
</description></bit><bit pos="5" default="false"><name lang="en">Started event on activate enable</name><description lang="en">
If set: A started event will be sent when the relay is turned on.
</description></bit><bit pos="6" default="false"><name lang="en">Stopped event on deactivate enable</name><description lang="en">
If set: A stopped event will be sent when the relay is turned off.
</description></bit><bit pos="7" default="false"><name lang="en">Enable relay</name><description lang="en">
Set this bit to make the relay controlable.
</description></bit></reg>
In this case a description of the bits in a register and how they make the device behave as they are set or cleared. This register is at location 11 on page 0, usually written as 0:11.
Note that we can reach this level of abstraction with a protocol that have only two operations, read and write, it’s hard to think of a simpler protocol than that.
The intended user of the MDF is a configuration software. This piece of software read the MDF location from the device, download it from the server, parse it, and can then help a user to set up a device. Good thing is that one piece of software works for all devices. Later we will explain the wizards that are available in the MDF which makes this even more useful.
Abstractions
A register is an 8-bit location as we said. Now how about storing things, like floating point value, that does not fit in an 8-bit location. Well the answer is simple of course. Store them in multiple 8-bit locations.
To describe this abstractions are used. Abstractions sit on top of registers and specify how higher end types such as integers, strings, floating point values are stored in register space. So a higher end software usually does not bother with registers it instead work with the high level types it usually deal with.
An example from the same MDF we sampled before
<abstraction type="short" default="0" page="0" offset="18" bgcolor="0xCCFFFF"><name lang="en">Relay pulse time register for relay 0</name><description lang="en">
This is the pulse time for the each relay expressed in seconds.
This can be used to have a relay turn on and off with a certain
preset interval. The min pulse time is 1 second and the max time
is 65535 seconds which is about 18 hours. Set to zero (default)
for no pulse time i.e. the relay will be steady on/off.\n\n
To start a pulse sequence first write the pulse time to this
register and then write 2 to the relay status register to start
the output. The pulse train is terminated by writing on or off
(1 or 0) to the relay status register.\n
</description><access>rw</access></abstraction>
show an integer that has its MSB at pos 0:18 and it’s LSB at 0:19 (Everything in register space is stored MSB first)
Software tools like VSCP Works (available in the VSCP & friends package) can handle configuration of any device. Some web-based tools is on the way to do the same.
There is no need for things to be more complicated.