VSCP FAQ

Also have alook at the canal_faq

CANAL is CAN abstraction layer. It is a generic interface to interface any CAN hardware adapter.

The vscp/canal daemon uses CANAL to interface hardware drivers. This way the daemon (or any other application software that wants to use the device) has one interface for drivers with very different properties.

VSCP Level I events fits perfectly in a CAN frame by design. Therefore it is possible to write drivers that interface other things such as WINLIRC (IR receivers/transmitters), xAP, SSH remote links, RS-232, X10 and more.

The driver is a “dll” or a “so” under Unix/Linux. The interface is well known and common to all and you can therefore build software that can work the same way on different hardware devices.

The daemon exports a CANAL interface to all drivers connected to the daemon. A wrapper class is available that lets you write software that looks the same regardless if it is using the daemon or talks directly to a driver.

VSCP is both open and free and there is no charge for its usage. You are also allowed to use the code and change it in any way you like. Some code are GPL/LGPL which means you have to share your changes. Some code are free for all uses.

There are three licenses used in this project. GPL, LGPL and freeware. If you use and change GPL'ed code you have to share your own changes and code as well. For LGPL code you are allowed to use it in your proprietary code without charge and need to reveal your code. The freeware code can be used in any way you like. Freeware is used for most general VSCP client routines and for all firmware code.

If you don't like this there is a commercial license available from eurosource

Send a mail to guid@vscp.org with your contact information (mail, phone, web) and we will return a GUID to you as soon as possible. There is no cost for this service.

As of inter segment communication it can be complicated and easy.

One approach is to have a level II bus that holds segments together. When events pass the segment barrier from the Level I segment nicknames are translated into full GUID's. When GUID's is received that is on the segment that a specific “segment boundary device” (segment controller) is on they are transferred to the local segment with the GUID replaced by the nickname. The segment controller thus has to know the GUID's of the devices on its segment. Not a hard thing even dynamically.

Another and simpler approach is to let the “segment controller” take the event from the segment. Replace the nickname with its own nickname id and send it out on the other segment(s). Much like a proxy.

Its no need to understand everything at least not when one start to experiment with VSCP.

Only one concept that is important to understand really. That is:

Each node can inform others with the help of events (which are well sepcified). It normally does not matter if anyone listens or just talks. Sometimes this talk is pretty certain to reach its destination, (CAN, TCP/IP), sometimes it don't know (UDP,RF etc) and from VSCP point of view it does not care.

After that

1. All nodes are identified by a 128-bit Globally unique ID, GUID.
2. 128 8-bit registers are defined by each node that have predefined contents (not all are used) ( http://www.vscp.org/wiki/doku.php?id=vscp_specification_register_abstraction_model).
3. Up to 128 8-bit registers can be defined for a nodes functionality/configuration. (As for the relay node (look at registers) http://www.vscp.org/wiki/doku.php?id=smart_relay_control_-_intelligent_relay_control_module)
4. Nodes can have a decision matrix built in. This matrix can be programmed to make the node react on external events on the form Event - Decision - Action
   (http://www.vscp.org/wiki/doku.php?id=vscp_specification_decision_matrix)
5. Every node got a Module Description File (MDF) that describes its registers, events, decision matrix capabilities etc in a higher level language (XML). The location for this file can be fetched from the registers. (http://www.vscp.org/wiki/doku.php?id=vscp_specification_mdf with a real life sample here http://www.eurosource.se/sht_001.xml)

That's it really.

It all comes down to

1. Sending events of predefined class + Type (we together adding events/classes as needs arise (or an interest group can own its own classes and do this themselves) (Currently defined stuff here
   http://www.vscp.org/wiki/doku.php?id=vscp_specification_level_i_events).
2. Reading/writing registers.

By thinking this way you can have a node such as the temperature node that triggers other stuff without knowing it and to which things can be added in a plug an play fashion where only the decision matrix needs to be manipulated at the new nodes and no master is needed but can be incorporated without affecting the rest of the system.

As everything in VSCP (as for CAN) is broadcasted zone/subzone can be used to “address” a group of nodes. This way it is possible to send for example a mute command to them. Several other are here http://www.vscp.org/wiki/doku.php?id=vscp_specification_class_30 Some events should also respon with events that contain the modules zone/subzone for example http://www.vscp.org/wiki/doku.php?id=vscp_specification_class_20

When we write CLASS1.ALARM we refer to a Level I event in the ALARM (CLASS=1) group (http://www.vscp.org/wiki/doku.php?id=vscp_specification_class_1).

In the same way CLASS1.PROTOCOL can be found here http://www.vscp.org/wiki/doku.php?id=vscp_specification_class_0

The naming convention used is like this

So

CLASS1.INFORMATION is here http://www.vscp.org/wiki/doku.php?id=vscp_specification_class_20

and

CLASS2.INFORMATION is here http://www.vscp.org/wiki/doku.php?id=vscp_specification_class_1026

So to find CLASS1.PROTOCOL Type 37 look at the page http://www.vscp.org/wiki/doku.php?id=vscp_specification_class_0

No. Your code just need to understand the events in CLASS1.PROTOCOL and this is handled by the firmware code. Then you might want to handle some other events of your choice or perhaps implement a decision matrix so you give the user of your device the decision to decide which event that should trigger a specific functionality (action) of your device.

125 kbps is the standard bitrate over CAN. Other bitrates can be used but all nodes must support 125 kbps.

This is dependant on the speed but if using the standard speed of 125 kbps the cable can be max 500 meters. The same timing as for CANopen is used and more info can be found here http://www.canopen.org/canopen/protocol/bittiming.html.

Yes! VSCP uses extended 29 bit addressing and CANopen used standard 11-bit addressing.

GUID stands for Globally Unique ID and is for VSCP a number consisting of 16 bytes that is and should be unique throughout the world for every node in a VSCP net. No two nodes should have the same GUID much the same as two nodes on an Ethernet don't have the same MAC address.

No it's free of charge. When you ask for a vendor ID you get a 12 byte number that represents the first 12 bytes of the complete 16-bit GUID. The remaining four bytes can be used in any way you like which gives you 4294967295 possibilities. Typical this is used as a serial number for your device.

Write to guid@vscp.org and we will register your GUID. Please add your mail and postal address to the mail.

No everyone can get there own id.

Yes write to guid@vscp.org and tell us why you need more GUID's ( 4294967295 is a lot!!! ) and you can get an additional vendor id or an extra byte (that is 1099511627775 nodes).

Yes! There are several well known ID's that are reserved and can be used without asking us for a GUID.

The Dallas 64-bit (8 byte) id can be used. This gives GUID's of the form

ff ff ff ff ff ff ff ff xx xx xx xx xx xx xx xx

where xx represent the Dallas id with the most significant byte to the left.

MAC Address. This is a 48-bit id ( 6-bytes). This gives GUID's of the form

ff ff ff ff ff ff ff fe xx xx xx xx xx xx yy yy

where xx represents the MAC address with the most significant byte to the left and yy represent a user assigned number.

Internet version 4 address. This is a 32-bit id ( 4-bytes). This gives GUID's of the form

ff ff ff ff ff ff ff fd xx xx xx xx yy yy yy yy

where xx represents the IP address with the most significant byte to the left and yy represent a user assigned number.

Private address. This is a 64-bit id ( 8-bytes). This gives GUID's of the form

ff ff ff ff ff ff ff fc yy yy yy yy yy yy yy yy

Any number can be used for the yy as long as its unique for the installation.

ISO id. This is a 24-bit id ( 3-bytes). This gives GUID's of the form

ff ff ff ff ff ff ff fb xx xx xx yy yy yy yy yy

where xx represents the ISO id with the most significant byte to the left and yy represent a user assigned number.

CiA vendor id. This is a 32-bit id ( 3-bytes). This gives GUID's of the form

ff ff ff ff ff ff ff fa xx xx xx xx yy yy yy yy

where xx represents the CiA vendor id with the most significant byte to the left and yy represent a user assigned number.

For LAB usage the 00 00 00 00 00 00 00 00 00 00 00 00 yy yy yy yy can be used. Also here the yy bytes can be used freely.

Normally the first found Ethernet MSC address of the computer where the daemon runs used as the basis for this GUID. The least significant byte is the nickname-id for the node sending the event and the next least signifiant byte is the id for the driver interface this node is at.

The actual GUID used can be set in the configuration file. Also gere the least significant byte will be the nickname-id and the next least significant byte the interface id.

Example
FF FF FF FF FF FF FF FE 00 05 5D 8C 02 00 02 01

For this GUID the Ethernet MAC address has been used and a node with nickname-id = 1
connected to device interface with id 2 sent the event.

There are two methods to achive this.

Method 1

Configure the new node with the old nickname before adding it to the segment. It will start up using the same nickname as the old module.

Metod 2

Remove the faulty module and add the new one. It will find a new nickname-address when it starts up and goes through the nickname discovery process. As the nickname is in the >128 register space we can just write a new nickname there using the write register events.

class=CLASS1_PROTOCOL
type=Write Register
data byte 0 = old nickname
data byte 1 = 0x91
data byte 2 = new nickname

The response should come form the “old node”.

class=CLASS1_PROTOCOL
type=Read/Write response
data byte 0 = 0x91
data byte 1 = new nickname

After this the node will use the new nickname on the segment.

VSCP uses GUID for addressing. Depending on the the environment it is running in other identification tokens - as the nickname on Level I segments - can be used. Only one rule apply and that is that the GUID should be possible to deduced from the id-token.

Nodes can be grouped by zone/subzone. Bot are values from 0-255 where 255 have the meaning “all”. Its up to the users/installer to decide how they are used. Typically zone can be a house, a room or something and subzone a sub part of that. Note that this is not addresses. Any number of nodes can have the same zone/subzone.

If the zone/subzone concept is used it is preferably possible to configure them through some registers.

Some nodes have functionality that holds a combination of different functionality. Typical examples are a light detector and a relay, eight input module etc. Also we have another group measurement devices that can have severals sensors.

For the combined devices the zone is typically used for the device and the subzone select the individual functionality. By doing this we can create decision matrix elements that do something like this

- Do this action if this event is for zone/subzone. Optionally also the originating nickname can be used in the selection.

If a node identifies similar subgroups with the subzone member something like this can be used

- Do this action if this event is for this zone and subzone as argument. Again the nikcname can be used also.

The user can thus program the device and tell it on what event and for which zones/subzones it should react.

For measurement devices things can be a be different. This is because this type of devices got a sensor index already built into the event. This is coded into the data coding byte that is present for all measurement events (http://www.vscp.org/wiki/doku.php?id=vscp_specification_data_coding). Three bits are available so up to eight sensors can be handled by one device.

The Paris module (http://www.vscp.org/wiki/doku.php?id=smart_relay_control_-_intelligent_relay_control_module) is a reference installation where the combined concept is shown and the Kelvin Smart II module (http://www.vscp.org/wiki/doku.php?id=kelvin_smart_ii_-_temperature_times_2_module) shows a multi sensor module.

Look at registers 0×92/x93

http://www.vscp.org/wiki/doku.php?id=vscp_specification_register_abstraction_model

they select which page of registers you map into register address space 0-0x7f. For nodes that just need one page they have no meaning for a node that have more then 128 registers they have to be used.

Usage is

- set the page - read/write register

Two events isavailable to take care of this in an atomic way. Look at CLASS1.PROTOCOL, Type=36 etc

For a generic package we have

[0] Head
[1] Class MSB
[2] Class LSB
[3] Type MSB
[4] Type LSB
[5] GUID byte 15 MSB
[6] GUID byte 14
[7] GUID byte 13
[8] GUID byte 12
[9] GUID byte 11
[10] GUID byte 10
[11] GUID byte 9
[12] GUID byte 8
[13] GUID byte 7
[14] GUID byte 6
[15] GUID byte 5
[16] GUID byte 4
[17] GUID byte 3
[18] GUID byte 2
[19] GUID byte 1
[20] GUID byte 0 LSB 
[21] Data size MSB 
[22] Data Size LSB
.....
..... Data if any
.....
[len-2] CRC MSB
[len-1] CRC LSB

This is specified in the vscp.h header file.

The following table illustrates how the filters works

Think of the mask as having ones at positions that are of interest and the filter telling what the value should be for those bit positions.

• So to only accept one class set all mask bits to one and enter the class in filter.
• To accept all classes set the mask to 0. In this case filter don't care.

If you have have started the dameon and try to communicate using two instances in CanalWorks for example or the testif application and you get a an error telling you that no server is found this may be due to the canald service started without a priviledged user. This is fully described here canalservice_documentation.

This is somewhat work in progress therefore there are two answers to this question. How it works today and how it will work.

An event from a low end device hooked to the driver interface will go out to the client interface as a Level I message and out on the UDP interface as a Level II event with the GUID of the low level interface.

A Level I event sent on the client interface will be sent on all low level interfaces and also on the UDP interface as a Level II event with GUID of the client interface.

A Level II event sent on the client interface will be sent out on the UDP interface as it is. The user decide if the interface GUID or some other GUID should be used.

A Level II event received from the UDP interface will be sent to all clients.

A Level I event received from the UDP interface will be sent to all clients and all devices.

All this is OK as long as we don't use the Level I CLASS.PROTOCOL types. There is no way today to route an event to the correct place.

An event from a low end device hooked to the driver interface will go out to the client interface as a Level I message and out on the UDP interface as a Level II event with the GUID of the low level interface OR the real GUID of the device if it's known.

A Level I event sent on the client interface will be sent on all low level interfaces and also on the UDP interface as a Level II event with GUID of the client interface if not CLASS.PROTOCOL. If it is CLASS.PROTOCOL and has a GUID the system knows of it will be sent only to that device. If not know old behaviour is used.

A Level II event sent on the client interface will be sent out on the UDP interface as it is. The user decide if the interface GUID or some other GUID should be used. Same as before.

A Level II event received from the UDP interface will be sent to all clients.

A Level I event received from the UDP interface will be sent to all clients and all devices if not CLASS.PROTOCOL. If it is CLASS.PROTOCOL and has a GUID the system knows of it will be sent only to that device. If not know old behaviour is used.

You have to add the shared library to your systems search path. A good explanation is available here

http://www.eyrie.org/~eagle/notes/rpath.html

This can be due to a missconfigured hostname. Check your hosts file. The 127.0.0.1 entry should be something like

 127.0.0.1       localhost        localhost.localdomain

The reason you get two events logged is that the daemon can't determine that the UDP event it sends out is comming from your machine and therefore receives its own events also. You can see this as the low eight bits of the id always is set to zero for the extra event.

Also have alook at the canal_faq