User Tools

Site Tools


register_abstraction_model

Register Abstraction Model

Functionality of a device in VSCP is exposed to the world through 8-bit registers. Much like a IC circuit expose information to the world in electronic systems. This is useful only for the lowest level devices. Higher level devices and users usually get the information in the registers presented as higher level value. This low level information is something the VSCP systems can hide with the help of the MDF information (see [sec:Module-Description-File]). This is this why we talk about an abstraction model.

Above the register model is abstractions (defined below) which describe the system in higher level terms.

Level I - Register Abstraction Model

Byte wide bit registers are a central part of the VSCP specification. All nodes Level I as well as Level II should be possible to be configured by reading/writing these registers. Some of the register are the same for all nodes and are also the same between Level I and Level II nodes. The difference is that Level II can have a lot more registers defined.

Registers 0x00 – 0x7F are application specific. Registers between 0x80 – 0xFF are reserved for VSCP usage. If the node has implemented the decision matrix it is stored in application register space.

With Node control flags (0x83) the node behavior can be controlled. The start up control is two bits that can have two values, binary 10 and binary 01. All other values are invalid and are translated to binary 10. If set to binary 10 it will prevent the initialization routine of the node to start before the initialization button on the node has been pressed.

Bit 5 of the node control flags write protects all user registers if cleared ( == 1 is write enabled). The page select registers (0x92/0x93) can be used if more application specific registers are needed. The page is selected by writing a 16-bit page in these positions. This gives a theoretical user registry space of 128 * 65535 bytes (65535 pages of 128 bytes each). Note that the normal register read/write method can not be used to access this space. The page read/write methods are used instead.

0x98 Buffer size for device is information for control nodes of limitations of the buffer space for a Level II node. Level I nodes should have eight (8) in this position. Level II nodes that can accept the normal Level II packet have 0 which indicates 512-25 bytes or can have some number that represent the actual buffer.

The page read/write, boot events etc can handle more then eight data bytes if the buffer is larger than eight and the implementer wishes to do so. This even if the event is a Level I event.

The VSCP registers are defined as follows:

Register abstraction model
Address Access Mode Description
0x00–0x7F Device specific (a page). Unimplemented registers should return zero.
128/0x80 Read Only Alarm status register content (!= 0 indicates alarm). Condition is reset by a read operation. The bits represent different alarm conditions.
129/0x81 Read Only VSCP Major version number this device is constructed for.
130/0x82 Read Only VSCP Minor version number this device is constructed for.
131/0x83 Read/Write VSCP error counter (was Node control flags prior to 1.6)
132/0x84 Read/Write User ID 0 – Client settable node-ID byte 0.
133/0x85 Read/Write User ID 1 – Client settable node-ID byte 1.
134/0x86 Read/Write User ID 2 – Client settable node-ID byte 2.
135/0x87 Read/Write User ID 3 – Client settable node-ID byte 3.
136/0x88 Read/Write User ID 4 – Client settable node-ID byte 4.
137/0x89 Read only Manufacturer device ID byte 0.
138/0x8A Read only Manufacturer device ID byte 1.
139/0x8B Read only Manufacturer device ID byte 2.
140/0x8C Read only Manufacturer device ID byte 3.
141/0x8D Read only Manufacturer sub device ID byte 0.
142/0x8E Read only Manufacturer sub device ID byte 1.
143/0x8F Read only Manufacturer sub device ID byte 2.
144/0x90 Read only Manufacturer sub device ID byte 3.
145/0x91 Read only Nickname-ID for node if assigned or 0xFF if no nickname-ID assigned.
146/0x92 Read/Write Page select register MSB
147/0x93 Read/Write Page Select register LSB
148/0x94 Read Only Firmware major version number.
149/0x95 Read Only Firmware minor version number.
150/0x96 Read Only Firmware sub minor version number.
151/0x97 Read Only Boot loader algorithm used. 0xFF for no boot loader support. Codes for algorithms are specified here CLASS1.PROTOCOL, Type=12
152/0x98 Read Only Buffer size. The value here gives an indication for clients that want to talk to this node if it can support the larger mid level Level I control events which has the full GUID. If set to 0 the default size should used. That is 8 bytes for Level I and 512-25 for Level II.
153/0x99 Read Only Number of register pages used. If not implemented one page is assumed. Set to zero if your device have more then 255 pages. Deprecated: Use the MDF instead as the central place for information about actual number of pages.
154/0x9A Read Only Standard device family code (MSB) Devices can belong to a common register structure standard. For such devices this describes the family coded as a 32-bit integer. Set all bytes to zero if not used. Also 0xff is reserved and should be interpreted as zero was read. Added in version 1.9.0 of the specification
155/0x9B Read Only Standard device family code Added in version 1.9.0 of the specification
156/0x9C Read Only Standard device family code Added in version 1.9.0 of the specification
157/0x9D Read Only Standard device family code (LSB) Added in version 1.9.0 of the specification
158/0x9E Read Only Standard device type (MSB) This is part of the code that specifies a device that adopts to a common register standard. This is the type code represented by a 32-bit integer and defines the type belonging to a specific standard. Added in version 1.9.0 of the specification
159/0x9F Read Only Standard device type Added in version 1.9.0 of the specification
160/0xA0 Read Only Standard device type Added in version 1.9.0 of the specification
161/0xA1 Read Only Standard device type (LSB) Added in version 1.9.0 of the specification
162/0xA2 Write Only Standard configuration should be restored for a unit if first 0x55 and then 0xAA is written to this location and is done so withing one second. Added in version 1.10.0 of the specification
163/0xA3-207/0xCF Reserved for future use. Return zero.
208/0xD0-223/0xDF Read Only 128-bit (16-byte) globally unique ID (GUID) identifier for the device. This identifier uniquely identifies the device throughout the world and can give additional information on where driver and driver information can be found for the device. MSB for the identifier is stored first (in 0xD0).
224/0xE0-255/0xFF Read Only Module Description File URL. A zero terminates the ASCII string if not exactly 32 bytes long. The URL points to a file that gives further information about where drivers for different environments are located. Can be returned as a zero string for devices with low memory. It is recommended that unimplemented registers read as 0xFF. For a node with an embedded MDF return a zero string. The CLASS1.PROTOCOL, Type=34/35 can then be used to get the information if available.

User ID

This is a register space that can be used to store installation values as for example a location code of where the unit is installed.

Manufacturer device ID/Manufacturer sub device ID

The manufacturer of the device can store whatever they like in thees registers. Typical use is for hardware version. Firmware version. Batch numbers. Serial numbers and such.

Page select

The page select registers can be used to switch pages for the lower 128 byte. Its important that an application that uses the page functionality switch back to page 0x0000 when its ready. Applications can use the page registers as a mutex which is signaled when not zero.

Standard device families and types

Added in version 1.9.0 of the specification

Some devices has a need for a common register structure standard. This is defined by two 32-bit values in the standard register space. The family value defines the group of devices the module belongs to and the type value describes the specific device type in that family it belongs to. Families and device types are still to be defined.

Level II - Register Abstraction Model

The level II abstraction model is the same as Level I but covers a much wider address space.

The registers are laid out in an 32-bit address space with the standard Level I register map on the top (0xFFFFFF80 - 0xFFFFFFFF) and where 0xFFFF0000 - 0xFFFFFFFF is a reserved area.

Abstractions

A VSCP unit is describing it's configuration to the world with the register model above where each register is eight bit in width. This is often inconvenient for a human user who is used to higher level types and this is what abstractions are there for. They sit above registers and specify types as strings, floats, integers and other such higher level types.

Just as register definitions, abstractions live there life in the Module Description file (MDF).

The following abstractions are currently defined

Abstraction Description
string A text string (UTF8 coded)
bitfield A field of bits. Width tells how many bits the field consist of. When read from a device the number of bits will always be in even octets with unused bits set to zero. Bitfield is taken from MSB part thrue LSB and continues that way on next octet in the series.
bool A 1 bit number specified as true or false.
int8_t An 8 bit number. Hexadecimal if it starts with “0x” else decimal.
uint8_t An unsigned 8 bit number. Hexadecimal if it starts with “0x” else decimal.
int16_t A 16 bit signed number. Hexadecimal if it starts with “0x” else decimal.
uint16_t A 16 bit unsigned number. Hexadecimal if it starts with “0x” else decimal.
int32_t A 32 bit signed number. Hexadecimal if it starts with “0x” else decimal.
uint32_t A 32 bit unsigned number. Hexadecimal if it starts with “0x” else decimal.
int64_t A 64 bit signed number. Hexadecimal if it starts with “0x” else decimal.
uint64_t A 64 bit unsigned number. Hexadecimal if it starts with “0x” else decimal.
float Data is coded as a IEEE-754 1985 floating point value That is a total of 32-bits. The most significant byte is stored first.
double IEEE-754, 64 Bits, double precision. That is a total of 64-bits. The most significant byte is stored first.
date Must be passed in the format dd-mm-yyyy and mapped to “yy yy mm dd” that is four bytes, MSB→LSB
time Must be passed in the format hh:mm:ss where hh is 24 hour clock and mapped to “hh mm ss” MSB→LSBthat is four bytes.
guid Holds the 16 bytes of a GUID. Stored on the form 11:22:33:… MSB→LSB

A note on floating point numbers and storage (source Wikipedia)

“Although the ubiquitous x86 of today use little-endian storage for all types of data (integer, floating point, BCD), there have been a few historical machines where floating point numbers were represented in big-endian form while integers were represented in little-endian form.” … “However, on modern standard computers (i.e., implementing IEEE 754), one may in practice safely assume that the endianness is the same for floating point numbers as for integers, making the conversion straightforward regardless of data type.”

synonyms

Abstraction Description
char Is the same as “int8_t”.
byte Is the same as “uint8_t”.
short Is the same as “int16_t”.
integer Is the same as “int16_t”.
long Is the same as “int32_t”.

index storage

This type of storage takes up two bytes in register space. The first byte is the index into the second.

Abstraction Description
index8_int16_t 16-bit signed integer
index8_uint16_t unsigned 16-bit integer
index8_int32_t 32-bit signed integer
index8_uint32_t 32-but unsigned integer
index8_int64_t 64-bit signed integer
index8_uint64_t 64-bit unsigned integer
index8_float 32-bit floating point value
index8_double 64-bit floating point value
index8_date “date” see above.
index8_time “time” see above
index8_guid “guid” see above
index8_string UTF8 string stored as [width, string]. Width tells how long the strings are. If any of them are shorter then this value it should be zero terminated.



Paradise of the Frog AB

register_abstraction_model.txt · Last modified: 2017/07/12 20:11 (external edit)