Abstract
VSCP stands for Very Simple Control Protocol and it is, as the name implies, a very simple protocol. It is simple because it has been developed for use on low end (read low cost) micro controllers. VSCP is actually more then just a protocol. Collected in a package described as VSCP & friends its a complete solution for measurement and control. The protocol was placed in the public domain in year 2000 when the project first was started and is therefore free to use and implement for everyone. VSCP uses a very well specified event format and supports global unique identifiers for nodes making a node identifiable wherever it is installed in the world. It has a register model to give a flexible common interface to node configuration and a model for controlling node functionality. VSCP does not assume anything about the lower level system. It works with different transport mechanism such as Ethernet, TCP/IP, Wireless, Zigbee, Bluetooth, CAN, GPRS, RS-232, USB. Every control situation can be described and implemented using VSCP.
VSCP is an open source standard protocol for Home Automation and other remote control applications. It enables simple, low-cost devices to be networked together with high-end computers, whatever the communication media used.
There are a lot of technologies and protocols that claims to be the perfect solution for home automation and SOHO (Small Office/Home Office) control. X10 is the most well known system using power line. More and more RF solutions are now available too: Bluetooth, Zigbee, Z-wave, Wifi, etc. Many systems use a dedicated bus based on RS485, CAN, LIN, LON, TCP/IP, etc. or can sometimes support different transport layers: CANopen, KNX (EIB), C-Bus, LonWorks, etc.
Most of them are proprietary, some are somehow “open”, meaning you can participate if you’re part of the alliance and pay your yearly fees, or anything similar. Except the small companies that have their own proprietary and completely closed small and simple protocols, the more standard solutions are usually difficult to understand, implement and require quite a bit of resources.
VSCP was designed with the following goals in mind:
The VSCP Protocol was initially used in CAN networks. CAN is very reliable and cheap today and allow us to manufacture low cost nodes that can work reliably, efficiently and can be trusted in their day-to-day use. But VSCP can be used equally well in other environments than CAN.
To meet both low cost and performance, VSCP is divided into 2 levels. Level 1 is intended for low-end nodes (i.e. based on tiny micro-controllers) while Level 2 is intended for higher level and faster transport layers such as TCP/IP. All nodes can talk together but level 2 nodes achieve better performance when talking together, while level 1 nodes that don’t require much processing can be implemented with very cheap technologies.
This protocol is open and free in all aspects that are possible. We want you to contribute work back to the project if you do your own work based on our code but we also like to make as much of this work useful also in commercial projects. The tool we have chosen to do this is the GNU public license and the lesser GPL. For firmware code we use an even more open model so that there is no question that you are allowed to put the code in your own commercial projects if you feel to do that.
The GPL license and the LGPL license is included in the distribution of code in the file COPYING but can also be ordered from by writing to the Free Software Foundation, 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
There is an exception in the license from GPL/LGPL that make the tools more useful for commercial use.
Alternative licenses for VSCP & Friends may be arranged by contacting eurosource at info@eurosource.se, http://www.eurosource.se
VSCP & Friends is licensed under tree different licenses.
As of February 2006, VSCP & Friends is released under a modified version of the well known GNU General Public License (GPL), now making it an official GPL-compatible Free Software License. An exception clause has been added to the VSCP & Friends license which limits the circumstances in which the license applies to other code when used in conjunction with VSCP & Friends. The exception clause is as follows:
As a special exception, if other files instantiate templates or use macros or inline functions from this file, or you compile this file and link it with other works to produce a work based on this file, this file does not by itself cause the resulting work to be covered by the GNU General Public License. However the source code for this file must still be made available in accordance with section (3) of the GNU General Public License.
This exception does not invalidate any other reasons why a work based on this file might be covered by the GNU General Public License.
The goal of the license is to serve the VSCP & Friends user community as a whole. It allows all VSCP & Friends users to develop products without paying anything, no matter how many developers are working on the product or how many units will be shipped. The license also guarantees that the VSCP & Friends source code will always be freely available. This applies not only to the core VSCP & Friends code itself but also to any changes that anybody makes to the core. In particular, it should prevent any company or individual contributing code to the system and then later claiming that all VSCP & Friends users are now guilty of copyright or patent infringements and have to pay royalties. It should also prevent any company from making some small improvements, calling the result a completely new system, and releasing this under a new and less generous license.
The license does not require users to release the source code of any applications that are developed with VSCP & Friends. However, if anybody makes any changes to code covered by the VSCP & Friends license, or writes new files derived in any way from VSCP & Friends code, then we believe that the entire user community should have the opportunity to benefit from this. The license stipulates that these changes must be made available in source code form to all recipients of binaries based on the modified code, either by including the sources along with the binaries you deliver (or with any device containing such binaries) or with a written offer to supply the source code to the general public for three years. It is perhaps most practical for VSCP & Friends developers to make the source code available online and inform those who are receiving binaries containing VSCP & Friends code, and probably also the VSCP & Friends maintainers, about the location of the code. See the full text of the GPL for the most authoritative definition of the obligations.
Although it is not strictly necessary to contribute the modified code back to the VSCP & Friends open source project, we are always pleased to receive code contributions and hope that developers will also be keen to give back in return for what they received from the VSCP & Friends project completely free of charge. The VSCP & Friends maintainers are responsible for deciding whether such contributions should be applied to the public repository. In addition, a copyright assignment is required for any significant changes to the core VSCP & Friends packages.
The result is a royalty-free system with minimal obligations on the part of application developers. This has resulted in the rapid uptake of VSCP & Friends. At the same time, VSCP & Friends is fully open source with all the benefits that implies in terms of quality and innovation. We believe that this is a winning combination.
You have the right to incorporate any code of VSCP & Friends in your own application and resell it without any need to re-share any code.
The commercial licenses is available from eurosource, akhe@eurosource.se.
The following queries provide some clarification as to the implications of the VSCP & Friends license. They do not constitute part of the legal meaning of the license.
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
This file is part of the VSCP (http://can.sourceforge.net) Copyright (C) 2000-2010 Ake Hedman, eurosource, <akhe@eurosource.se>
Version 3, 29 June 2007
Copyright Ⓒ 2007 Free Software Foundation, Inc. <http://fsf.org/>
Preamble The GNU General Public License is a free, copyleft license for software and other kinds of works.
The licenses for most software and other practical works are designed to take away your freedom to share and change the works. By contrast, the GNU General Public License is intended to guarantee your freedom to share and change all versions of a program–to make sure it remains free software for all its users. We, the Free Software Foundation, use the GNU General Public License for most of our software; it applies also to any other work released this way by its authors. You can apply it to your programs, too.
When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for them if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs, and that you know you can do these things.
To protect your rights, we need to prevent others from denying you these rights or asking you to surrender the rights. Therefore, you have certain responsibilities if you distribute copies of the software, or if you modify it: responsibilities to respect the freedom of others.
For example, if you distribute copies of such a program, whether gratis or for a fee, you must pass on to the recipients the same freedoms that you received. You must make sure that they, too, receive or can get the source code. And you must show them these terms so they know their rights.
Developers that use the GNU GPL protect your rights with two steps: (1) assert copyright on the software, and (2) offer you this License giving you legal permission to copy, distribute and/or modify it.
For the developer’s and author’s protection, the GPL clearly explains that there is no warranty for this free software. For both user’s and author’s sake, the GPL requires that modified versions be marked as changed, so that their problems will not be attributed erroneously to authors of previous versions.
Some devices are designed to deny users access to install or run modified versions of the software inside them, although the manufacturer can do so. This is fundamentally incompatible with the aim of protecting user’s freedom to change the software. The systematic pattern of such abuse occurs in the area of products for individuals to use, which is precisely where it is most unacceptable. Therefore, we have designed this version of the GPL to prohibit the practice for those products. If such problems arise substantially in other domains, we stand ready to extend this provision to those domains in future versions of the GPL, as needed to protect the freedom of users.
Finally, every program is threatened constantly by software patents. States should not allow patents to restrict development and use of software on general-purpose computers, but in those that do, we wish to avoid the special danger that patents applied to a free program could make it effectively proprietary. To prevent this, the GPL assures that patents cannot be used to render the program non-free.
The precise terms and conditions for copying, distribution and modification follow.
0. Definitions. “This License” refers to version 3 of the GNU General Public License.
“Copyright” also means copyright-like laws that apply to other kinds of works, such as semiconductor masks.
“The Program” refers to any copyrightable work licensed under this License. Each licensee is addressed as “you”. “Licensees” and “recipients” may be individuals or organizations.
To “modify” a work means to copy from or adapt all or part of the work in a fashion requiring copyright permission, other than the making of an exact copy. The resulting work is called a “modified version” of the earlier work or a work “based on” the earlier work.
A “covered work” means either the unmodified Program or a work based on the Program.
To “propagate” a work means to do anything with it that, without permission, would make you directly or secondarily liable for infringement under applicable copyright law, except executing it on a computer or modifying a private copy. Propagation includes copying, distribution (with or without modification), making available to the public, and in some countries other activities as well.
To “convey” a work means any kind of propagation that enables other parties to make or receive copies. Mere interaction with a user through a computer network, with no transfer of a copy, is not conveying.
An interactive user interface displays “Appropriate Legal Notices” to the extent that it includes a convenient and prominently visible feature that (1) displays an appropriate copyright notice, and (2) tells the user that there is no warranty for the work (except to the extent that warranties are provided), that licensees may convey the work under this License, and how to view a copy of this License. If the interface presents a list of user commands or options, such as a menu, a prominent item in the list meets this criterion.
1. Source Code. The “source code” for a work means the preferred form of the work for making modifications to it. “Object code” means any non-source form of a work.
A “Standard Interface” means an interface that either is an official standard defined by a recognized standards body, or, in the case of interfaces specified for a particular programming language, one that is widely used among developers working in that language.
The “System Libraries” of an executable work include anything, other than the work as a whole, that (a) is included in the normal form of packaging a Major Component, but which is not part of that Major Component, and (b) serves only to enable use of the work with that Major Component, or to implement a Standard Interface for which an implementation is available to the public in source code form. A “Major Component”, in this context, means a major essential component (kernel, window system, and so on) of the specific operating system (if any) on which the executable work runs, or a compiler used to produce the work, or an object code interpreter used to run it.
The “Corresponding Source” for a work in object code form means all the source code needed to generate, install, and (for an executable work) run the object code and to modify the work, including scripts to control those activities. However, it does not include the work’s System Libraries, or general-purpose tools or generally available free programs which are used unmodified in performing those activities but which are not part of the work. For example, Corresponding Source includes interface definition files associated with source files for the work, and the source code for shared libraries and dynamically linked subprograms that the work is specifically designed to require, such as by intimate data communication or control flow between those subprograms and other parts of the work.
The Corresponding Source need not include anything that users can regenerate automatically from other parts of the Corresponding Source.
The Corresponding Source for a work in source code form is that same work.
2. Basic Permissions. All rights granted under this License are granted for the term of copyright on the Program, and are irrevocable provided the stated conditions are met. This License explicitly affirms your unlimited permission to run the unmodified Program. The output from running a covered work is covered by this License only if the output, given its content, constitutes a covered work. This License acknowledges your rights of fair use or other equivalent, as provided by copyright law.
You may make, run and propagate covered works that you do not convey, without conditions so long as your license otherwise remains in force. You may convey covered works to others for the sole purpose of having them make modifications exclusively for you, or provide you with facilities for running those works, provided that you comply with the terms of this License in conveying all material for which you do not control copyright. Those thus making or running the covered works for you must do so exclusively on your behalf, under your direction and control, on terms that prohibit them from making any copies of your copyrighted material outside their relationship with you.
Conveying under any other circumstances is permitted solely under the conditions stated below. Sub licensing is not allowed; section 10 makes it unnecessary.
3. Protecting User’s Legal Rights From Anti-Circumvention Law. No covered work shall be deemed part of an effective technological measure under any applicable law fulfilling obligations under article 11 of the WIPO copyright treaty adopted on 20 December 1996, or similar laws prohibiting or restricting circumvention of such measures.
When you convey a covered work, you waive any legal power to forbid circumvention of technological measures to the extent such circumvention is effected by exercising rights under this License with respect to the covered work, and you disclaim any intention to limit operation or modification of the work as a means of enforcing, against the work’s users, your or third parties legal rights to forbid circumvention of technological measures.
4. Conveying Verbatim Copies. You may convey verbatim copies of the Program’s source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice; keep intact all notices stating that this License and any non-permissive terms added in accord with section 7 apply to the code; keep intact all notices of the absence of any warranty; and give all recipients a copy of this License along with the Program.
You may charge any price or no price for each copy that you convey, and you may offer support or warranty protection for a fee.
5. Conveying Modified Source Versions. You may convey a work based on the Program, or the modifications to produce it from the Program, in the form of source code under the terms of section 4, provided that you also meet all of these conditions:
A compilation of a covered work with other separate and independent works, which are not by their nature extensions of the covered work, and which are not combined with it such as to form a larger program, in or on a volume of a storage or distribution medium, is called an “aggregate” if the compilation and its resulting copyright are not used to limit the access or legal rights of the compilation’s users beyond what the individual works permit. Inclusion of a covered work in an aggregate does not cause this License to apply to the other parts of the aggregate.
6. Conveying Non-Source Forms. You may convey a covered work in object code form under the terms of sections 4 and 5, provided that you also convey the machine-readable Corresponding Source under the terms of this License, in one of these ways:
A separable portion of the object code, whose source code is excluded from the Corresponding Source as a System Library, need not be included in conveying the object code work.
A “User Product” is either (1) a “consumer product”, which means any tangible personal property which is normally used for personal, family, or household purposes, or (2) anything designed or sold for incorporation into a dwelling. In determining whether a product is a consumer product, doubtful cases shall be resolved in favor of coverage. For a particular product received by a particular user, “normally used” refers to a typical or common use of that class of product, regardless of the status of the particular user or of the way in which the particular user actually uses, or expects or is expected to use, the product. A product is a consumer product regardless of whether the product has substantial commercial, industrial or non-consumer uses, unless such uses represent the only significant mode of use of the product.
“Installation Information” for a User Product means any methods, procedures, authorization keys, or other information required to install and execute modified versions of a covered work in that User Product from a modified version of its Corresponding Source. The information must suffice to ensure that the continued functioning of the modified object code is in no case prevented or interfered with solely because modification has been made.
If you convey an object code work under this section in, or with, or specifically for use in, a User Product, and the conveying occurs as part of a transaction in which the right of possession and use of the User Product is transferred to the recipient in perpetuity or for a fixed term (regardless of how the transaction is characterized), the Corresponding Source conveyed under this section must be accompanied by the Installation Information. But this requirement does not apply if neither you nor any third party retains the ability to install modified object code on the User Product (for example, the work has been installed in ROM).
The requirement to provide Installation Information does not include a requirement to continue to provide support service, warranty, or updates for a work that has been modified or installed by the recipient, or for the User Product in which it has been modified or installed. Access to a network may be denied when the modification itself materially and adversely affects the operation of the network or violates the rules and protocols for communication across the network.
Corresponding Source conveyed, and Installation Information provided, in accord with this section must be in a format that is publicly documented (and with an implementation available to the public in source code form), and must require no special password or key for unpacking, reading or copying.
7. Additional Terms. “Additional permissions” are terms that supplement the terms of this License by making exceptions from one or more of its conditions. Additional permissions that are applicable to the entire Program shall be treated as though they were included in this License, to the extent that they are valid under applicable law. If additional permissions apply only to part of the Program, that part may be used separately under those permissions, but the entire Program remains governed by this License without regard to the additional permissions.
When you convey a copy of a covered work, you may at your option remove any additional permissions from that copy, or from any part of it. (Additional permissions may be written to require their own removal in certain cases when you modify the work.) You may place additional permissions on material, added by you to a covered work, for which you have or can give appropriate copyright permission.
Notwithstanding any other provision of this License, for material you add to a covered work, you may (if authorized by the copyright holders of that material) supplement the terms of this License with terms:
All other non-permissive additional terms are considered “further restrictions” within the meaning of section 10. If the Program as you received it, or any part of it, contains a notice stating that it is governed by this License along with a term that is a further restriction, you may remove that term. If a license document contains a further restriction but permits re licensing or conveying under this License, you may add to a covered work material governed by the terms of that license document, provided that the further restriction does not survive such re licensing or conveying.
If you add terms to a covered work in accord with this section, you must place, in the relevant source files, a statement of the additional terms that apply to those files, or a notice indicating where to find the applicable terms.
Additional terms, permissive or non-permissive, may be stated in the form of a separately written license, or stated as exceptions; the above requirements apply either way.
8. Termination. You may not propagate or modify a covered work except as expressly provided under this License. Any attempt otherwise to propagate or modify it is void, and will automatically terminate your rights under this License (including any patent licenses granted under the third paragraph of section 11).
However, if you cease all violation of this License, then your license from a particular copyright holder is reinstated (a) provisionally, unless and until the copyright holder explicitly and finally terminates your license, and (b) permanently, if the copyright holder fails to notify you of the violation by some reasonable means prior to 60 days after the cessation.
Moreover, your license from a particular copyright holder is reinstated permanently if the copyright holder notifies you of the violation by some reasonable means, this is the first time you have received notice of violation of this License (for any work) from that copyright holder, and you cure the violation prior to 30 days after your receipt of the notice.
Termination of your rights under this section does not terminate the licenses of parties who have received copies or rights from you under this License. If your rights have been terminated and not permanently reinstated, you do not qualify to receive new licenses for the same material under section 10.
9. Acceptance Not Required for Having Copies. You are not required to accept this License in order to receive or run a copy of the Program. Ancillary propagation of a covered work occurring solely as a consequence of using peer-to-peer transmission to receive a copy likewise does not require acceptance. However, nothing other than this License grants you permission to propagate or modify any covered work. These actions infringe copyright if you do not accept this License. Therefore, by modifying or propagating a covered work, you indicate your acceptance of this License to do so.
10. Automatic Licensing of Downstream Recipients. Each time you convey a covered work, the recipient automatically receives a license from the original licensors, to run, modify and propagate that work, subject to this License. You are not responsible for enforcing compliance by third parties with this License.
An “entity transaction” is a transaction transferring control of an organization, or substantially all assets of one, or subdividing an organization, or merging organizations. If propagation of a covered work results from an entity transaction, each party to that transaction who receives a copy of the work also receives whatever licenses to the work the party’s predecessor in interest had or could give under the previous paragraph, plus a right to possession of the Corresponding Source of the work from the predecessor in interest, if the predecessor has it or can get it with reasonable efforts.
You may not impose any further restrictions on the exercise of the rights granted or affirmed under this License. For example, you may not impose a license fee, royalty, or other charge for exercise of rights granted under this License, and you may not initiate litigation (including a cross-claim or counterclaim in a lawsuit) alleging that any patent claim is infringed by making, using, selling, offering for sale, or importing the Program or any portion of it.
11. Patents. A “contributor” is a copyright holder who authorizes use under this License of the Program or a work on which the Program is based. The work thus licensed is called the contributor’s “contributor version”.
A contributor’s “essential patent claims” are all patent claims owned or controlled by the contributor, whether already acquired or hereafter acquired, that would be infringed by some manner, permitted by this License, of making, using, or selling its contributor version, but do not include claims that would be infringed only as a consequence of further modification of the contributor version. For purposes of this definition, “control” includes the right to grant patent sub licenses in a manner consistent with the requirements of this License.
Each contributor grants you a non-exclusive, worldwide, royalty-free patent license under the contributor’s essential patent claims, to make, use, sell, offer for sale, import and otherwise run, modify and propagate the contents of its contributor version.
In the following three paragraphs, a “patent license” is any express agreement or commitment, however denominated, not to enforce a patent (such as an express permission to practice a patent or covenant not to sue for patent infringement). To “grant” such a patent license to a party means to make such an agreement or commitment not to enforce a patent against the party.
If you convey a covered work, knowingly relying on a patent license, and the Corresponding Source of the work is not available for anyone to copy, free of charge and under the terms of this License, through a publicly available network server or other readily accessible means, then you must either (1) cause the Corresponding Source to be so available, or (2) arrange to deprive yourself of the benefit of the patent license for this particular work, or (3) arrange, in a manner consistent with the requirements of this License, to extend the patent license to downstream recipients. “Knowingly relying” means you have actual knowledge that, but for the patent license, your conveying the covered work in a country, or your recipient’s use of the covered work in a country, would infringe one or more identifiable patents in that country that you have reason to believe are valid.
If, pursuant to or in connection with a single transaction or arrangement, you convey, or propagate by procuring conveyance of, a covered work, and grant a patent license to some of the parties receiving the covered work authorizing them to use, propagate, modify or convey a specific copy of the covered work, then the patent license you grant is automatically extended to all recipients of the covered work and works based on it.
A patent license is “discriminatory” if it does not include within the scope of its coverage, prohibits the exercise of, or is conditioned on the non-exercise of one or more of the rights that are specifically granted under this License. You may not convey a covered work if you are a party to an arrangement with a third party that is in the business of distributing software, under which you make payment to the third party based on the extent of your activity of conveying the work, and under which the third party grants, to any of the parties who would receive the covered work from you, a discriminatory patent license (a) in connection with copies of the covered work conveyed by you (or copies made from those copies), or (b) primarily for and in connection with specific products or compilations that contain the covered work, unless you entered into that arrangement, or that patent license was granted, prior to 28 March 2007.
Nothing in this License shall be construed as excluding or limiting any implied license or other defenses to infringement that may otherwise be available to you under applicable patent law.
12. No Surrender of Others Freedom. If conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License. If you cannot convey a covered work so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not convey it at all. For example, if you agree to terms that obligate you to collect a royalty for further conveying from those to whom you convey the Program, the only way you could satisfy both those terms and this License would be to refrain entirely from conveying the Program.
13. Use with the GNU Affero General Public License. Notwithstanding any other provision of this License, you have permission to link or combine any covered work with a work licensed under version 3 of the GNU Affero General Public License into a single combined work, and to convey the resulting work. The terms of this License will continue to apply to the part which is the covered work, but the special requirements of the GNU Affero General Public License, section 13, concerning interaction through a network will apply to the combination as such.
14. Revised Versions of this License. The Free Software Foundation may publish revised and/or new versions of the GNU General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns.
Each version is given a distinguishing version number. If the Program specifies that a certain numbered version of the GNU General Public License “or any later version” applies to it, you have the option of following the terms and conditions either of that numbered version or of any later version published by the Free Software Foundation. If the Program does not specify a version number of the GNU General Public License, you may choose any version ever published by the Free Software Foundation.
If the Program specifies that a proxy can decide which future versions of the GNU General Public License can be used, that proxy’s public statement of acceptance of a version permanently authorizes you to choose that version for the Program.
Later license versions may give you additional or different permissions. However, no additional obligations are imposed on any author or copyright holder as a result of your choosing to follow a later version.
15. Disclaimer of Warranty. THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
16. Limitation of Liability. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
17. Interpretation of Sections 15 and 16. If the disclaimer of warranty and limitation of liability provided above cannot be given local legal effect according to their terms, reviewing courts shall apply local law that most closely approximates an absolute waiver of all civil liability in connection with the Program, unless a warranty or assumption of liability accompanies a copy of the Program in return for a fee.
END OF TERMS AND CONDITIONS
Current information about VSCP (Very Simple Control Protocol) can be found at:
http://www.vscp.org http://sourceforge.net/projects/m2m
There is three mailing lists available on Sourceforge that is about CANAL, VSCP and OHAS topics.
Many of the thoughts behind this protocol come from work done by Ake Hedman as early as 1986 but the high node costs at the time made it impossible to do the things VSCP can do today. The official start date/time is 2000-08-28 14:07 CET when the EDA project (http://sourceforge.net/projects/eda) was registered at Sourceforge. EDA, is an acronym for Event-Decision-Action and is still preserved in the decision matrix of VSCP.
VCSP is designed to be used where other solutions are to expensive to implement. This can typically be in code overhead where most other protocols use more resources (flash/ram) on a micro-controller than the actual “application” adding a lot of cost to the project. VSCP can work with a typical lowest cost dumb nodes like the Microchip MCP250xx series, to a 1K-2K flash micro controller module up to a full implementation with all features in about 5K flash. VSCP is both free and open. Everyone can join the project and help to add features and functionality to the protocol. There is free firmware and driver code available for most micro-controllers which uses many communication techniques. Everyone is free to use this code and there is not requirement to share any new code you develop, although most choose to, in order to improve the code base.
Most people don’t remember the world looked like for PC developers before Windows where introduced. This was a time when the developer needed to ship a big bunch of floppy disks with his/here’s application. One big pile of floppies where for different printers. Another set of disk was for different graphical cards and yet another for different pointing devices etc. It was not uncommon to have one floppy for the application an fifteen to twenty for drivers.
Windows changed this. The OS introduced abstraction for devices and from that point drivers was something the OS dealt with and the application developer could concentrate on creating the application. This was the big reason behind the boom in software that made Microsoft and others successful.
VSCP does this for automation tasks. Look around and see how it looks today. We have applications that work for Zigbee, X10, KNX, LonWorks etc. Some try to combine them into one application like MrHouse and the like but still it’s a different thing to turn on a lamp using Zigbee, X10, KNX or whatever. In the best case the same user interface component can be used but still there is a need to differentiate between the technologies use also at that level and most important the knowledge about the technology is needed on the top level.
VSCP try to hide this. Drivers implement the interface to the technology and
they all talk to the system using the VSCP protocol and understand VSCP
protocol events. Compare this with printing under a modern OS. It’s no
difference today if you print to a Laser printer or a ink jet printer. Also it all
works the same if the printer use protocol x, y or z. You are also still able to
configure and print with the printers. This is where the abstraction comes into
place.
To switch on a lamp (or a group of lamps) in VSCP we send a
A driver translate this event to it’s own format and does its specific work using it’s own protocol and return a
when it’s job is done as a confirmation for the rest of the system.
An application does not need to bother how the actual control is done. On the application level it’s enough to implement a button and some visual indication to indicate the outcome of the operation.
A system to present some measurement data is another example. Think of a system with temperature sensors. They all use different technologies but a driver for each translate the temperature readings to a common
This event is region independent and format independent. It is easy to create a driver that log this value into a database. Also here in a common format. You can now build a web applet that shows the temperature for every possible temperature sensor. As the format is common and easy to collect in a database in a common way you can also write a statistical application that show temperature data and work for any temperature sensor.
The above is the most important reason for VSCP but there is more.
Each VSCP device have a common way it can be configured by. This means one high level software can be used for all devices. Note that a device necessarily does not need to implement this. Instead a driver can do that and make it look like a VSCP device. Typically is a 1-wire sensor where the driver can implement the parameters for it and export it in a common way.
All VSCP devices is described in a common way. The device itself holds this information and therefore when a device is found all information about how it is configured and used is available. Again this information can be implemented in the driver.
VSCP defines a lot more functionality and can be used all the way out to the actual device. Still the most important part is the abstraction.
VSCP is an event based system. Nodes generate events and nodes react on events. Normally events are not addressed but instead are broadcast on the bus. Its up to the receiving end to decide if its interested in the event or not. All events have an originating address for the node they are sent from. This is a GUID consisting of 16 bytes but a shorter, typically, one byte nickname id is used on most system. It is always possible to deduce the full GUID from the nickname. Events are divided into groups. First there is Level I and Level II events. Level I events are limited to a maximum of eight bytes of data while Level II events can have up to 488 bytes of data. The low maximum data count for Level I comes from that CAN has been used as the least common denominator. This does not limit VSCP Level I to be used only over CAN. Both Level I and Level II events are divided into a class and a type. The class defines a group of events of a specific type. Typical examples are classes for measurements, information and control. As mentioned above events are not addressed. This is not entirely true as one class in each level (CLASS1.PROTOCOL and CLASS2.PROTOCOL) have events that are addressed. These classes defines protocol functionality that all nodes must implement. Typical examples found here is event types for boot loader, register access and status information. Most of the events can use a zone/subzone to identify the group of nodes it is relevant to.
Each node has a specified number of byte wide registers defined. This is the second interface to the black box the node represents. The register space of a node is 256 bytes divided in two halves. The lower part (0x00-0x7f) is application specific. The upper part content is mandatory and specified by VSCP. This space hold, among many other things, the firmware and hardware version of the node. The GUID, user module id, alarm status and similar registers.. In the top of the mandatory register space is a 32 byte string stored, the MDF, which contains an URL that points to a location where to find an XML file that describe this module its registers and its functionality. The lower part of the register space is used to define control and status registers and more complex structures. The area is mapped and 65535 pages can be used if needed allowing for very complex scenarios if needed.
The MDF file describe the module at a high level. It provides information about the manufacturer of the module, the events that can be expected from it and the definition of its register content. The MDF looks at the module from a high level perspective and can see floating point values, bit arrays, option tables in register space and thus give application software a way to present registers in a much more user friendly way. There is two way to obtain the MDF after getting it from the module by reading the registers holding it . As VSCP is designed for low end nodes it is normally to much for such a node to have the MDF stored internally. In this case the string points to a web server from which the XML can be downloaded and processed. In a more capable module with more resources the MDF is stored internally in which case the read string has zero length and in this case the MDF data can be fetched from the module itself. The node constructor decide which method he/she wants to use. The MDF also point out where drivers for different environments and systems for the module and user manuals etc can be found. Decision Matrix
All nodes can optionally implement a decision matrix. This matrix is used to define one or a group of events that should trigger a predefined functionality at the module. In VSCP this is called the Event-Decision-Action mechanism from the predecessor of the project which was called EDA. A typical examples can be to trigger a relay. The module got one action that set the relay and another action that reset it. Typically this could be implemented hard coded so that the relay would be set when an ON-event was received and reset ed when an OFF-event was received. With the use of the DM it is easy to use any event to trigger the action not just the ON/OFF events. Physically the DM is located in register space just as any other parameters of the module so register access functions are used to changed it.
Measurements A special class is used for measurements and events for all SI units and derived units is defined. The class will grow over time when new types are needed. This means that for example a temperature measurement is normally sent as a Kelvin temperature. Celsius and Fahrenheit is also possible in this case and similar alternatives is available for other types but the SI unit is always the default. How the measurement is presented in the frame is also well specified. Bit field, string, integer, normalized integer (decimal) and floating point values are possible. The normalized integer is especially well suited for a low end system to send decimal data. As the event and its content is well specified it is very easy to interpret the data on the receiving end where it should be processed, stored in a database, logged or displayed.
As VSCP is event based, one often need to think a bit differently when constructing a system. A typical example is a tank with a level sensor and a pump which together construct a self contained system. A traditional system system would have used a master to control the pump and the sensor. In VSCP we allow for this also but try to distribute as much of the intelligence as possible to the nodes themselves. So what we do is to tell the level sensor to send level information with a predefined interval. Several sensors can be added for redundancy. We tell the pump that it should start to fill up the tank when the tank reach a low level and stop at a high level. This might be dangerous as the sensor may stop working, the cable get cut or whatever. In this case the we also program the pump goes to its safe state == pump off and alarming this state to the rest of the system when it does not receive sensor measurements any more.. This “safe state“ is often possible to find for most control situations. As the transport mechanism is unknown to the application, timing must be very lose for VSCP. We cannot be certain when an event arrives or if it arrives. Many transport mechanisms, such as CAN and TCP/IP, makes delivery more certain while other solutions like UDP, RF and PLC can be problematic. It is therefore very important that a sent event always get a confirmation event back. For some nodes this might not be important. A temperature node or the level sensor node above just send there measurements and don’t care if someone uses them or not. This thinking is central. The node that originate an event should – if possible - know as little as possible about how the event it sends out will be used. This make the system very flexible.
A software package called VSCP & Friends is available to support VSCP users. This package can be downloaded and used for free and contain a lot of application and code. Everything is available both for Windows and Linux based systems.
First and possibly most important it contain the VSCP daemon. This is a server software that makes it possible to control several VSCP segments over the Internet.
The server expose a secure Internet interface and makes it possible to add drivers for segments of nodes or special equipment. A driver can communicate with the server using the CANAL interface for a Level I driver and the TCP/IP interface for a Level II driver.
CANAL stands for CAN Abstraction Layer and was initially developed as a software layer between application software and CAN equipment. For the VSCP it is not limited to interface CAN equipment but CAN drivers for most CAN adapters such as PEAK, IXXAT, PORT etc is included in the package as many CAN users use the system.
A lot of code is available that confirms to the CANAL interface. This same code can be used to communicate directly to a device that use the CANAL driver as can be used to talk to the daemon. This makes, among many other advantages, it easy to build simulated systems that use the same code base as the resulting system.
The daemon can do a lot more such as remotely replace/install drivers, remotely handle users and permissions, set up and handle an internal decision matrix to set up a self contained control system etc.
VSCP Works is a client application that is included in the package. This application can be used to send/receive VSCP events to/from every segment/device that export a CANAL interface and also talk to a remote VSCP daemon. VSCP Works can be used to investigate register space on any VSCP node and will also have support for remote firmware upgrade.
Server and client application is released under the GPL license. Libraries and classes is released under a modified LGPL license that make sure they can be used in proprietary projects.
Maybe the most important aspect of the VSCP & Friends package is that it can be used as an abstraction for interfacing other technologies and protocols. One just need to build a driver that translate the systems functionality to/from VSCP events and then install this driver for the VSCP daemon and then remote control functionality, software interface etc is directly available. This way one application interface can be constructed to control several technologies using different protocols. One can compare this to the situation for printers before windows was announced. Each application needed to distribute a stack of disks with printer drivers. Windows ended this by introducing the printer API abstraction for printers. VSCP & Friends does the same for SECO (SEensor/COntrol) devices .
A web interface named OHAS is under development that will make it possible to build dynamic control interfaces with drag and drop technology.
VSCP makes it easy and very cost effective to build systems with distributed intelligence. The protocol is placed in the Public Domain so it is therefore free for anyone to use and modify to their own needs. VSCP can be used all the way from the application down to the device but it can also be used as an abstraction to other technologies so one application can be written that transparently use several different technologies..
More information and downloads is available at HTTP://www.vscp.org
When the protocol was designed it’s usefulness on the CAN bus was the main objective. The identifier length and many other things on Level I are therefore very “CAN-ish” in its design and behavior. CAN is however no prerequisite. The protocol works equally well over RS-232, RF-Links, Ethernet etc.
Level I is effective over bandwidth limited links but don’t have the full GUID of the nodes in the frames and some sort of lower level addressing system must be used.
The maximum number of nodes VSCP can handle is 254. In practice, the number of nodes that can be connected to a CAN bus depends on the minimum load resistance a transceiver is able to drive. This is typically around 120 depending on all the transceivers and media (cables) used.
The transmission speed (or nominal bit rate) is set by default at 125 kilobits per second. All nodes should support this speed but lower bit rates can be used too. See chapter about using alternative bit rates below]].
The maximum length of the cabling in a segment is typically 500 meters using AWG24 or similar (CAT5) and a nominal bit rate of 125kbps. Drops with a maximum length of 24M can be taken from this cable and the sum of all drops must not exceed a total of 120 meters counted together.
| Bit Rate | Max Bus Length (m) | Max Drop Length (m) | Max Cumulative Drop Length (m) |
| 1Mbps | 25 | 2 | 10 |
| 800 Kbps | 50 | 3 | 15 |
| 500 Kbps | 100 | 6 | 30 |
| 250 Kbps | 250 | 12 | 60 |
| 120 Kbps | 500 | 24 | 120 |
| 50 Kbps | 1000 | 60 | 300 |
| 20 Kbps | 2500 | 150 | 750 |
| 10 Kbps | 5000 | 300 | 1500 |
CAN bit rate data
The cable should be terminated at both ends with 120 ohms resistors.
VSCP requires Extended Data Frames with a 29-bit identifier.
The protocol is compatible with elementary CAN nodes such as the Microchip MCP2502x/5x I/O CAN expander.
Just as for CANopen and DeviceNet, the sample point should be set at 87.5%.
| Bit | Use | Comment |
| 28 | Priority | Highest priority is 000b (=0) and lowest is 111b (=7) |
| 27 | Priority |
|
| 26 | Priority |
|
| 25 | Hard-coded | If this bit is set the Nickname ID of the device is hard-coded |
| 24 | Class | The class identifies the event class. There are 512 possible classes. This is the MSB bit of the class. |
| 23 | Class |
|
| 22 | Class | |
| 21 | Class |
|
| 20 | Class | |
| 19 | Class |
|
| 18 | Class | |
| 17 | Class |
|
| 16 | Class | |
| 15 | Type | The type identifies the type of the event within the set event class. There are 256 possible types within a class. This is the MSB bit of the type. |
| 14 | Type |
|
| 13 | Type |
|
| 12 | Type |
|
| 11 | Type |
|
| 10 | Type |
|
| 9 | Type |
|
| 8 | Type |
|
| 7 | Originating-Address | The address is a unique address in the system. It can be a hard-set address or (hard-coded bit set) or an address retrieved through the nickname discovery process. 0×00 is reserved for a segment master node. 0xff is reserved for no assigned nickname. |
| 6 | Originating-Address |
|
| 5 | Originating-Address |
|
| 4 | Originating-Address |
|
| 3 | Originating-Address |
|
| 2 | Originating-Address |
|
| 1 | Originating-Address |
|
| 0 | Originating-Address |
|
Format of the 29 bit CAN identifier in VSCP
If addressing of a particular node is needed the nickname address for the node is given as the first byte in the data part. This is a rare situation for VSCP and is mostly used in the register read/write events.
| Pin RJ45,RJ12,RJ11,RJ10 | Use | RJ-11 | RJ-12 | RJ-45 | Patch Cable wire color T568B |
| 1 | +9-28V DC | RJ-45 | Orange/White |
||
| 2 1 | +9-28V DC | RJ-12 | RJ-45 | Orange |
|
| 3 2 1 | +9-28V DC | RJ-11 | RJ-12 | RJ-45 | Green/White |
| 4 3 2 | CANH | RJ-11 | RJ-12 | RJ-45 | Blue |
| 5 4 3 | CANL | RJ-11 | RJ-12 | RJ-45 | Blue/White |
| 6 5 4 | GND | RJ-11 | RJ-12 | RJ-45 | Green |
| 7 6 | GND | RJ-12 | RJ-45 | Brown/White |
|
| 8 | GND | RJ-45 | Brown | ||
RJ-11/12/45 pin-out
.
RJ-45 pin out
Note that the schematics drawings for VSCP modules use a symbol that is numbered looking from the PCB side. It thus appear as to be numbered in the other direction but is actually the same.
Note also that CANopen specify a different schema http://www.cd-systems.com/Can/can-cables.htm which is opposite numbered VSCP but they are actually the same. We use the numbering that look into the female connector and count from the left. They use the Arabic style and count from the right.
Aways try to use a pair of wires for CANH/CANL fort best noise immunity. If the EIA/TIA 56B standard is used this condition will be satisfied. This is good as most Ethernet networks already is wired this way.
Don’t! The bit-rate should be fixed at 125kbps.
✦Preliminary Information. May change in future specifications.
A byte stuffing binary interface is used to talk to the module through the serial
interface.
The protocol is created for VSCP Level I events but can be used for other purposes also, as the 16 byte data content indicates. In this case the class and type bytes can be used freely by the implementor.
The check-sum is calculated from, and including, flags up to the last data-byte.
The channel byte can be used to logically separate different channels on the same physical line. Typically this can also be a serial line with many nodes which are polled for data.
The sequence number byte marks a number for a sequence of a special frame. For instance four frame are sent after each other and they will get different counter numbers. The NACK/ACKS that are responded from the node use the same counter values to separate the frames from others. Can, for example, be used to implement a sliding window protocol.
As noted there can be two types of ACK’s/NACK’s one (251/252) is a general ACK/NACK that is the response when a frame is received and put in a buffer. This is generally all that is needed. The other version (249/250) can optionally be sent when the frame is actually sent on the interface.
Byte 3 - Flags + bit nine of class
There can be 0 to 16 argument bytes.
When a command is sent their should always be a response. This response could be an ACK/NACK/Response/Error frame so all types should be expected.
Optional command Data byte(s) 0-15
There can be 0 to 16 argument bytes.
Optional error data byte(s) 0-15
There can be 0 to 16 argument bytes.
Optional error data byte(s) 0-15
Used as a positive response.
Used as a negative response.
The DLE character is sent as [DLE][DLE]
For generic CAN frames the operation byte is set to 5 The first four data-bytes form
the CAN ID.
The four last data-bytes can be a time-stamp (big endian).
Command codes and data format is decided by the implementor.
Response codes and data format is decided by the implementor.
Error codes and data format is decided by the implementor.
This is a description of a low level protocol for RS-485. The protocol is a server based protocol and is low speed but very cheap to implement. At a very low additional cost a CAN network with full VSCP functionality and server less functionality can be constructed and this is recommended for the majority of systems.
Addressing is done with nine bit addressing. Address 0 is reserved for the server and the rest of the addresses are free to use for clients. Addresses are hard-coded within devices and each device should have its own unique address.
If a node has a event to send it sends it directly after the poll event. The node should respond within one maximum packet time (14 * 8 * 104uS = 10 ms. Note that the event may be addressed to another node on the segment not only to the host.
If the node has no events to send it can either not reply to the poll or reply with “No Events to send” which is the preferable way.
The events is standard VSCP Level I events in every other aspect.
A master on a 485 segment must check for new nodes on regular intervals. With 127 possible nodes this process could take 1.3 seconds to perform. Instead of doing all this at once it may be better to spread it over the standard polling range. That is to do a full polling of all active nodes and then try to discover a new node on an unused address etc etc.
Packet CRC (counted from address (low 8-bits of it).
VSCP can use Ethernet directly making it possible to construct very low end nodes. There is no need for nickname shemas etc as a VSCP GUID can be constructed from an Ethernet MAC. The payload is a standard VSCP level II frame with some specific Ethernet stuff in it
| Content | Size | Description |
| Preamble | 62 bits | Standard Ethernet preamble. (Part of Ethernet) |
| SOF (Start of Frame) | 2 bits | Standard Ethernet SOF. (Part of Ethernet) |
| Destination MAC address | 6 bytes | Always set to FF:FF:FF:FF:FF:FF (Part of Ethernet) |
| Source MAC address | 6 bytes | Source address. Part of GUID see information below. (Part of Ethernet) |
| Ethernet Type | 2 bytes | Frame type: Always set to 0x257e (decimal 9598) (Part of Ethernet) |
| Version | 1 byte | Currently zero for this version. May change in the future. |
| VSCP head | 4 bytes | Header |
| VSCP sub source address | 2 bytes | Identifies one subunit of an ethernet device. Last two bytes of the GUID. |
| Timestamp | 4 bytes | Timestamp in microseconds. Module relative value. |
| obid | 4 bytes | For use by modules and drivers. |
| VSCP class | 2 bytes | 16-bit VSCP class |
| VSCP type | 2 bytes | 16-bit VSCP type |
| DataSize | 2 bytes | Size of datapart. Needed because Ethernet frames with have a minimum length of 64 bytes. |
| Payload | 0- 487 bytes | The VSCP data part. As usual 512-25 bytes. |
| CRC | 4-bytes | 32 bit CRC check-sum (Part of Ethernet) |
The VSCP GUID for Ethernet is defined as
FF FF FF FF FF FF FF FE YY YY YY YY YY YY XX XX
where FF FF FF FF FF FF FF FE say this is an Ethernet GUID and YY YY YY YY YY YY is the MAC address and XX XX is the id for a specific VSCP device. Each node can thus appear as 65535 - 2 nodes which is perfect for a gateway or similar device that have VSCP devices connected on one or many other buses such as CAN, RF and the like. Two id’s is reserved. 0 which is the Ethernet node itself and 0xffff which is all nodes on the interface. If a node consist just of itself then it can ignore the VSCP sub address but it is recommended that it use 0×0000 for it’s transmitted frames.
The header (32-bits) is defined as follows
| CONTENT | SIZE | DESCRIPTION |
| Priority (Bit 31,30,29) | 3 bits | Standard VSCP priority. |
| Cryptographic algorithm (Bit 28, 27, 26, 25) | 4 bits | Cryptographic algorithm. |
| Reserved | 25 bits | |
Cryptographic encoding is done after type up to and including the last databyte thus the VSCP head is never encoded.
The unused pairs can be used to power nodes and that way making them lower cost. In a perfect world a standard compliant Power over Ethernet schema could have been used. Regrettably the technique is to expensive. At least at the moment. Instead a +9-48V DC injector is used. If in dought use +48V DC. The IEEE 802.3af standard POE pinout is as follows:
| Pin | Description |
| 1 | |
| 2 | |
| 3 | |
| 4 | +9V - +48V |
| 5 | +9V - +48V |
| 6 | |
| 7 | GND |
| 8 | GND |
Maximum power usage depends on the cabling but for AWG-24 it is 0.5A for each pair but never more then 13 watts. There is a description of how different manufacturers implement this here http://pinouts.ru/Net/poe_pinout.shtml. A calculator for losses can be found here Power calculator.
VSCP level II is designed for TCP/IP and other high-end network transport mechanisms that are able to handle a lot of data. With all the additional bandwidth available it is ideal to always have a full addresses in packets for this type of media. That means that the address part in the header which is 8-bits for Level I is instead 129 bits for Level II. That is the full GUID is available in the frame.
There are two different versions of VSCP over TCP/IP. One UDP version which is broad-casted on a segment and the other which is more secure and use the TCP low level protocol.
Default Port: 95981
Byte 5 - ORIGINATING ADDRESS MSB
Byte 20 - ORIGINATING ADDRESS LSB
... data ... limited to max 512-25 = 487 bytes
Byte len -2 - CRC MSB (Calculated on HEAD + CLASS + TYPE + ADDRESS + SIZE + DATA…)
Byte len -1 - CRC LSB The number above is the offset in the package. Len is the total datagram size.
Note also that the MSB is sent before the LSB (network byte order, Big Endian). So, for little endian machines such as a typical PC the byte order needs to be reversed for multi. byte types.
There is a 24-byte overhead to send one byte of data so this is not a protocol which should be used where an efficient protocol for data intensive applications is required and where data is sent in small packets.
The CRC used is the 16-bit CCITT type and it should be calculated across all bytes except for the CRC itself.
As indicated, the Class is 16-bits allowing for 65535 classes. Class 0000000x xxxxxxxx is reserved for the Level I classes. A low-end device should ignore all packages with a class > 511.
A packet traveling from a Level I device out to the Level II world should have an address translation done by the master so that a full address will be visible on the level II segment. A packet traveling from a Level II segment to a Level I segment must have a class with a value that is less then 512 in order for it to be recognized. If it has it is aimed for the Level I segment. Classes 512-1023 are reserved for packets that should stay in the Level II segment but in all other aspects (the lower nine bits + type) are defined in the same manner as for the low-end net.
The Level II register abstraction level also has more registers (32-bit address is used) and all registers are 32–bits wide. Registers 0-255 are byte wide and are the same as for level 1. If these registers are read at level 2 they still is read as 32-bit but have the unused bits set to zero.
The VSCP TCP interface is a telnet type interface.
✦Preliminary Information. May change in future specifications.
MiWi is Microchips solution to get a simpler protocol then Zigbee according to IEEE 802.15.4. MiWi documents can be found here. Special requirements for VSCP over MiWi
There are no special requirements other then that nodes on a MiWi net should preferably implement CLASS1.PROTOCOL, Type=40 and CLASS1.PROTOCOL, Type=41 to loosen the burden of the PAN coordinator to resend all events to all node. For example a temperature node is normally not interested in anything else then CLASS1.PROTOCOL and it is a waste of bandwidth to send other events to it if the PAN know it just will through them away.
The PAN must have buffers and intelligence to be able to handle event filtering for all connected nodes. A standard node however does not need to have this extra burden.
There is no requirement for a node other then the PAN and coordinators to be active all the time. However all nodes must at least send a one minute heartbeat. CLASS1.INFORMATION, Type=9. After a node sent an heartbeat the node should be awake for a minimum of five seconds (:!: Time value may change) and receive any collected events intended for it.
Just as most other VSCP devices, VSCP MiWi devices need a n initialization sequence. In this case the intention of the sequence is to hook together a node and a PAN. This is typically done by activating a discover mode on the PAN and then press a button on the node that should be connected to this PAN.
The 802.15.4 payload is max 122 bytes. This payload can carry one or more VSCP events. The first byte tell how many events there is in the frame.
| Byte | Description | |||||||||||||||||||||
| 0 | Number of VSCP events in frame (1-x) | |||||||||||||||||||||
| 1 | head:
|
|||||||||||||||||||||
| 2 | class | |||||||||||||||||||||
| 3 | type | |||||||||||||||||||||
| 4 | Start of data. Max eight byte. Min 0 | |||||||||||||||||||||
| 4 + data-count + 1 | head for next event if any | |||||||||||||||||||||
On each segment there can be two kind of nodes. Dynamic and hard-coded.
Dynamic nodes are VSCP nodes that confirm fully to the Level I part of this document. This means they have
Sample implementations are available at http://www.vscp.org
VSCP hard-coded nodes have a nickname that is set in hardware and cant be changed.
Very simple hard coded nodes can therefore be implemented. A node that sends out an event at certain times is typical and a button node that sends out an on-event when the button is pressed is another example.
All nodes in a VSCP network segment need a way to get their nicknames ID’s, this is called the nickname discovery process.
A VSCP Level 1 segment can have a maximum of 254 nodes + an additional 254 possible hard coded nodes. A segment can have a master that handles address or nickname assignment but this is not a requirement.
After a node has got its nickname id it should save this id in permanent non-volatile storage and use it until it is told to stop using it. Even if a node forgets its nickname a segment controller must have a method to reassign the id to the node. The master needs to store the nodes full address to accomplish this.
In a segment where a new node is added the following scenario is used.
Step 1 The process starts by pressing a button or similar on the node. If the node has a nickname assigned to it, it forgets this nickname and enters the initialization state. Uninitiated nodes use the reserved node id 0xff.
Step 2 The node sends a probe event (CLASS1.PROTOCOL, TYPE=2,??) to address 0 (the address reserved for the master of a segment) using 0xff as its own address. The priority of this event is set to 0×07. The master (if available) now has a chance to assign a nickname to the node ((CLASS1.PROTOCOL, TYPE=2, ??). Five seconds may be a good interval for which this assignment should happen.
If no nickname assignment occurs the node checks the other possible nicknames (1-254) in turn. The node listens for a response event, probe ACK (CLASS1.PROTOCOL, TYPE=2, ??), from a node (which may already have the nickname assigned) for five seconds before concluding that the id is free and then uses the id as its own nickname id. On slower medium increase this timeout at will.
It is recommended that some visual indication is shown to indicate success. A blinking green led that turns steady green after a node has got its nickname is the recommended indication. If there is a response for all addresses a failure condition is set (segment full) and the node goes to sleep.
On an insecure medium such as RF (good practice also for CAN) it is recommended that the Probe is sent several time in a row to make sure that the nickname actually is free. This is actually a good method on all low level protocols and at least three tests are recommended.
Step 3 After it assigns a nickname to itself the node sends Nickname id accepted using its new nickname id to inform the segment of its identity.
Step 4 It’s now possible for other nodes to check the capabilities of this new node using read etc commands.
Only one node at the time can go through the initialization process. The following picture shows the nickname discovery process for a newly added node on a segment
Before an installation in a big system it is better to preassigned id’s to the nodes. This is just done by connecting each of the nodes to a PC or similar and assigning id’s to each of them, one at the time. After that they can be installed at there location and will use this id for the rest if there life or until told otherwise.
Things are a little different for hard coded nodes.
If a hard coded node has its address set in hardware it starts working on the segment immediately.
If the nickname discovery method is implemented it goes through the same steps (1-3) as the dynamic node. In this case all hard coded nodes on the segment must recognize and react on the probe-event.
The hard coded bit should always be set for a hard coded node regardless if the nickname discovery method is implemented or not.
Sometimes it can be an advantage to build modules that start up as silent nodes. This is typical for a RS-485 or similar segment. This type of nodes only listen to traffic before they get initialized by a host. In this case the nickname discovery process is not started for a node when it is powered up for the first time. This type on node instead starts to listen for the CLASS1.PROTOCOL, Type=23 (GUID Drop nickname id / Reset Device.) event. When this series of events is received and the GUID is the same as for the module the module starts the nickname discovery procedure as of above.
Using this method it is thus possible, for example, to let a user enter the GUID of a module and let some software search and initialize the node. As only the last four bytes of the GUID are unknown if the manufacturer GUID is known this is easy to enter for a user with the addition of a list box for the manufacturer.
The active nickname process is still a better choice as it allows for automatic node discovery without user intervention and should always be the first choice.
This is an example on the way it works
You have two nodes and assign unique id’s from there serial numbers
Combined with your GUID this will be
When you start up your nodes they see they don’t have assigned nickname id (= 0xff) so they just sit back and listen.
When your PC app want to initialize the new nodes it sends
At this stage your node knows it should enter the initialization phase and it will try to discover a new nickname using 0xff as its nickname.
This will be several CLASS.PROTOCOL Type 2 staring with 0 (server) as the probe id and increasing the probe id as long as CLASS.PROTOCOL Type 3 is received (i.e other nodes say they use that id).
If this is the first node on the bus it will claim nickname id = 1. This id should (normally( be stored in EEPROM and will be used without the sequence above next time the node is started.
The PC now continue with the other node sending
and this node will start its initialization procedure and find a free id.
Note that this process is only done the first time you put a fresh new node on a bus. Next time the id the node finds will be used directly from the time the node starts up.
If you always have a PC present let it send CLASS1.PROTOCOL, Type 6 to the uninitialized node when the node send the probe to the server (.CLASS.PROTOCOL Type 2 with probe id=0xff and origin 0xff)
A typical scenario for a segment without a Master can be a big room where there are several switches to turn a light on or off. During the installation the switches are installed and initialized.
When each switch is initialized it checks the segment for a free nickname and grabs it and stores it in local nonvolatile memory. By being connected to the segment the installer makes note of the id’s. It is of course also possible to set the nicknames to some desired value instead.
Additionally, VSCP aware relays are installed and also initialized to handle the actual switching of lighting. Again each in turn are initialized and the segment unique nickname noted.
At this stage the switches and the relay nodes have no connection with each other. One can press any switch and an on-event is sent on the segment but the relays don’t know how to react on it.
We do this by entering some elements in the decision matrix of the relay nodes.
etc and the same for off-event
As the decision matrix also is stored in the nodes non volatile storage, the system is now coupled together in this way until changed sometime in the future.
To have switches in this way that send on and off events is not so smart when you have a visible indication (lights go on or off) and it would have been much better to let the switches send only an on-event and let the relay-node decide what to do. In this case the decision matrix would look:
But how about a situation when we need a visual indication on the switch for instance? This can be typical when we turn a boiler or something like that off. The answer is simple. We just look for a event from the device we control. In the decision matrix of the switches we just enter
It’s very easy to add a switch to the scenario above and it can be even easier if the zone concepts are used. In this concept each switch on/off event add information on which zone it controls and the same change is done in the decision matrix we get something like:
We now get even more flexible when we need to add/change the setup.
What if I want to control the lights from my PC?
No problem just send the same on-event to the zone from the PC. The relay and the switches will behave just as a new switch has been added.
What if I want a remote control that controls the lighting?
Just let the remote control interface have a decision matrix element that sends out the on-event to the zone when the selected key is pressed.
What if I want the lights to be turned on when the alarm goes off?
Same solution here. Program the alarm control to send the on-event to the zone on alarm.
You imagination is the only limitation….
Also check VSCP over TCP/IP which have more Level II specifics for the lower levels.
Level II nodes are intended for media with higher bandwidth then Level I nodes and no nickname procedure is therefore implemented on Level II. As result of this the full GUID is sent in each packet.
The header for a level II event is defined as
The biggest differences is that the GUID is sent in each event and that both class and type has a 16-bit length.
The CRC is calculated using the CCITT polynomial
The max size for a Level II event is 512 bytes and as the header takes up 25 bytes the payload or data-part can take up max 487 bytes. This can seem a bit strange looking at the above structure but in a datagram or another package not all of the above members are present. The format in a stream is
As is noted the obid and time-stamp is not present in the actual stream and is only inserted by the driver interface software.
Level I events can travel in the Level II world. This is because all Level I events are repleted in Class=1024. As nicknames are not available on Level II they are replaced in the events by the full GUID. This is an important possibility in larger installations.
A event from a node on a Level I that is transferred out on a Level II can have the nodes own GUID set or the GUID of the interface between the Level I and the Level II segment. Which method to choose is up to the implementor as long as the GUID’s are unique.
For interfaces the machine MAC address, if available, is a good base for a GUID which easily can map to real physical nodes that are handled by the interface. By using this method each MAC address gives 65536 unique GUID’s.
Other methods to generate GUID’s s also available form more information see Appendix A.
VSCP level II events can be presented as XML data. Format is
To classify as a node in a VSCP net all nodes must be uniquely identified by a globally unique 16-byte (yes that is 16-byte (128 bits) not 16-bit) identifier. This number uniquely identifies all devices around the world and can be used as a means to obtain device descriptions as well as drivers for a specific platform and for a specific device.
The manufacturer of the device can also use the number as a serial number to track manufactured devices. In many other environments and protocols there is a high cost in getting a globally unique number for your equipment. This is not the case with VSCP. If you own an Ethernet card you also have what is needed to create your own GUID’s.
The GUID address is not normally used during communication with a node. Instead an 8-bit address is used. This gives a low protocol overhead. A segment can have a maximum of 127 nodes even if the address gives the possibility for 256 nodes. The 8-bit address is received from a master node called the segment controller. The short address is also called the nodes nickname id or nickname address.
Besides the GUID it is recommended that all nodes should have a node description string in the firmware that points to a URL that can give full information about the node and its family of devices. As well as providing information about the node, this address can point at drivers for various operating systems or segment controller environments. Reserved GUID’s
Some GUID’s are reserved and unavailable for assignment. Appendix A list these and also assigned id’s.
The VSCP team controls the rest of the addresses and will allocate addresses to individuals or companies by them sending a request to guid_request@vscp.org. You can request a series of 32-bits making it possible for you to manufacture 4294967295 nodes. If you need more (!!!) you can ask for another series. There is no cost for reserving a series. Appendix A in this document contains a list of assigned addresses which will also be available at http://www.vscp.org
It is possible to create your own GUID without requesting a series and still get a valid VSCP GUID.
| Assigned Global Unique ID’s | ID’s Series Reserved to/for |
| FF FF FF FF FF FF FF FF YY YY YY YY YY YY YY YY | Dallas Semiconductor GUID’s. This is the 1-wire/iButton 64-bit id. The device code is in the MSB byte and CRC in the LSB byte. |
| FF FF FF FF FF FF FF FE YY YY YY YY YY YY XX XX | Ethernet Device GUID’s. The holder of the address can freely use the two least significant bytes of the GUID. MAC address in MSB - LSB order. Also called MAC-48 or EUI-48 by IEEE |
| FF FF FF FF FF FF FF FD YY YY YY YY XX XX XX XX | Internet version 4 GUID’s. This is a 32-bit id so the holder of the address can freely use the four least significant bytes of the GUID. IP V4 address in MSB - LSB order. |
| FF FF FF FF FF FF FF FC XX XX XX XX XX XX XX XX | Private. Use for in-house local use. The GUID should never appear outside your local segments. |
| FF FF FF FF FF FF FF FB YY YY YY XX XX XX XX XX | ISO id. This is a three byte id so the holder of the ISO ID can freely use the five least significant bytes of the GUID. |
| FF FF FF FF FF FF FF FA YY YY YY YY XX XX XX XX | CiA (CAN in Automation) vendor ID. This is a 32-bit id so the holder of the vendor ID can freely use the four least significant bytes of the GUID. |
| FF FF FF FF FF FF FF F9 YY YY YY XX XX XX XX XX | ZigBee 802.15.4 OID. This is a 24-bit id so the holder of the OID can freely use the five least significant bytes of the GUID. |
| FF FF FF FF FF FF FF F8 YY YY YY YY YY YY XX XX | Bluetooth MAC. This is a 48-bit id so the holder of the OID can freely use the two least significant bytes of the GUID. |
| FF FF FF FF FF FF FF F7 YY YY YY YY YY YY YY YY | IEEE EUI-64. This is a 64-bit id. The upper three bytes are purchased from IEEE by the company that releases the product. The lower five bytes are assigned by the device and must be unique. |
| FF FF FF FF FF FF FF F6 00 YY YY YY YY YY YY YY | Reserved for RAMTRON MRAM (and compatible), seven byte id’s. |
| FF FF FF FF FF FF FF F6 01 YY YY YY YY YY YY YY - FF FF FF FF FF FF FF F6 FF YY YY YY YY YY YY YY | Reserved other future seven bit id (memory devices) that may have id, such as PRAM etc. |
| FF FF FF FF FF FF FF F5 00 00 00 00 - FF FF FF FF FF FF FF FF FF FF FF FF | Reserved |
| 00 00 00 00 00 00 00 00 00 00 00 00 xx xx xx xx | Lab usage. You can use this range for your own development or for in-house local use. The GUID should never appear outside your local segments. |
| FE YY YY YY YY YY YY YY YY YY YY YY YY YY YY YY | Reserved for a generated 128 bit GUID where the most significant byte is replaced by FE Only use for Level II and on internal net. http://hegel.ittc.ku.edu/topics/internet/internet-drafts/draft-l/draft-leach-uuids-guids-01.txt |
Note that there is a convenient shorthand notation :: used for IPV6 that can be used as a placeholder for zeros. For example
::1 really means 00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:01
and
FF:21::22:32
is the same as
FF:21:00:00:00:00:00:00:00:00:00:00:00:00:22:32
we use *: in the same way for FF’s so that
*:1 really means
FF:FF:FF:FF:FF:FF:FF:FF:FF:FF:FF:FF:FF:FF:FF:01
These shortcut notations makes it much easier to write GUID’s.
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 0×00 – 0x7f are application specific. Registers between 0×80-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 (0×83) 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 (0×92/0×93) 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.
0×98 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 implementor wishes to do so. This even if the event is a Level I event.
The VSCP registers are defined as follows:
| Address | Access Mode | Description |
|||||||||||||||||||||||||||||||||||||||||
| 0×00 – 0x7f | — | Device specific. Unimplemented registers should return zero. |
|||||||||||||||||||||||||||||||||||||||||
| 128/0×80 | Read Only | Alarm status register content (!= 0 indicates alarm). Condition is reset by a read operation. The bits represent different alarm conditions. |
|||||||||||||||||||||||||||||||||||||||||
| 129/0×81 | Read Only | VSCP Major version number this device is constructed for. |
|||||||||||||||||||||||||||||||||||||||||
| 130/0×82 | Read Only | VSCP Minor version number this device is constructed for. |
|||||||||||||||||||||||||||||||||||||||||
| 131/0×83 | Read/Write | Node control flags
|
|||||||||||||||||||||||||||||||||||||||||
| 132/0×84 | Read/Write | User ID 0 – Client settable node id byte 0. |
|||||||||||||||||||||||||||||||||||||||||
| 133/0×85 | Read/Write | User ID 1 – Client settable node id byte 1. |
|||||||||||||||||||||||||||||||||||||||||
| 134/0×86 | Read/Write | User ID 2 – Client settable node id byte 2. |
|||||||||||||||||||||||||||||||||||||||||
| 135/0×87 | Read/Write | User ID 3 – Client settable node id byte 3. |
|||||||||||||||||||||||||||||||||||||||||
| 136/0×88 | Read/Write | User ID 4 – Client settable node id byte 4. |
|||||||||||||||||||||||||||||||||||||||||
| 137/0×89 | 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/0×90 | Read only | Manufacturer sub device ID byte 3. |
|||||||||||||||||||||||||||||||||||||||||
| 145/0×91 | Read only | Nickname id for node if assigned or 0xff if no nickname id assigned. |
|||||||||||||||||||||||||||||||||||||||||
| 146/0×92 | Read/Write | Page select register MSB |
|||||||||||||||||||||||||||||||||||||||||
| 147/0×93 | Read/Write | Page Select register LSB |
|||||||||||||||||||||||||||||||||||||||||
| 148/0×94 | Read Only | Firmware major version number. |
|||||||||||||||||||||||||||||||||||||||||
| 149/0×95 | Read Only | Firmware minor version number. |
|||||||||||||||||||||||||||||||||||||||||
| 150/0×96 | Read Only | Firmware sub minor version number. |
|||||||||||||||||||||||||||||||||||||||||
| 151/0×97 | Read Only | Boot loader algorithm used. 0Xff for no boot loader support. Codes for algorithms are specified here vscp_event_class_000 for Type = 12 |
|||||||||||||||||||||||||||||||||||||||||
| 152/0×98 | 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/0×99 | Read Only | Number of register pages used. If not implemented one page is assumed. |
|||||||||||||||||||||||||||||||||||||||||
| 154/0x9A-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 oxff. 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. |
|||||||||||||||||||||||||||||||||||||||||
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 0×0000 when its ready. Applications can use the registers as a Mutex which is signaled when not zero.
Unimplemented registers should return zero.
The level II abstraction model is the same as Level I but covers a much wider address space.
The registers are layed out in an 32-bit address space with the standard Level I register map on the top (0xffffff80 - 0xffffffff).
Level II also has a configuration model where data for a node can be read and written in XML format. Its up to the design of the node which method to use as long as the required registers are implemented. It is however recommended that both methods are present so a register read/write could be used as a last resort to configure also a high end device.
Every event on a VSCP segment can be seen as an event. To be of any use to anyone a decision has to be taken on what to do as a result of the event. This is done in a decision matrix, which is a standardized way to write the rules that take care of events. To get something done when a specific event is detected some sort of action mechanism is needed.
The event-decision-action model or eda-model is the way we look at the functionality of a VSCP-node. First of all a node can be a level I or level II node. A level I node can perform actions from all level I events. A level II node can handle both level I and level II events. In fact when we define rules we define them at the highest level.
To be able to build a software model that is common for several device/machine/situation types and environments we have to make a model to suit the typical control situation. The model is very simple and is also very easy to implement on different target environments.
Something happens that triggers some kind of input. This could be the elapse of a timer, a delivered temperature reading, a triggered fire alarm etc. Without this state there is nothing to do. We call this state the EVENT - state.
If an event occurs we may react in some way to this happening. This reaction comes after a decision about if and how the event should be handled. We use a decision matrix to control the logic of our decisions. Every element in the decision matrix handles one event and performs one action. A decision matrix element is also capable of generating events and can in this way perform several actions on the behalf of one event.
The action is the function, thread, procedure, method or other functionality that should be carried out as a result of an event.
The states represented by EVENT + DECISION + ACTION are treated as one transaction. All steps must be handled for the transaction to be marked as completed.
So when you describe the functionality of a VSCP-node you say
To make the node a useful piece of equipment it needs a decision matrix. This matrix can be implemented with no possibility for a user to change it or it can be undefined and left for the user to specify.
In resource-limited environments, such as a microprocessor, the previously discussed matrix format takes up to much space and a more resource friendly format is therefore defined. Here the class + type bytes formats the event.
This matrix has no trigger for data values. This has to be done internally by the application using user defined codes.
A matrix row consists of 8 bytes and has the following format
| Byte 0 | Byte 1 | Byte 2 | Byte 3 | Byte 4 | Byte 5 | Byte 6 | Byte 7 |
| oaddr | flags | class-mask | class-filter | type-mask | type-filter | action | action-parameter |
byte 0 byte 1 byte 2 byte 3 byte 4 byte 5 byte 6 byte 7 oaddr flags class-mask class-filter type-mask type-filter action action-parameter
Oaddr is the originating address. We are only interested in events from the node given here. 0×00 is segment controller and 0xff is a node without a nickname. If bit 6 of flags is set oaddr will not be checked and events from all nodes will be accepted.
| Bit # | Description |
| 7 | Enabled if set to 1 |
| 6 | oaddr should be checked (=1) or not checked (=0) |
| 5 | Indicates hard-coded originating address if set to 1 |
| 4 | Match Zone to trigger DM entry |
| 3 | Match Subzone to trigger DM entry |
| 2 | Reserved |
| 1 | Class-mask bit 8 |
| 0 | Class-filter bit 8 |
The enable bit can be used to disable a decision matrix row while it is edited.
The zone and use subzone bits can be activated to have a check on the zone/subzone information of an event. That is the zone/subzone of the machine must match the one of the event to trigger the DM row. Bits 0/1 are the ninth bit of the filter/mask not enable bits.
A class that should trigger this decision matrix row is defined in class-mask and class-filter with bit eight for both taken from the flags byte.
The following table illustrates how this works
| Mask bit n | Filter bit n | Incoming event class bit n | Accept or reject bit n |
| 0 | x | x | Accept |
| 1 | 0 | 0 | Accept |
| 1 | 0 | 1 | Reject |
| 1 | 1 | 0 | Reject |
| 1 | 1 | 1 | Accept |
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.
A type that should trigger this decision matrix row is defined in type-mask and type-filter with bit eight for both taken from the flags byte.
A similar truth table as for the class-mask/filter is used.
This is the action or operation that should be performed if the filtering is satisfied. Only action code 0×00 is predefined and means No-Operation. All other codes are application specific and typical application defined codes could do measurement, send predefined event etc.
A numeric action can be set and its meaning is application specific.
The number of matrix rows are limited in a micro controller. The control class has an event defined that gets the number of elements in the matrix and the location of the matrix in the register model of the node (Get Decision matrix info, CLASS1.PROTOCOL, Type=33).
The matrix information is read and written with the standard read/write control functions. And is placed in the standard low register range (< 0×80) or in an optional page in this area.
Note that there is no demand that a node implements a decision matrix. If not implemented the Get Decision matrix info just returns a zero size.
A special paged feature is available for the decision matrix to save register space. If the offset for the decision matrix is 0×80 - 8 i.e. Starts at 0×78 (120) it is implied that the register position just below 0×77(119) contains a register that is an index to the active DM.
Method CLASS1.PROTOCOL TYPE=32 is used to fetch decision matrix information for a specific node.
It is important to note that the decision matrix can contain any number of lines for a specific event element. So one incoming event can trigger many actions.
Events are marked as handled when the action thread is started. This can be bad in some situations where the event chain is dependent on the action to complete its task before any new work is done. In this case it is better to continue the event chain by posting an event from the action thread instead of setting the following event as a next event in the decision matrix.
The decision matrix structure gives us the freedom to implement events that perform:
To understand how the decision matrix is updated one needs to understand how it is set up. Each line of the matrix is built from a table of entries of the following form:
| byte 0-3 | byte 4-7 | byte 8-11 | byte 12-13 | byte 14-n |
| mask | filter | control | action | action-parameter |
where the action-parameter has device specific length.
This is a bit mask, which has ones at the bit positions of the event that is interesting. So 0xffffffff makes all events interesting. Class is in the high word. Type is in the low word. For a truth table see the class-mask for Level I decision matrices.
This is a bit mask, which tells the value for bits that is of interest. Class is in the high word. Type is in the low word. For a truth table see the class-mask for Level I decision matrices.
| bit # | Description |
| 31 | Enabled if set to 1. If disabled the decision matrix element is ignored. |
| 30 | Reserved. |
| 29 | Marks end of matrix. No more valid entries in the DM after this line. Used to save parsing resources. |
| 28 | Reserved. |
| 27 | Reserved. |
| 26 | Reserved. |
| 25 | Reserved. |
| 24 | Reserved. |
| 23 | Reserved. |
| 22 | Reserved. |
| 21 | Reserved. |
| 20 | Reserved. |
| 19 | Reserved. |
| 18 | Reserved. |
| 17 | Reserved. |
| 16 | Reserved. |
| 15 | Reserved. |
| 14 | Reserved. |
| 13 | Reserved. |
| 12 | Reserved. |
| 11 | Reserved. |
| 10 | Reserved. |
| 9 | Reserved. |
| 8 | Reserved. |
| 7 | Reserved. |
| 6 | Reserved. |
| 5 | Match index of this module to trigger DM entry. Byte 0 of data. . |
| 4 | Match Zone of this module to trigger DM entry. Byte 1 of data. |
| 3 | Match Subzone of this module to trigger DM entry. Byte 2 of data. |
| 2 | Reserved. |
| 1 | Reserved. |
| 0 | Reserved. |
Level II decision matrix control word
Specific node implement ions decide how to interpret bits or not. Just some or none of the bits can be used if that suits the implement ion.
This is the what should be carried out to make this action happen. This is a 16-bit cod that is application specific. 0×0000 is the only code that is predefined as no operation.
This is a variable length text-string/binary array that can contain parameters for the action. Format is application dependent. Can be omitted if no parameters are used.
A decision matrix row is 14 bytes plus the size of the action parameters.
A special paged feature is available for the decision matrix to save register space. If the offset for the decision matrix is 0×80 - dm-row-size (a DM row aligned to the upper register border) it is implied that the register position just below, 0×80 -dm-row-size - 1, contains a register that is an index to the row that has its first byte at 0×80 - dm-row-size.
The index byte is used to select rows and the selected row is available from the byte after the index byte to the 0×80 border.
Method CLASS1.PROTOCOL TYPE=32 is used to fetch decision matrix information for a specific node. Byte six of the response tells the actual size for a decision matrix row.
The Level II Decision Matrix has no entry for originating address. The action parameter field can be used for this information if needed.
For the measurement class and the data class all data is sent in a form that is related to the default format of the data. The number of data bytes in the frame also reflects the size of the variable. In this definition there is a very important assumption. If two nodes should be able to talk to each other they have to know each others data formats. So our assumption is that if a node is interested in what another node has to say it must learn its data format. Also if a node needs to control another node it has to learn its data format to do so.
As a guideline the format defined bellow for the first data byte of a data frame can be used but if a user likes to use another format it is perfectly fine to do so.
Tells how data that follows should be interpreted. This is used for CLASS1.MEASUREMENT and CLASS1.DATA
| Bits | Description |
| 5,6,7 | Represent one of several numerical representations in which the data that follows can be represented as. |
000b Bit Format The data should be represented as a set of bits. This can be used for picture coding etc.
001b Byte Format( 0x20 ) The data should be represented as a set of bytes.
010b String Format( 0x40 ) The data should be represented as an ASCII string (possibly with language extensions (8-bit)).
011b Integer Format( 0x60 ) Data is coded as an integer. The integer is coded in the bytes that follows and can be 1-7 bytes where the most significant byte always is in byte 1 (big endian).
100b Normalized Integer Format( 0x80 ) Data is coded as a normalized integer. In this case the format byte is followed by the normalizer byte which have bit 7 set if the value that is represented by the integer that follow should have a decimal point that is shifted to the right. I bit 7 is reset the decimal point should be shifted to the left. Thus a set bit 7 represent a number between -1 and +1.
The normalizer bytes lower six bits tells how many position the decimal point should be shifted left or right. If bit 7 is set i.e. indicates a value < 1 the decimal point should be shifted in the left direction and if bit 7 is cleared it is a value > 1 and the decimal point should be shifted in the right direction.
The actual integer is coded in the bytes that follows and can be 1-6 bytes where the most significant byte always is in byte 2. This integer is always signed and always given as a two’s complement number.
101b Floating point value( 0xA0 ) 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. The frame holds a total of five bytes. The full definition is at http://www.psc.edu/general/software/packages/ieee/ieee.html and further info at http://en.wikipedia.org/wiki/IEEE_754-1985
110b Reserved.( 0xC0 ) The format is yet to be defined.
111b Reserved( 0xE0 ) The format is yet to be defined.
| Bits | Description |
| 3,4 | Indicates how the data should be interpreted. Typically this is a unit like Centigrade, Fahrenheit or Kelvin for a temperature value. |
00b Standard format. All other codes in this field are event class/type specific.
| Bits | Description |
| 0,1,2 | Zero based sensor index which can be used if there are more then one sensor handled by the node. |
The VSCP registers 0xe0-0xff specifies the Module Description File URL (without “http://” which is implied). The file is in XML format and defines a modules functionality, registers and events. The intended use is for application software to be able to get information about a node and its functionality in an automated way.
On Level II devices this information can be available in the configuration data and be locally stored on the node. If language tags are missing for a name or a description or in an other place where they are valid English should be assumed.
Notes Register definitions must be available for all nodes (if it has registers defined). A register which does not have a an abstraction defined will be handled with a default abstraction constructed from its offset as
for example
The type will always be “uint8_t” in this case
“\n” can be used for a new line in text.
Registers are always eight bits. This is the only way a VSCP unit can be interfaced to. Everything it exports of it’s black box functionality must be broken down into eight bit registers. The common denominator between devices in short.
For user applications this may be inconvenient as a higher level application wants to look at parameters in a smarter way. A string should be a string instead of a sequence of registers. An integer a numerical value instead of two consecutive registers with a high and a low part. To overcome this abstractions can be defined in the MDF file that tells which registers make up a string and which register makes up an integer. This can then be presented to the user and the software can handle the actual register abstraction model.
Lets look at an example. The reference model for the Ethernet based Nova module have a protection timer. O the unit this timer takes up two consecutive registers for each output channel it protects. The first byte is as it should be the most significant byte of the timer and the second byte is the least significant byte. Thus the actual timer value is byte0 * 256 + byte1. In the MDF file for Nova this is written as
As seen the register at position 26 and 27 is used. Both on page 0. A user that gets this information presented for him/here needs to do some calculations to actually set the value. To make it possible to preset this to a user in a more user friendly way and abstraction is defines.
Now the two registers instead is presented as an unsigned 16 bit integer in a way a user expect it to be. He/she just set the value in seconds for the protection timer and the control system knowing that an unsigned integer needs two bytes can write or read the value from the register pair 26/27.
Also here an URL pointing to formatted help information is set. This URL could have been set for the registers as well of course.
User software first try to present information to users using the definitions in the abstraction section and only use registers if no abstraction covers that register.
This is the VSCP boot loader. Note that several other low level boot loader mechanisms that are more suited for low memory footprint devices are available. Many devices of today have the capability for in circuit programming and can have their firmware changed whilst still in the system. This is supported by VSCP with boot loader events.
Most flash devices are programmed block by block. The boot loader algorithm must support this. Blocks are usually quite small but to be compatible with future devices 16-bit words are used to describe a block size. 16-bit words are also used to describe the number of available blocks. This means that the total Flash size is described by a 32-bit word and the maximum flash size supported is thus four gigabytes.
The boot loader sequence is as follows:
The boot-loader is built to direct control flash if other methods such as intermediate storage is used. Data can be loaded direct and program block can just get a dummy ACK.
rev 0.3: 2004-09-22 The CAN boot loader is a modified version of a boot loader that Microchip describes in there application note AN247. Source for the boot loader is available at /firmware/pic/bootloader/Microchip/firmware in the source tree.
This boot loader is based on the Microchip CAN boot loader for 18F devices that is described in their application note 247 (see references at the end of this document for a pointer to original code and excellent documentation). This work remains much the same but some changes have been made to it to make it suitable for VSCP nodes.
The vscpboot application is written in C++ using the wxWidgets library making it usable on multiple platforms (Windows, Unix and in the future Macintosh) The bootloader firmware Entering bootloader mode on a VSCP node
To enter boot loader mode a class=0, Type=12, Enter boot loader mode should be sent to the node. The following data should be supplied
If the supplied data is correct and this bootloader type is supported on the device, a message class=0, type=13, ACK Boot Loader Mode will be sent from the node.
If something is wrong a class=0, type=14, NACK Boot Loader Mode will be sent.
To indicate that the node is in boot loader mode. It will send a message 0x15nn where nn is its node id when it has entered the boot loader. The application should wait for this initial message before it starts its work.
Register 0×97 contains info (the code) about which bootloader algorithm a node support as documented in the VSCP specification for class=0, type=12..
The VSCP bootloader wizard handles this task.
If the filter allows messages for all nicknames to come in to the node it is possible to boot load many nodes at the same time. Each node will answer with its node id but will only react to packages for node 0xff and its own id. In this way it is possible to have part of the programming common for all nodes.
accept only class=0, type=16,17,18,19, origin=all
Responses are of type 20 and 21.
Command id is 0x000010nn where nn is the nickname for the node that initiated the boot load.
The PUT_BASE_INFO command sets address and flags for a device.
Send this command first with the base address and MODE_WRT_UNLCK to be able to write to memory.
If MODE_AUTO_ERASE is set the memory pointer will auto increment after each write.
If MODE_ACK is set then ack messages will be sent from the node after the write. Response messages has the form 0x000014nn where nn is node nickname-id.
To only erase but not write set MODE_ERASE_ONLY
if MODE_AUTO_INC is set, the memory pointer will increment automatically.
Command id is 0x000011nn where nn is the nickname for the node that initiated the boot load.
This command writes data to memory.
The PUT_DATA command sets address and flags for a device.
If MODE_ACK is set then ack messages will be sent from the node after the write. Response messages has the form 0x000015nn where nn is node nickname-id.
If MODE_AUTO_INC is set the memory pointer will increase automatically and one can issue multiple PUT_DATA after each other until the flash is written.
Command id is 0x000012nn where nn is the nickname for the node that initiated the boot load.
This command gets the base info from the node. There is no data for this command.
The response is:
with id 0x000010nn where nn is nickname.
Command id is 0x000013nn where nn is the nickname for the node that initiated the boot load.
This command gets data at the pointer from the node. There is no data for this command.
The response is:
The id has the form 0x000011nn where nn is node nickname-id.
If MODE_AUTO_INC is set the memory pointer will increase automatically and one can issue multiple PUT_DATA after each other until the flash is written.
A node that implements the bootloader but does not want to share memory content can report all data as 0xff.
The Microchip application note AN 247 is the base work for this application. It and it’s accompanying source can be found at http://www.microchip.com/stellent/idcplg?IdcService=SS_GET_PAGE&nodeId=1999&ty=&dty=§ion=&NextRow=&ssUserText=AN247&x=7&y=8&DesignDocSelect=
For VSCP multicast the address
should be used.Please see the following:
http://www.iana.org/assignments/multicast-addressesand http://www.tldp.org/HOWTO/Multicast-HOWTO.html
A class in Level I is described by a number between 0-511. Instead of writing a number the class can be described as CLASS1.XXXX indicate a specific (XXXX in this case) Level I class. Also the form CLASS1.XXXX=yy can be used where yy is the numerical form.
Class definitions can be found in the header file vscp_class.h which is located located in the src/vscp/common folder. In the same folder vscp_type-h can be found which contains defines for types. Also the vscphelper.h/cpp files contains stuff that are useful for handling classes/types as a programmer.
CLASS1.PROTOCOL
This class defines some types that must be implemented by every node that implements the VSCP protocol. The types in this class must be handled by all level I and Level II nodes. Note also that this class is repeated as Level II class=512 with the only difference that GUID’s are used instead of nicknames.
Undefined protocol function.
Not mandatory. Implement in device if needed by application.
A segment controller sends this event once a second on the segment that it controls. The data field contains the 8-bit CRC of the segment controller GUID and the time since the Epoch (00:00:00 UTC, January 1, 1970) as a 32-bit value. A node that receive (and recognize) this event should respond with a CLASS1.INFORMATION, Type=9 event.
Other nodes can originate this event on the segment. For these nodes the data part, as specified below, should be omitted. A better choice for periodic heartbeat events from a node may be CLASS1.INFORMATION, Type=9
All nodes that recognize this event should save the 8-bit CRC in non-volatile storage and use it on power up. When a node starts up on a segment it should begin to listen for the Segment controller heartbeat. When/if it is received the node compares it with the stored value and if equal and the node is assigned a nickname id it continues to its working mode. If different, the node has detected that it has been moved to a new segment and therefore must drop its nickname id and enters the configuration mode to obtain a new nickname id from the segment controller.
If the node is in working mode and it’s nickname id changes, the node should do a complete restart after first setting all controls to their default state.
As a segment can be without a segment controller this event is not available on all segments and is not mandatory.
Uninitiated nodes have the CRC of the segment controller set to 0xff.
A node that is initialized on a segment and does not receive a Heartbeat can take the role of segment controller if it wishes to do so. Only one node one a segment are allowed to do this fully by setting its nickname=0 and therefore a standard node should not have this feature built in. Any node can however behave like a segment controller but use a nickname other then zero.
Mandatory. Must be implemented by all devices.
This is intended for nodes that have been initiated, is part of the segment and is powered up. All nodes that have a nickname id that is not set to 0xff should send this event before they go on line to do their “day to day” work.
Normally all nodes should save their assigned nickname id in nonvolatile memory and use this assigned id when powered up. A segment controller can however keep track of nodes that it controls and reassign the id to a node that it did not get a new node on-line event from. This is the method a segment controller uses to detect nodes that have been removed from the segment.
For the nickname discovery procedure this event is used as the probe. The difference between a probe and a new node on line is that the later has the same originating nickname as value in byte 0.
If a node send this event with the unassigned id 0xff and byte 0 set to 0xff it has given up the search for a free id.
It is recommended that also level II nodes send this event when they come alive. In this case the 16-byte data is the GUID of the node.
Mandatory. Must be implemented by all devices.
This event is sent from a node as a response to a probe. There are no arguments.
Reserved.
Reserved.
Mandatory. Must be implemented by all devices.
This event can be used to change the nickname for a node.
Mandatory. Must be implemented by all devices.
A node sends this event to confirm that it accepts its assigned nickname id. When sending this event the node uses its newly assigned nickname address.
Mandatory. Must be implemented by all devices.
Request a node to drop its nickname. The node should drop its nickname and then behave in the same manner as when it was first powered up on the segment.
There is a variant of this where the GUID is used instead of the nickname to identify the device, Class = 0, Type = 23.
Mandatory. Must be implemented by all devices.
Read a register from a node.
A read/write response event is returned on success.
The following format can be used for nodes on a Level II segment as a midway between a full Level II handling as specified in Class=1024 and Level I.
Mandatory. Must be implemented by all devices.
Response for a read/write event. . Note that the data is returned for both a read and a write and can and probably should be checked for validity.
Mandatory. Must be implemented by all devices.
Write register content to a node.
A read/write response event is returned on success.
The following format can be used for nodes on a Level II segment as a midway between a full Level II handling as specified in Class=1024 and Level I.
Mandatory. Must be implemented by all devices.
Send NACK (Class=0,Type=14 if no boot-loader implemented)
This is the first event in the boot loader sequence. The node should stop all other activities when in boot loader mode. This also means that the node should not react on other events (commands) then the boot loader related.
The following format can be used for nodes on a Level II segment as a midway between a full Level II handling as specified in Class=1024 and Level I.
Boot-loader Codes
Not mandatory. Only needed if a VSCP boot-loader algorithm is used.
This event has no meaning for any node that is not in boot mode and should be disregarded.
The node confirms that it has entered boot loader mode. This is only sent for the VSCP boot loader algorithm.
Mandatory. Should be implemented by all devices.
The node was unable to enter boot loader mode. The reason is given by a user specified error code byte. This event has no meaning for any node that is not in boot mode and should be disregarded.
Not mandatory. Only needed if a VSCP boot-loader algorithm is used.
Begin transfer of data for a block of memory. This event has no meaning for any node that is not in boot mode and should be disregarded.
or byte absent = PROGRAM Flash (status quo for old nodes)
DATA (Eeprom, Mram, Fram)
CONFIG (Fuses, cpu configuration)
RAM
Currently undefined - send a NACK as response
or absent = normally, means first memory from the view of the node creator, e.g. internal Flash, internal EEprom etc. Useful for projects that have internal as well es external EEproms so the external one could be addressed with byte5=1. Also with byte4=0 and byte5=1 an SD-Card as well as a second firmware image inside the flash could be addressed.
Response can be Class=0, Type=50 (Start block data transfer ACK) or Class=0, Type=51(Start block data transfer NACK).
Not mandatory. Only needed if a VSCP boot-loader algorithm is used.
Data for a block of memory. This event has no meaning for any node that is not in boot mode and should be disregarded.
Not mandatory. Only needed if a VSCP boot-loader algorithm is used.
Confirm the reception of a complete data block. This event has no meaning for any node that is not in boot mode and should be disregarded.
The write pointer is the actual pointer after the last data has been written i,e the next position on which data will be written.
Not mandatory. Only needed if a VSCP boot-loader algorithm is used.
NACK the reception of data block. This event has no meaning for any node that is not in boot mode and should be disregarded.
The write pointer is the actual pointer after the last data has been written i,e the next position on which data will be written.
Not mandatory. Only needed if a VSCP boot-loader algorithm is used.
Request from a node to program a data block that has been uploaded and confirmed. This event has no meaning for any node that is not in boot mode and should be disregarded.
Not mandatory. Only needed if a VSCP boot-loader algorithm is used.
A node confirms the successful programming of a block. This event has no meaning for any node that is not in boot mode and should be disregarded.
Not mandatory. Only needed if a VSCP boot-loader algorithm is used.
A node failed to program a data block. This event has no meaning for any node that is not in boot mode and should be disregarded.
Not mandatory. Only needed if a VSCP boot-loader algorithm is used.
This command is sent as the last command during the boot-loader sequence. It resets the device and starts it up using the newly loaded code. The 16-bit CRC for the entire program block is sent as an argument. This must be correct for the reset/activation to be performed. NACK boot loader mode will be sent if the CRC is not correct and the node will not leave boot loader mode.
To leave boot mode just send this event and a dummy CRC. Other methods could have been used to load the code but it can still be activated with this event as long as the CRC is correct. This event has no meaning for any node that is not in boot mode and should be disregarded. Response can be Class=0, type=48 (Activate new image ACK) or Class=0, Type=49(Activate new image NACK).
Mandatory. Should be implemented by all devices.
Added in version 1.4.0
This is a variant of Class=0, Type=8 but here the full GUID is used instead of the nickname to identify the node that should drop its current nickname and enter the node-name discovery procedure.
As the GUID is 16 bytes this is a multi-frame event. To ease the storage requirements on the nodes only four GUID bytes are send in each frame. The frames must be sent out within one second interval.
where index goes from 0-3 and GUID bytes are sent MSB first, like
| Index = Byte 0 | Byte 1 | Byte 2 | Byte 3 | Byte 4 |
| Index = 0 | GUID byte 15 | GUID byte 14 | GUID byte 13 | GUID byte 12 |
| Index = 1 | GUID byte 11 | GUID byte 10 | GUID byte 9 | GUID byte 8 |
| Index = 2 | GUID byte 7 | GUID byte 6 | GUID byte 5 | GUID byte 4 |
| Index = 3 | GUID byte 3 | GUID byte 2 | GUID byte 1 | GUID byte 0 |
A device can use just one byte to detect this. This byte is initialized to zero and holds four bits that match correct frames. That is, when this register is equal to 0x0f the nickname should be dropped and the nickname discovery sequence started. The node must also have a timer that reset this byte one second after any of the above frames have been received or when the nickname discovery sequence is started.
Hi-level software must take this one second interval into account when more then one node should be initialized. This event can be used to assign nickname id’s to silent nodes. This is nodes that does not start the nickname discovery process on startup and instead just sits and wait until they are assigned an id with this event.
Mandatory. Should be implemented by all devices.
The page read is implemented to make it possible to read/write larger blocks of data. Two register positions are reserved to select a base into this storage. This is a 16-bit number pointing to a 256-byte page. This means that a total of 65535 * 256 bytes are accessible with this method (page 0 is the standard registers).
To read a block of data from the storage, first write the base registers then issue this event and n events will be sent out from the node containing the data from the specified area. If the count pass the border it of the page ( > 0xff) the transfer will end there.
Note that the page select registers only selects a virtual page that can be accessed with page read/write and not with the ordinary read/write.
Response is
Class=0, Type=26 (0x1A) Read Page Response.
The following format can be used for nodes on a Level II segment as a midway between a full Level II handling as specified in Class=1024 and Level I.
Mandatory. Should be implemented by all devices.
The write page is implemented to make it possible to write larger blocks of data. One data-space positions is reserved to select a base into this storage. See Page read for a full description.
It is only possible to write one 6-byte chunk at a time in contrast to reading several. This is because VSCP at Level I is aimed at low end devices with limited resources meaning little room for buffers.
Response is
Class=0, Type = 26 (0x1A) Read Page Response.
The following format can be used for nodes on a Level II segment as a midway between a full Level II handling as specified in Class=1024 and Level I.
Data count can be as many as the buffer of the Level II node accepts.
Mandatory. Should be implemented by all devices.
This is a response frame for the read page command. The Sequence number goes from 0 up to the last sent frame for a read page request.
The following format can be used for nodes on a Level II segment as a midway between a full Level II handling as specified in Class=1024 and Level I.
Data count can be as many as the buffer of the Level II node accepts.
Should be implemented by all devices that work over 802.15.4/Ethernet/Internet or other high end protocols.
This event can be broad-casted on a segment by a node to get information about available servers.
Code Description 0 this is a TCP/IP node, byte 1-4 is the V4 IP address of the node. Byte 5 - if available - tells the capabilities of this node.
Code Description Bit 0 Node will log in to server using text mode. Bit 1 Node will log in to server using binary mode. Bit 2 Node expect server to connect using text mode. Bit 3 Node expect server to connect using binary mode. Bit 4-7 Reserved. Bit 0 + Bit 1 can be set at the same time indicating that the node can handle both modes. Bit 2 + bit 3 can be set at the same time indicating that the node can handle both modes.
The VSCP daemon documention have a description on how server discovery works ??
Should be implemented by all devices that work on 802.15.4/Ethernet/Internet.
Description of bit-usage
A node that need a TCP connection to a host. Broadcast HIGH END SERVER PROBE on the segment and waits for HIGH END SERVER RESPONSE from one or more servers to connect to. If a suitable server has responded it can decide to connect to that server.
A daemon like the canal daemon can span multiple segments and a reply can therefore be received from a remote segment as well. This can be an advantage in some cases and unwanted in some cases. The server configuration should have control on how it is handled.
The VSCP daemon documention have a description on how server discovery works ??
Mandatory. Should be implemented by all devices.
Increment a register content by one with no risk of it changing in between
If no value is supplied the register is incremented with one.
Node should answer with Read/Write register response. Class=0, Type=10
Mandatory. Should be implemented by all devices.
Decrement a register content by one with no risk of it changing in between
If no value is supplied the register is decremented by one.
Node should answer with Read/Write register response. Class=0, Type=10
Mandatory. Must be implemented by all devices.
This event can be used as a fast way to find out which nodes there is on a segment. All nodes receiving it should respond.
Response is Class = 0, Type = 32.
Mandatory. Must be implemented by all devices.
Response from node(s) looks like this
| byte 0 | byte 1 | byte 2 | byte 3 | byte 4 | byte 5 | byte 6 | byte 7 |
| 0 | GUID15 | GUID14 | GUID13 | GUID12 | GUID11 | GUID10 | GUID9 |
| 1 | GUID8 | GUID7 | GUID6 | GUID5 | GUID4 | GUID3 | GUID2 |
| 2 | GUID1 | GUID0 | MDF20 | MDF1 | MDF2 | MDF3 | MDF4 |
| 3 | MDF5 | MDF6 | MDF7 | MD8 | MDF9 | MDF10 | MDF11 |
| 4 | MDF12 | MDF13 | MDF14 | MDF15 | MDF16 | MDF17 | MDF18 |
| 5 | MDF19 | MDF20 | MDF21 | MDF22 | MDF23 | MDF24 | MDF25 |
| 6 | MDF26 | MDF27 | MDF28 | MDF29 | MDF30 | MDF31 | 0 |
Mandatory if the device got a decision matrix.
Request a node to report size and offset for its decision matrix.
The following format can be used for nodes on a Level II segment as a midway between a full Level II handling as specified in Class=1024 and Level I.
Mandatory if the device got a decision matrix.
Report the size for the decision matrix and the offset to its storage. The reported size is the number of decision matrix lines. The offset is the offset in the register address counter from 0×00 (See the register model in this document). If the size returned is zero the node does not have a decision matrix. A node without a decision matrix can also skip to implement this event but it’s better if it returns a decision matrix size of zero.
The decision matrix can as noted be stored in paged registers and if so it must be accessed with the paged read/write. Level I If the offset given is 0×80-8 = 0×78 the matrix is paged and it is implied that rows are selected in a register located at register position 0×80-8–1 = 0×77. 0 means row 1 is in the register space, 1 = row 2 is in register space and so on.
| Register position | Description |
| 0×77 | Index for row in decision matrix. |
| 0×78-0x7F | Level I decision matrix row. |
Note for event on a Level II network
The same mapping can be used for Level II but the location of the page register is dependent on the row size. Thus a register at register position 0×80-dm-row-size-1 is an index to the row that is available in the decision matrix space.
| Register position | Description |
| (0×80-dm-row-size-1) | Index for row in decision matrix. |
| (0×80-dm-row-size)- 0x7F | Level II decision matrix row. |
Optional.
A node that get this event and has an embedded MDF description in flash or similar respond with the description .
Optional. See Type=35
This is the response from a Get embedded MDF. The response consist of several frames where an index in byte0/1 is incremented for each frame and MDF data is in byte 2-7.
If an embedded MDF is not available a response on the form
byte 0 = 0 byte 1 = 0 byte 2 = 0
should be sent.
Mandatory. Must be implemented by all devices.
Read a register from a node with page information.
Implementation must take care so all page register change done by these routines must restore the content of the page registers to there original content when they are done.
An extended read/write response event is returned on success.
This means that a register (or a maximum of six consecutive registers) located on any page can be read in a single operation.
The following format can be used for nodes on a Level II segment as a midway between a full Level II handling as specified in Class=1024 and Level I.
Mandatory. Must be implemented by all devices.
Write register content to a node.
Implementation must take care so all page register change done by these routines must restore the content of the page registers to there original content when they are done.
A read/write response event is returned on success.
Event allows a register (or a maximum of four consecutive registers) located on any page can be written in a single operation.
The following format can be used for nodes on a Level II segment as a midway between a full Level II handling as specified in Class=1024 and Level I.
Mandatory. Must be implemented by all devices.
This is the replay sent for events CLASS1.PROTOCOL, Type=40,41.
A multi register read/write can generate many events of this type. Index will then be increased by one for each event sent.
Optional. Implemented if needed.
It is possible to ask a node which event(s) it is interested in with this event. If not implemented the node is supposed to be interested in all events.
All nodes are by default interested in CLASS1.PROTOCOL.
The event is intended for very low bandwidth nodes like low power wireless nodes where it saves a lot of bandwidth if only events that really concerns the node is sent to it.
Optional. Implemented if needed.
Response for event CLASS1.PROTOCOL, Type=40. The node report all events it is interested in.
A node that is interested in everything send just a CLASS1.PROTOCOL, Type=41 with no data.
Nodes that want to specify events of interest fill them in. If all types of a class should be recognized set the corresponding bit in byte 1 and the related type to zero.
A maximum of 255 frames (index = 0-254) may be sent.
Fill unused pairs with zero.
Not mandatory. Only needed if a VSCP boot-loader algorithm is used.
Part of the VSCP boot-loader functionality. This is the positive response after a node received a CLASS1.PROTOCOL, Type=22, Activate new image. It is sent by the node before the new firmware is booted into.
Not mandatory. Only needed if a VSCP boot-loader algorithm is used.
Part of the VSCP boot-loader functionality. This is the negative response after a node received a CLASS1.PROTOCOL, Type=22, Activate new image. It is sent by the node to inform it that it will (or can not) switch to the new firmware image.
Not mandatory. Only needed if a VSCP boot loader algorithm is used.
Part of the VSCP boot-loader functionality. This is the positive response after a node received a CLASS1.PROTOCOL, Type=15, Start block data transfer. It is sent by the node as a validation that it can handle the block transfer.
Not mandatory. Only needed if a VSCP boot-loader algorithm is used.
Part of the VSCP boot-loader functionality. This is the negative response after a node received a CLASS1.PROTOCOL, Type=15, Start block data transfer. It is sent by the node as an indication that it can NOT handle the block transfer.
CLASS1.ALARM
Alarm events that indicate that something not ordinary has occurred. Note that the priority bits can be used as a mean to level alarm for severity.
Undefined alarm.
Indicates a warning condition.
If both or one of zone/sub zone are omitted they should be interpreted as if they where 255.
Indicates an alarm condition.
If both or one of zone/sub zone are omitted they should be interpreted as if they where 255.
Alarm sound should be turned on or off.
If both or one of zone/sub zone are omitted they should be interpreted as if they where 255.
Alarm light should be turned on or off.
If both or one of zone/sub zone are omitted they should be interpreted as if they where 255.
Power has been lost or is available again.
If both or one of zone/sub zone are omitted they should be interpreted as if they where 255.
Emergency stop has been hit/activated. All systems on the zine/subzone should go to their inactive/safe state.
Emergency pause has been hit/activated. All systems on the zone/subzone should go to their inactive/safe state but preserve there settings.
If both or one of zone/sub zone are omitted they should be interpreted as if they where 255.
Issued after an emergency stop or pause in order for nodes to reset and start operating .
Issued after an emergency pause in order for nodes to start operating from where they left of without resetting their registers .
If both or one of zone/sub zone are omitted they should be interpreted as if they where 255.
CLASS1.SECURITY
Security related events for alarms and similar devices.
Undefined security issue.
A motion has been detected.
If both or one of zone/sub zone are omitted they should be interpreted as if they where 255.
CLASS1.MEASUREMENT
Byte 0 is the data coding byte for all measurement packages. The default unit has bits 0,1,2 set to 000 and the first optional unit 001 and so on. It also have a field for the item ( if more than one sensor is controlled by the node) that the value belongs to. See ?? for a full description on datacoding used.
All events in this class are mirrored in Class=60 (0x3c) as floating point values with the defautlt unit ??.
Undefined measurement value.
This is a discrete value typical for a count. There is no unit for this measurement just a discrete value.
Default unit: Meter.
Default unit: Kilogram.
Default unit: Millisecond.
Opt.unit: (1) Second Absolute: (2) y-y-m-d-h-m-s (binary) String: (3) HHMMSS Time since Epoch (00:00:00 UTC, January 1, 1970).
Default unit: Ampere.
Default unit: Kelvin.
Opt. unit: Degree Celsius (1), Fahrenheit (2)
Default unit: Mole.
Default unit: Candela.
Default unit: Hertz.
Default unit: Becquerel.
Default unit: Newton.
Default unit: Pascal.
Opt. unit: bar (1), psi (2)
Default unit: Joule.
Default unit: Watt.
Default unit: Coulomb.
Default unit: Volt.
Default unit: Farad.
Default unit: Ohm.
Default unit: Siemens.
Default unit: Ampere meters.
Default unit: Weber.
Default unit: Tesla.
Default unit: Henry.
Default unit: Lumen (lm= cd * sr)
Default unit: Lux ( lx = lm / m² )
Default unit: Gray. Opt unit: Sievert.
Default unit: Katal.
Default unit: qubic meter
Opt. Unit: Liter (dm³) (1).
Default unit: Bel.
Opt Unit: Neper (1), dB (2).
Default unit: Radian (Plane angles).
Opt Unit: Degree (1)
Opt Unit: Arcminute (2)
Opt Unit: Arcseconds (3)
Default unit: Longitude. Opt. Unit: Latitude.
Default unit: Meters per second.
Default unit: Meters per second/second.
Default unit: N/m.
Default unit: Relative percentage 0-100%.
Default unit: Qubic meters/second. Opt Unit: Liter/Second.
Default unit: Thermal ohm K/W.
Default unit: Diopter (dpt) m-1.
Default unit: Poiseuille (Pl) Pa . s.
Default unit: Rayal Pa . s/m.
Default unit: Acoustic ohm Pa . s/ m3.
Default unit: Darag F-1.
Default unit: Talbot ( tb = lm * s)
Default unit: Nit (nt = cd / m²)
Default unit: Molal mol/kg.
Reserved (previously was doublet of Type 26, don’t use any longer!)
Default unit: Sievert J/Kg.
Reserved (was doublet of type 24, do not use any longer!)
Default unit: Kelvin. Opt. unit: Degree Celsius (1), Fahrenheit (2)
Default unit: Relative value.
Default unit: Meter. Opt. unit: Feet(1), inches (2)
Default unit: square meter (m²)
Default unit: watt per steradian ( W / sr )
Default unit: att per steradian per square metre ( W / (sr * m²) )
Default unit: watt per square metre ( W / m² )
Default unit: watt per steradian per square metre per nm (W·sr-1·m-2·nm-1) Opt. Units: watt per steradian per metre3 (W·sr-1·m-3) watt per steradian per square metre per hertz (W·sr-1·m-3)
Default unit: watt per square metre per nm (W·m-2·nm-1) Opt. Units: watt per metre3 (W·m-3) watt per square metre per hertz (W·m-2·Hz-1)
CLASS1.DATA
Representation for different general data types. Byte 0 is the data coding byte for all data packages. The default unit has bits 0,1,2,3 set to 0000 and the first optional unit 0001 and so on.
General event.
General I/O value. First data byte defines format.
General A/D value. First data byte defines format.
General D/A value. First data byte defines format.
Relative strength is a value that has its maximum at 255 and minimum at 0 if the data part is one byte. If the data part is two bytes the minimum strength is still at zero but the maximum strength is at 65535.
Signal Level is a relative strength value that (as default) has its maximum at 100 and minimum at 0 interpreted as a percentage. For a digital transmission Signal Level it can be used to give an indication of the analogue signal and CLASS1.DATA, Type = 6, Signal Quality can be used to give an indication of the quality of the digital part as BER (Bit Error Ratio) for example.
Default coding: percentage. Optional codings: Scale 0-255 (1), Scale 0-65535 (2)
Signal Quality be used to give an indication of the quality of the digital part as BER (Bit Error Ratio) for example.
Default coding: percentage. Optional codings: Scale 0-255 (1), Scale 0-65535 (2)
CLASS1.INFORMATION
Most of the events below have an index parameter that can be used to indicate which of several SECO (sensor/control) units on a node originated the event. Set to zero if the node only control one item. Type = 0 (0x00) Undefined
This is a general event of no special type.
A button has been pressed/released.
A mouse movement has occurred.
A node indicates that a condition is in its on state. Heater on, lights on are two examples.
A node indicates that a condition is in its off state. Heater off, lights off are two examples.
A node tells the world that it is alive.
A node tells the world that it is terminating.
A node indicates that an open has occurred. This can be a door/window open, a modem line open etc.
A node indicates that a close has occurred. This can be a door/window close, a modem line closure etc.
Heartbeats can be used to indicate that a unit is alive or to send periodic data. This can be sent out at predefined intervals to indicate that the node is alive, however, it does not necessarily mean the node is functioning as it should. It simply states that the node is connected to the network. To check if a node is functioning, other properties such as a measurement event or registry should be used. This event should be sent as a response to a “Segment Status Heartbeat” (CLASS1.PROTOCOL, Type=1) in order to provide a method of finding out what is connected to the network. The data bytes from byte 3 and forward can be used to send a descriptive/user friendly name if desired.
Not mandatory but it is recommended that all nodes send this event on regular intervals.
This indicates that the node has a condition that is below a configurable limit.
This indicates that the node has a condition that is above a configurable limit.
This can be used for slow pulse counts. This can be an S0-pulse interface or something similar.
A node indicates that an error occurred.
A node indicates that it has resumed operation.
A node indicates that it has paused.
A node indicates that it eneterd a sleeping state.
The system should enter its morning state. This can be a user pressing a button to set his/her house to it’s morning state.
The system should enter its day state. This can be a user pressing a button to set his/her house to it’s day state.
The system should enter its afternoon state. This can be a user pressing a button to set his/her house to it’s afternoon state.
The system should enter its evening state. This can be a user pressing a button to set his/her house to it’s evening state.
The system should enter its night state. This can be a user pressing a button to set his/her house to it’s night state.
The system should be on a temporary alert. This can be a user locking the door to go out to the waste bin or similar situation. An alarm system should not be activated in this situation.
The system should be on a goodbye alert. This can be a user locking the door to go out for a day’s work or similar situation. All alarm systems should be activated in this situation.
A node indicates that a stop event occurred. This can for example be a motor stopping.
A node indicates that a start event occurred. This can be a motor starting.
A node indicates that a reset occurred. This can be a node doing a warm start.
A node indicates that a reset occurred. This can also be a node doing a warm start.
A node indicates that a sleep event occurred. This can be a node going to its inactive state.
A node indicates that a wakeup event occurred. This can be a node going to it awake state.
A node indicates that the system should enter its dusk state.
A node indicates that the system should enter its dawn state.
A node indicates that its active.
A node indicates that its inactive.
A node indicates that its busy.
A node indicates that its idle.
A steam of information from a node can be reported with this event. This can be a serial RS- 232 channel or some other sequential stream.
This event is used for cards, RFID’s, iButtons, GSM phones and other identification devices. The event is generated when the token device is attached/detached to/from the system. Level II has a counterpart to this event that can take more data. CLASS2.INFORMATION Type=1
Depending on the Token device type a number of this event are sent on the segment with frame index increase for each event. The total expected number can be deduced from the type.
Touched and released.
Touched.
Released.
Reserved.
Unknown Token. 128-bits
iButton 64-bit token. 64-bits
RFID Token. 64-bits
RFID Token. 128-bits
RFID Token. 256-bits
Reserved.
ID/Credit card. 128-bits
Reserved.
Biometri device. 256-bits
Biometri device. 64-bits
Bluetooth device. 48-bits
GSM IMEI code (International Mobile Equipment Identity) AA-BBBBBB-CCCCCC-D packed in 64 bits. http://en.wikipedia.org/wiki/IMEI
GSM IMSI code (International Mobile Subscriber Identity) packed in 64 bits. http://en.wikipedia.org/wiki/IMSI
RFID Token. 40-bits
RFID Token. 32-bits
RFID Token. 24-bits
RFID Token. 16-bits
RFID Token. 8-bits
Reserved.
A steam of information from a node can be reported with this event. This can be a serial RS- 232 channel or some other sequential stream.
This event can be used as a general confirm event for zoned and stream data.
Response/confirmation from ex. a dimmer control after a dimmer command or some other unit that change a level.
A node indicates that a warning condition occurred.
A node indicates that a state change has occurred. Th numerical id for the current state and the state that is about to become active is supplied.
A node optionally indicates that an action has been triggered by this event.
A node indicates that sunrise is detected/calculated.
A node indicates that sunset is detected/calculated.
This event is used to mark the start of a multi-frame data transfer. This can typically be a GPS received which sends a train of events from one GPS record. The index byte can be used to distinguish record between each other.
This event is used to mark the end of a multi-frame data transfer. The index byte can be used to distinguish record between each other.
This event is used to tell the system that a pre-set configuration is active. Usually a response from a node after a CLASS1.CONTROL, Type=28 has been received by a node.
This event is used to tell the system that a detection of some kind has occurred.
The first byte is used as an index if a module have several channels or detectors.
This event is used to tell the system that an overflow of some kind has occurred.
The first byte is used as an index if a module have several channels or detectors.
CLASS1.CONTROL
Control functionality. One of the main concepts of VSCP is that it is an event driven protocol. Commands are sent out as events to the network not as events to specific devices. A device can belong to a zone which select limit events of interest for the particular node.. If there is a need to control a specific device the registry model should be used. This is the only way to directly control a device.
General control.
Mute/Un-mute all sound generating nodes in a zone
Turn on/off lamps on nodes in zone.
Perform open on all nodes in zone.
Perform close on all nodes in zone.
Turn On all nodes in a zone.
Turn Off all nodes in a zone.
Start all nodes in a zone.
Stop all nodes in zone. byte # Description byte 0 Optional byte that have a meaning given by the issuer of the event. byte 1 Zone for which event applies to (0-255). 255 is all zones byte 2 Sub Zone for which event applies to (0-255). 255 is all sub zones
Perform Reset on all nodes in zone.
Perform Interrupt on all nodes in zone.
Perform Sleep on all nodes in zone.
Wakeup all nodes in zone.
Resume all nodes in zone.
Pause all nodes in zone.
Activate all nodes in zone.
Deactivate all nodes in zone.
Reserved.
Reserved.
Reserved.
Dim all dimmer devices on a segment to a specified dim value.
This is typical for changing TV channels or for changing AV amp input source etc.
Change an absolute level.
Use this event for streamed data out from a node. The source is then given by the nickname. If a specific received is needed use Zoned Stream.
Synchronize events on a segment.
Some nodes may have pre-set configurations to choose from. With this event a pre-set can be set for a zone/subzone.
A node that receive and act on this event send CLASS1.INFORMATION,
Type=48 as a response event.
Toggle the state of a node.
Note: This may be a bad design option as it often demands that the state should be known for the node on beforehand.
With this event it is possible to generate a timed pulse that is on for a specified time.
The control byte have the following bits defined
| Bit | Description | |||||||||||||||||||||||||||||||||
| 0-3 |
|
|||||||||||||||||||||||||||||||||
| 4 | Reserved. | |||||||||||||||||||||||||||||||||
| 5 | Reserved. | |||||||||||||||||||||||||||||||||
| 6 | Send on event ( Class=20 Type = 3 (0x03) On ) when pulse goes on. | |||||||||||||||||||||||||||||||||
| 7 | Send off event ( Class=20 Type = 4 (0x04) Off ) when pulse goes off. | |||||||||||||||||||||||||||||||||
With this event it is possible to generate a timed pulse that is off for a specified time.
The control byte have the following bits defined
| Bit | Description | |||||||||||||||||||||||||||||||||
| 0-3 |
|
|||||||||||||||||||||||||||||||||
| 4 | Reserved. | |||||||||||||||||||||||||||||||||
| 5 | Reserved. | |||||||||||||||||||||||||||||||||
| 6 | Send on event ( Class=20 Type = 3 (0x03) On ) when pulse goes on. | |||||||||||||||||||||||||||||||||
| 7 | Send off event ( Class=20 Type = 4 (0x04) Off ) when pulse goes off. | |||||||||||||||||||||||||||||||||
| Language code | Description | Example |
| 0 | Custom coded system | Byte 3 = 0 English, Byte 3 = 1 German or similar. |
| 1 | ISO 639-1 | nl for Dutch, en for English. |
| 2 | ISO 639-2/T | nid for Dutch, eng for English. |
| 3 | ISO 639-2/B | dut for Dutch, eng for English. |
| 4 | ISO 639-3 | nid for Dutch, eng for English. |
| 5 | IETF (RFC-5646/4647) | en-US for American English. en-GB British. |
ISO codes can be found here http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes
CLASS1.MULTIMEDIA
Dedicated class for multimedia functionality. This class was introduced to supplement the control class and to offer multimedia specific control events.
The Play/Pause/Stop etc. events in the CLASS1.CONTROL class can also be used for media control.
This is for controlling playback functionality
Stop
Pause
Play
Forward
Rewind
Fast Forward
Fast Rewind
Next Track
Previous Track
Toggle repeat mode
Repeat mode ON
Repeat mode OFF
Toggle Shuffle mode
Shuffle ON
Shuffle mode OFF
Fade in, Play
Fade out, Stop
This is typically for navigation functions or DVD controls
0..9 keys
10+ key
OK
Left
Right
Up
Down
Menu
Selecting
A..Z Keys
a-z keys (can’t use ASCII hex as numbers are too large so this is the next best thing)
This is typically for adjusting the contrast level of a display device
This is typically for adjusting the focus settings of a display device
This is typically for adjusting the tint settings of a display device
This is typically for adjusting the color balance settings of a display device.
This is typically for adjusting the tint settings of a display device
This is typically for adjusting the hue settings of a display device
This is typically for adjusting the bass level settings of a sound device. Depending on the implementation, this could automatically adjust the treble level. To adjust left and right bass levels, a node would have to use separate zones or sub zones for left and right.
This is typically for adjusting the treble level settings of a sound device. Depending on the implementation, this could automatically adjust the bass level. To adjust left and right treble levels, a node would have to use separate zones or sub zones for left and right.
This is typically for adjusting the master volume level. This could be used for adjusting the level for all speakers.
This is typically for adjusting the front speaker volume level. This usually means the two front speakers as opposed to the single center speaker.
This is typically for adjusting the front speaker volume level. This usually means the single center speaker as opposed to the two front speakers.
This is typically for adjusting the rear speaker volume level.
This is typically for adjusting the side speaker volume level.
These are reserved for other future speaker combinations
This is typically for selecting a disk for playback
This is typically for selecting a track for playback
This is typically for selecting an album or playlist for playback byte # Description byte 0 A value between 0 and 127 indicates the album/playlist number. A value between 128 and 159 is change down by the specified number of albums/playlists. A value between 160 and 191 is change up by the specified number of albums. A value of 200 means select a random album. A value of 255 means that this is and extended event and that the album number is sent in byte 3 and after. byte 1 Zone for which event applies to (0-255). 255 is all zones. byte 2 Sub Zone for which event applies to (0-255). 255 is all sub zones.
This is typically for selecting a TV Channel
This is typically for selecting a page of a film
This is typically for selecting a chapter of a film
This is for controlling screen format of a display device
This is for controlling the input source of a playback device
Auto
CD
AUX
DVD
SAT
VCR
Tape
Phone
Tuner
FM
AM
Radio (9 – 10 are more specific)
Component
VGA
SVideo
Video1
Video2
Video3
Sat1
Sat2
Sat3
mp3 source
mpeg source
This is for controlling the output of a playback device
Auto
Component
VGA
SVideo
Video1
Video2
Video3
Control a recording device.
Control a recording device.
This is typically for accessing TIVO functions
Box Office
Services
Program Guide
Text
Info
Help
Backup
Red key
Yellow key
Green key
Blue key
White key
Black key
Get the title for the current active media.
This is for controlling the position in the stream/file of a playback device
Get various media information from a device.
If a device does not support the requested type of media information its sends a CLASS1.INFORMATION error event or does not response.
Remove an item from an album.
Remove all items from an album.
Save album/playlist to permanent storage.
Send multimedia information. This can be the title for the current active media. It can be sent as a response to a “Get Title” or similar event or by its own when a new title is playing or other multimedia information has changed.
Response should be Type=61
The last fragment is sent with no data.
Lists in string form have list items separated with a zero (0×00).
Album can be looked upon as a playlist which is a term used for many other multimedia products.
Response for multimedia control.
CLASS1.AOL
AOL Event. The main idea of AOL is to send warnings to remote administrators about different PC conditions using a LAN. Info here http://en.wikipedia.org/wiki/Alert_on_LAN
Undefined
Undefined measurement value.
This node was unplugged from it’s power source.
This node was unplugged from the network.
This node detected chassis intrusion.
This node detected processor removal.
This node detected system environmental errors.
This node detected high temperature.
This node detected Fan speed problem.
This node detected Voltage fluctuations.
This node detected Operating system errors.
This node detected System power-on errors.
This node detected System is hung.
This node detected Component failure.
This node detected Remote system reboot upon report of a critical failure.
This node detected Repair Operating System.
This node detected Update BIOS image.
This node detected Update Perform other diagnostic procedures.
CLASS1.MEASUREMENT64
Floating point measurements. This class mirrors the standars measurement events is class=10 ??. The measurement unit is always the standard unit.
The value is a "double" - IEEE-754, 64 Bits, double precision.
That is a total of 64-bits. The most signifficant byte is stored in byte 0.
CLASS1.PHONE
This class is for phone related functionality.
General event.
There is an incoming phone call. Usually a caller ID node just sends out numerical information. A database event can follow (later) that contains the real text information.
Phone calls are reported in the following form
from,to
where from is the originating number and to is the receiving phone. Numbers is preferable presented in an international form. So a call from England to a Swedish phone should take the following form
44-123-1122334,46-657-413430
which is sent in tree frames. Some device can’t separate country and area-code and therefore the form
441231122334,46657413430
will also be valid.
a database connected application can later resolve this and present
A customer,Eurosource
This is the type=8 event, database info, (see below). Note that the comma cant be used in the descriptive names.
Calls from unlisted numbers are presented as
,to
There is an outgoing phone call.
This is a event indicating that there is a “ring” for this call.
The call has been answered.
The call has been terminated by the receiving end.
The call has been terminated by the originating end. byte
The call has been transferred. byte
CLASS1.DISPLAY
This is generic display related functionality. Show info on a screen, LED-display diode, etc.
The new_york module is an example on the how this can be implemented in a module. Escape sequences
An escape sequence is preceded with a %. As a result to display ”%” %% should be used.
The first character after the % is the escape-type. This character is case sensitive. That is “e” is not the same as “E”.
Escape character Description
Display a register content: The second character tells how the register should be interpreted and it is followed by the register pos. As an example %rn2 can be used to display a normalized integer that is at register pos=2 and forward. The intended use is to have actions that store data from events in registers and that they are displayed by the escape.
| Second character | Description |
| $ | Zero terminated string |
| ! | Boolean value |
| b | signed char |
| B | unsigned char |
| s | signed short |
| S | unsigned short |
| i | signed int |
| I | unsigned int |
| l | signed long |
| L | unsigned long |
| f | floating point decimal value |
| d | date format |
| t | time |
| n | normalized integer |
Parameter data: Display parameter escapes. The format is %p001 where “001” is the id that identifies the parameter. This escape is used for hard parameters displayed by the display maker. Se Type=6 below.
Event data: Event data escapes. The format is %eclass,type,r where class and type tells which event is of interest and r have the same format as the r escape
The above is just a recommendation. Anyone can of course use any format they like.
General event.
Clear the display on displays in a certain zone,subzone.
Move the cursor to a specific position on displays in a certain zone,subzone.
Write to display(s) in a certain zone,subzone. The update of the display is immediate.
Index is increased by one for each event that builds up a specific event. If needed an empty (no data) can be sent as the last event else sending data to fill the display buffer will give the end automatically.
Write to the buffers of displays in a certain zone,subzone. The update of the display is is not done right away but is instead done when the Show Buffer event is received by the display unit.
Index is increased by one for each event that builds up a specific event. If needed an empty (no data) can be sent as the last event else sending data to fill the display buffer will give the end automatically.
Many LCD displays allow definition of special characters. Use this event to define custom matrices buy defining a subzone for the user defined matrix(es).
Tells displays in a certain zone,subzone to display the content in their display buffers. The update of the display is immediate.
With this call a display buffer parameter can be sent to a display. This parameter is inserted at the escape position %pn in the string in the buffer *when the buffer is transferred to the display*.
Note that there are no zone and subzone defined for this event and the escapes must instead be chosen to be distinct in a system. This means that &p1 will be unique within a system and updating this parameter will update on all displays that has it defined.
Note that the event have one byte less then standard measurement events so all coding types can not be used.
This event contains information that should be displayed on displays pointed out by zone/subzone.
This event can have the same functionality as Write Display or be set on an higher abstraction level.
Index is increase by one for each event that builds up a specific event. If needed an empty (no data) can be sent as the last event else sending data to fill the display buffer will give the end automatically.
The text sent to a node can contain escape characters that themselves display data or other display events. Se the new_york node for examples of this.
For a multi line display one can use different sub zones o address different lines. One can also us macro characters to map display events to a line.
This event contains information that should be displayed on LED(s) pointed out by zone/subzone.
Blink period can be omitted if not used or if blink period is defined hard.
This event set the color for LED(s) pointed out by zone/subzone.
If multi-byte resolution for the colors is needed use index to address the byte where 0 means the MSB byte, 1 MSB+1 byte etc (Big endian).
CLASS1.IR
This is the IR code sent/received from common remote controls.
Undefined
A RC5 remote code. http://www.xs4all.nl/~sbp/knowledge/ir/sirc.htm Use the VSCP abstract remote format if possible.
A SONY remote code. http://www.xs4all.nl/~sbp/knowledge/ir/sirc.htm Use the VSCP abstract remote format if possible.
Packed LIRC codes code. LRC Codes are normally sent as 64-bit codes or even larger codes. Only codes with a length less then 56 bits (7-bytes) are supported by VSCP and the most significant byte of the LIRC code is not transferred. http://www.lirc.org/
Instead of sending codes that relates to a certain remote this format is general. And therefore more flexible
Instead of sending codes that relates to a certain remote this format is general. And therefore more flexible.
CLASS1.ONEWIRE
Carrier for the 1-wire API. Its often better to have a translation layer in between the 1-Wire bus and VSCP but to be able to control 1-Wire nodes fully this class has been defined.
General one wire.
A new 1-wire device is discovered. The 1-wire device id is in the data field layed out as a standard 64-bit 1-wire ID.
Command a 1-wire node to do a conversion.
Execute a 1-wire Read ROM command. The 1-wire device id is in the data field layed out as a standard 64-bit 1-wire ID.
Execute a 1-wire Match ROM command. The 1-wire device id is in the data field layed out as a standard 64-bit 1-wire ID.
Execute a 1-wire Skip ROM command.
Execute a 1-wire Search ROM command. The 1-wire device id is in the data field layed out as a standard 64-bit 1-wire ID.
Execute a 1-wire Conditional Search ROM command. The 1-wire device id is in the data field layed out as a standard 64-bit 1-wire ID.
Execute a 1-wire Program command. The 1-wire device id is in the data field layed out as a standard 64-bit 1-wire ID.
Execute a 1-wire Overdrive Skip ROM command.
Execute a 1-wire Overdrive Match ROM command. The 1-wire device id is in the data field layed out as a standard 64-bit 1-wire ID.
Execute a 1-wire Read Memory command. The 1-wire device id is in the data field.
Execute a 1-wire Write Memory command. The 1-wire device id is in the data field layed out as a standard 64-bit 1-wire ID.
CLASS1.X10
X10 Protocol functionality.
General event.
| Bit | Description |
| 0 | 0 |
| 1 | F/A |
| 2 | 1 |
| 3 | Dim amount |
| 4 | Dim amount |
| 5 | Dim amount |
| 6 | Dim amount |
| 7 | Dim amount |
Where F = Function A = Address Note that bit 0 always is zero.
| Bit | Description |
| 0 | Device Code |
| 1 | Device Code |
| 2 | Device Code |
| 3 | Device Code |
| 4 | House Code |
| 5 | House Code |
| 6 | House Code |
| 7 | House Code |
| Bit | Description |
| 0 | Function Code |
| 1 | Function Code |
| 2 | Function Code |
| 3 | Function Code |
| 4 | House Code |
| 5 | House Code |
| 6 | House Code |
| 7 | House Code |
where
| Bit | Description |
| 0 | 1 |
| 1 | 1 |
| 2 | 1 |
| 3 | 0 |
| 4 | House Code |
| 5 | House Code |
| 6 | House Code |
| 7 | House Code |
The unit code contains the encoded unit in the lower four bits.
The format is the same as for Type=1 except for the Node address in the first byte.
The format is the same as for Type=2 except for the Node address in the first byte.
Instead of sending house code P, Unit code 1 and then sending house code P, Command On, once can simply send house code P, unit code 1, command On, which will then be translated into 2 x10 messages.
CLASS1.LON
LON Works functionality.
General Event.
CLASS1.EIB
EIB functionality.
General Event.
CLASS1.SNAP
You can read more about the S.N.A.P. protocol at http://www.hth.com/snap/ or in this document http://www.hth.com/filelibrary/pdffiles/snap.pdf
General Event.
CLASS1.CBUS
Control and interface for the CBUS protocol
General event.
CLASS1.GPS
Control and interface for the GPS protocols (NMEA, SIRF etc)to VSCP
Typically one NMEA, SIRF etc frame with information needs to be translated to many VSCP events. It is possible to group the events together with
if preferred to hold the events together.
General event.
Position information as decimal Latitude + Longitude.
Number of satellites used.
CLASS1.WIRELESS
This class of events is used for wireless equipments such as cellular phones etc.
General event.
Event with ID for the GSM cell. Normally this is a 16-bit value but a 32-bit value is used in VSCP.
CLASS1.LOG
Logging functionality.
General Log event.
Message for Log. Several frames have to be sent for a event that take up more the five bytes which is the maximum for each frame. In this case the zero based index (byte 2) should be increased for each frame.
Start logging.
Stop logging.
Set level for logging.
CLASS1.LABORATORY
This class is intended for lab usage. No production device should use this event type.
General event.
CLASS1.LOCAL
This event type is for local defined events. It is thus possible to add user defined events here. In a public environment the risk for collisions with other devices that also use CLASS.LOCAL should be noted. It is good to make user events configurable in the device to give users a chance to avoid problems.
A class in Level II is described by a number between 512-65535. Instead of writing a number the class can be described as CLASS2.XXXX indicate a specific (XXXX in this case) Level II class. Also the form CLASS2.XXXX=yy can be used where yy is the numerical form.
Class definitions can be found in the header file vscp_class.h which is located located in the src/vscp/common folder. In the same folder vscp_type-h can be found which contains defines for types. Also the vscphelper.h/cpp files contains stuff that are useful for handling classes/types as a programmer.
CLASS2.PROTOCOL1
Class 512-1023 are reserved for events that should stay in the Level 2 network but that in all other aspects (the lower nine bits + type) are defined in the same manner as for Level I. For CLASS2.PROTOCOL1 the first 16 bytes of the data field is the GUID of the node the event is intended for.
This is used for translation in the VSCP daemon for instance where a level II client can send events that are automatically sent to the correct interface and is addressed to the correct device in question. To use this feature send events with the GUID of the i/f where the device is located when addressing is needed. The correct nickname is needed and it should be set in GUID byte 16.
An event with a class >= 512 but < 1024 will be sent to all Level II clients and to the correct i/f (the one that have the addressed GUID). A response form the device will go out as as a Level II event using the GUID of the interface but class will always have a value < 512 for a response event just as all events originating from a device.
Note that the LSB of an interface GUID is always the nickname id for a device interface.
Type = 6 (0x06) Set Nickname id for node. To set a new nickname for a node send the following event
Class = 512 = Level I Protocol, Type = 6 (0x06)
Set Nickname id for node.
Class = 0 = Level I Protocol, Type = 7 (0x07)
Nickname id accepted.
Note the the LSB of the GUID contains the nickname is in both cases but that this is of no use when the event is sent but should be used to verify that the correct node answered when the response is received.
Type = 9 (0x09) Read register. To read a register of a node send the following event
Class = 512 = Level I Protocol, Type = 9 (0x09)
Read register.
Class = 0 = Level I Protocol, Type=10 (0x0A)
Read/Write response.
CLASS2.PROTOCOL
For Level I events class=0 defines protocol control functionality. All events of this class are repeated at class=512 for use on Level II networks. The only difference is that the GUID is used instead of the Level I nickname.
This class defines protocol functionality for Level II. To simplify the handling of level II events, the data portion of the VSCP event can be considered as being made up of two parts. An 8-byte code portion (size of long integer) followed by a data portion if required. This is simply done to make processing level II events a little easier. The following events have been added to the level II control events to support configuration management.
General event.
Read a Level II register
Number of registers to read can also be restricted by the buffer size on the board (register 0×98). If this register is set to something else then 0 (default) this is the max size for data.
This means that buffer_size - 8 is maximum data bytes read.
Number of registers to write can also be restricted by the buffer size on the board (register 0×98). If this register is set to something else then 0 (default) this is the max size for data. This means that buffer_size - 24 is maximum data bytes written.
This is the response from a read and a write. Note that the data is returned in both cases and can be checked for validity.
This is a response from a node for which a copy of it’s configuration has been modified and is available for download.
Request a copy of a configuration from a node if a GUID is given or from any node willing to answer the request if no GUID given. This event is sent by a node who’s configuration had been remotely modified or a node that wants its configuration restored.
Request specific parameters from a node. The requested parameters are specified on the form
Response from a parameter request The requested parameters are received on the form
which gives the data for the parameters name1 . name-n
CLASS2.CONTROL
Level II Control functionality.
General event.
CLASS2.INFORMATION
Level II Information events.
General event.
This event is used for cards, RFID’s, iButtons and other identification devices. The event is generated when the token device is attached/detached to/from the system.
| Code | Description |
| 0 | Touched and released. |
| 1 | Touched. |
| 2 | Released. |
| 3-254 | Reserved. |
| 255 | Error. |
| Code | Description |
| 0 | Unknown Token. |
| 1 | iButton 64-bit token. |
| 2 | RFID Token. |
| 3 | Philips mifare®; RFID Token. |
| 4-8 | Reserved. |
| 9 | ID/Credit card. |
| 10-15 | Reserved. |
| 16 | Biometri device 256-bits . |
| 17 | Biometri device. 64-bits. |
| 18 | Bluetooth device. 48-bits |
| 19 | GSM IMEI code (International Mobile Equipment Identity) AA-BBBBBB-CCCCCC-D packed in 64 bits. http://en.wikipedia.org/wiki/IMEI |
| 20 | GSM IMSI code (International Mobile Subscriber Identity) packed in 64 bits. http://en.wikipedia.org/wiki/IMSI |
| 21-255 | Reserved. |
CLASS2.TEXT2SPEECH
This is an interface that translates text to speech
General event.
An implementor can design their own events in this class. Care must be taken not to cause conflicts by selecting types used by other implementors.
General event
CLASS2.DISPLAY
Level II specific display functionality. Also look at CLASS1.DISPLAY Class=102 (0x66) Display i/f - CLASS1.DISPLAY
CLASS2.VSCPD
This class is reserved for internal events used by the decision matrix mechanism of the VSCP daemon. Events of this type should never be visible on a physical bus.
General event.
Event is generated each loop in the DM or if no events is received every 100 ms (configurable value). No data is defined.
The machine/daemon is going to a pause state. No data is defined.
The machine/daemon is going from a pause state. No data is defined.
Event is generated each new second. No data is defined.
Event is generated each new minute. No data is defined.
Event is generated each new Hour. No data is defined.
Event is generated at 12:00 each day. No data is defined.
Event is generated at 00:00 each day. No data is defined.
Event is generated when a new week starts (config setting). No data is defined.
Event is generated when a new month starts. No data is defined.
Event is generated when a new quarter starts. No data is defined.
Event is generated when a new year starts. No data is defined.
Event is generated randomly over a minute as is sent once each minute. No data is defined.
Event is generated randomly over an hour and is sent once each hour. No data is defined.
Event is generated randomly over a day and is sent once each day. No data is defined.
Event is generated randomly over a week and is sent once each week. No data is defined.
Event is generated randomly over a month and is sent once each month. No data is defined.
Event is generated randomly over a year and is sent once each year. No data is defined.
Event is from calculated dusk. No data is defined.
Event is from calculated dawn. No data is defined.
The machine/daemon is starting up. This is the first event sent after a machine start up. Shutting down . No data is defined.
The machine/daemon is shutting down. This is the last event sent before a machine is shutting off. No data is defined.
A timer has been started.
Argument is timer id and start time for the timer.
Max timer value is about 49 days.
A timer has been paused.
Argument is timer id and time when timer was paused.
A timer has been restarted.
Argument is timer id and time when timer was restarted.
A timer has been stopped.
Argument is timer id and time when timer was stopped.
A timer has elapsed.
Argument is timer id.
The VSCP daemon is a server program that collects information from many drivers and lets clients collect this information over a TCP/IP interface. The daemon also has an internal scheduler that makes it possible to control different scenarios such as simple tasks like automatically turn on a group of lamps at a special time of the day to complex industrial control situations.
On Unix systems the daemon is a standard server application that is started in the background. It is possible also to compile it to start as a standard application if that is needed.
On Windows the daemon is available as a standard Windows service and as a standard application. Normally the standard application is not used, but for debugging and testing the application can be useful.
The daemon uses the CANAL interface to talk to drivers. This means that a driver normally is at VSCP Level I. However, a special driver can be implemented that just needs to implement three methods of the CANAL API (Open,Close and CanalGetLevel).
If the CanalGetLevel call returns CANAL_LEVEL_USES_TCPIP the daemon will assume this is a Level II driver that will use the TCP/IP interface of the daemon for all of its communication and therefore not communicate any further with it until it is time to close it down.
On Unix if you start vscpd from your shell prompt you will usually get back immediately to the prompt. Often people think that the program has died. But this is not an error. vscpd is a daemon. Daemons always run in background.
There is a video on you tube that takes you through some of the essentials of the VSCP Daemon. http://www.youtube.com/watch?v=9HY2br8ASvo
About The vscpservice is a WIN32 program that runs the VSCP daemon as a WIN32 service. This service is installed as a service by the setup program.
The VSCP Service works exactly the same as the daemon but runs as a standard service. This means the the control panel applet to handle windows services can be used to control how it behaves. The executable is called vscpservice.exe.
The service can be installed manually or with its own installation mechanism
Command line switches available are
| Switch | Description |
| no switch | Start the service |
| -i | Install the service |
| -u | Uninstall the service |
| -v | Display service information |
| -? or -h | Display information |
After installing the service the obvious location to control it is the control panel applet designed for this.
Manually installing the services If you want to install(de-install the service manually follow the steps below
The service can be installed with (this is done automatically by the WIN32 setup program)
vscpservice -i
Uninstalled with
vscpservice -u
More info about different switches and the available options can be retrieved by
vscpservice -? or vscpservice -h
The service has a variable called start at HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\vscpservice that should be set to 2 (autostart). It is set to 3 (manual) after installation so that you have the option to select which server/service to use.
This can also be done in the service applet
Configure the service to run on your machine This can also be done in the service applet
Where you select automatic if you want the service to start automatically.
The installation program installs the service and marks it to be run automatically. You have to add the user the service runs under manually.
vscpservice needs to be run as a user belonging to the administrator group. Therefore you should add a user “canald” and add this user to the administrators group.
You do this by selecting the Users and Passwords applet in the control panel
and adding the user.
After hitting next and entering a password (recommended) this window is shown
Select others and “Administrators”
After doing that you should open the service applet under the Administrative Tools in the control panel
You select the services applet here
and this window will show up
Right click the vscpservice item and select properties. Select the Logon tab
Mark “This account” and select the user you added above.
Now you can start the service in the service control applet.
Enabling VSCP ports on the XP firewall Normally the firewall is (and should be) enabled on Windows XP. This means that the port used by VSCP (9598) is blocked for both TCP and UDP traffic. You must enable this port in the firewall to make everything working.
The firewall settings is found in the control panel
Add the ports in the exceptions tab and select add port…
Allow the TCP port.
Allow the UDP port.
This is how it should look like when both the ports has been enabled.
The VSCP daemon (vscpd.exe in the installation folder) is run as an ordinary application (console application). The application will normally open a console window when run, in this window information is printed about what the daemon is working on and what command users issue.
To close the application just click on the close window icon in the top right corner of the console window.
The daemon needs a configuration file just as the service does. This configuration file should be in the file folder
\Documents and Settings\All users\Application Data\vscp
and it is called
vscpd.conf
normally the installation program will create a default file. The file is described here ??.
Some switches are available that control how the daemon is started.
| Short switch | Long switch | Description |
| -h | –help | Give information about available switches and what they do |
| -g | –gnu | Gives copyright information. |
| -v | –verbose | Give extra information useful for debugging |
| -c | –configpath | Tell where the program should look for the configuration file. Default is to look for this information in the general “application data” folder in a folder called vscp. Typically this is c:/documents and settings/all users/application data/vscp/vscpd.conf |
| -d | –debuglevel | Set the debug level (0-9). Higher value more output. Default=0 |
| -w | –hide | Hide the console window. Can be useful if running the app. in a “service way”. |
The daemon is the central program that do VSCP work on your box. It loads drivers for different devices and it present a TCP/IP interface from which it is possible to control the daemon and read/write events to devices.
On Linux the vscp daemon is started as any other daemon. Example startup scripts is available in the root folder.
| Switch | Description |
| -c | Path to configuration file. Default is /etc/vscp/vscpd.conf |
| -d | Debug level 0-9. Higher value means more information. Default is 0, no debug information. |
| -g | Displays copyright information. |
| -h | Displays help information. |
There are two configuration files that the daemon will load upon startup. /etc/vscp/vscpd.conf for general configuration parameters and /etc/vscp/variables.xml that hold persistent variable declarations. variables.xml should be writeable by the daemon.
When you type
make install
(or install one of the binary distributions) the daemon executable will be copies to /usr/local/bin and the configuration file will be copied to /etc/vscp and a default configuration file vscpd.conf will be copied to this folder. You should edit this file to fit your needs as it is described here 40_vscpd_config_file.
To actually install the daemon as a self starting server you need to create a startup script for it in /etc/init.d. Sample scripts are available in the root of the source tree.
If you want to debug the daemon there is wxTrace enablers in the controlobject.cpp file. Just uncomment any of the wxLog::AddTraceMask in the CControlObject::init method to get the debug events you want.
The full configuration file format is described here 40_vscpd_config_file.
In the <general> tab area settings that affect the behavior of the server in general is located.
udpport Use to set the port for the daemon UDP broadcasts. Default is 9598.
tcpport Use to set the port for the daemon TCP/IP interface. Default is 9598.
loglevel Loglevel 0-10 where 0 is no logging and 10 is debug mode. Default is 1.
Enable/disable daemon TCP/IP interface. Default is enabled.
udpif Enable/disable daemon UDP interface. Default is enabled.
canaldriver Enable/disable daemon driver interface. If disabled no drivers will be loaded. Default is enabled.
vscp Enable/disable daemon internal VSCP functionality. If disabled the server will no longer react on events like the High end server probe etc. Default is enabled.
dm Enable/disable the internal decision matrix of the daemon. Default is enabled.
guid Set the server GUID for the daemon. If not set here a GUID will be formed from the (first) MAC address of the machine the daemon runs on (on Linux needs to be run as root to get this) or if this fails the local IP address is used to form the GUID.
clientbuffersize This is the default buffer size (number of events) for all clients in the system. Everything from a driver to a TCP/IP user is regarded as a client. Default is 1024.
In the <remoteuser» tab area settings that affect users on that can access the daemon through the TCP/IP interface is located. Each user is defined between a <user>…</user> pair.
password Password ad an md5 checksum for this user. The mkvscppw can be user to generate passwords.
privilege Users can have privileges from 0-15 that allow them to do command that are equal to or less then the set privilege level. Enter a privilege level as 0-15 here or in symbolic form as admin (==15) or user (==4). Default is 4.
allowfrom This is a comma separated list with host addresses this user is allowed to log in to the server from. wild cards can be used to indicate “all”. This mean that
* .*.*.*”
means a user can log in from all remote machines.
194.*.*.*
that he/she can log on from all IP addresses that starts with 194 and son on. Default is all so iff you want to allow everyone to access your server you can skip this tag.
allowevent This is a comma separated list of events this user is allowed to send. The form is
class:type,class:type
wild-cards (*)can be used for both. This means that 20:*,30:* means that the user is allowed to send all events in class=20 and class=30. Default allows user to send all events.
mask Set the mask for incoming events to a client. The form is
priority="xxx" class="xxx" type="xxx" GUID="xxx">
The mask has a bit set for a binary digit that is of interest. Default is all is null == disabled.
priority="xxx" class="xxx" type="xxx" GUID="xxx">
Set the filter for incoming events to a client. The form is
class="xxx" type="xxx" GUID="xxx"
If a mask bit is set to one for a position then the filter bit must be equal to the bit of the incoming event for the client to get it.
In the <automation> tab area settings that affect the internal VSCP functionality behavior of the server is located.
zone This is the zone for the server 0-254.
subzone This is the sub-zone for the server 0-254.
longitude Longitude for place where daemon is located.
latitude Latitude for place where daemon is located.
time Enable/disable the periodic CLASS1.PROTOCOL, Type=1 (Segment Status Heartbeat) event to be sent from the daemon. The interval between events is set in seconds.
<time enable="true|false" interval="seconds" />
sunrise Enable/disable the CLASS1.INFORMATION, Type=44 (Sunrise) to be sent. Longitude and latitude must be set for this to work correctly.
<sunrise enable="true|false" />
sunset Enable/disable the CLASS1.INFORMATION, Type=45 (Sunset) to be sent. Longitude and latitude must be set for this to work correctly.
<sunset enable="true|false" />
heartbeat Enable/disable the CLASS1.INFORMATION, Type=9 (Node Heartbeat) to be sent. The interval between events is set in seconds.
<heartbeat enable="true|false" interval="seconds" />
In the <canaldriver> tab there are settings and information for loadable Level I drivers. Tags are located between <driver>…</driver> pairs.
Drivers are specified within a <vscpdriver> tag
This section holds information about each TCP/IP interface the daemon service. Normally no need to enter this information.
port The TCP/IP port to use for the interface. Default is 9598.
ipaddress IP address to use for interface.
macaddress MAC address for the Ethernet card where interface is. Entered as a six digit hex number on the form
aa:bb:cc:dd:ee:ff
This is documentation for the TCP interface of the daemon. The TCP/IP interface is a very powerful tool for users that allow for full control of the functionality of the daemon.
Originally the TCP/IP interface was added to allow for a more secure way to send events over TCP/IP links. This interface will have a fair better chance to work over wireless and other links that are hard to get to work reliable with UDP. Again it is not fully secure but just as we from time to time miss a character in our e-mails this can also happen here. *Secure enough* is the design criteria.
Just as with all clients that connect to the daemon each TCP client interface gets a GUID assigned to it. This GUID is assigned by setting it to the GUID the server was assigned at start up (in it’s configuration file 40_vscpd_config_file). This means that a client GUID has the following general form
yy yy yy yy yy yy yy yy yy yy yy yy client_id_MSB client_id_LSB 0 0
where the the assigned GUID is represented by yy and client_id is a system unique id for this client interface.
If no GUID is assigned in the configuration file the ethernet MAC address of the computer vscpd is running on using the VSCP Ethernet assignment method ( see Assigned GUID’s ). This results in a GUID of the following form
FF FF FF FF FF FF FF FE yy yy yy yy client_id_MSB client_id_LSB 0 0
where yy is the four most significant bytes of the Ethernet address and FF is decimal 255. Note that as the two least significant bytes of the MAC address is dropped there is a chance for duplicated GUID’s in a network with more then one machine with a network card from the same manufacturer. In this case set a unique GUID in the configuration file.
Another possibility is to use the IP address of the computer
FF FF FF FF FF FF FF FD yy yy yy yy client_id_MSB client_id_LSB 0 0
where yy is the IP address and FF is decimal 255.
The client_id is present in each VSCP event data structure and if a client uses more then one connection to the daemon this client_id can be used to detect events that it has sent itself when they arrive on the other open interfaces. This is typical used when the RCVLOOP command is issued where typically one interface is used to send events and another is used to receive events. By saving the client_id for the transmitting channel events that is sent on this channel can be detected on the receive channel.
When an event is sent from the driver interface ( a CANAL event ) the nickname id is stored in the LSB GUID byte (GUID[0]).
A node that needs a TCP connection to a server broadcasts High end server probe Class=0, Type = 27 (0x1B) on the segment and waits for High end server response Class=0, Type = 28 (0x1C) from one or more servers that serve the segment. If a suitable server has responded it can decide to connect to that server.
A daemon like the VSCP daemon can span multiple segments and a reply can therefore be received from a remote segment as well. This can be an advantage in some cases and unwanted in other cases. The server configuration should have control on how it is handled.
As an example: In this picture VSCP Works has been used to broadcast a High end server probe from the machine with IP address 192.168.1.8 - Data is 0,192,168,1,8 - The initial zero indicates that this is a TCP/IP based device.
The server that in this case is on the same machine have answered with a High end server response with data set to
80 00 08 01 A8 C0 25 7E
The first two bytes is the bit-filed that tells the Code for server capabilities. After that follows the server IP address (192.168.1.8) followed by the VSCP default port 9598.
In clear text, this server has a VSCP TCP/IP interface available at the standard port.
Other scenarios could be possible of course such as several servers responding and each of the servers supporting different capabilities.
The High end server probe and High end server response is described here Class=0 (0x00) VSCP Protocol Functionality - CLASS1.PROTOCOL
A node can react in its own manner on the response. It can connect to the server itself or wait for the server to connect to the node.
From version two a very flexible security schema has been introduced. Each user is defined with a list of parameters
username A name that this user is refereed to and known by. Always required for all users.
password A password this user must give to sign in. Always required for all users. Stored in configuration files as MD5 of password.
host-list A list with locations/computers/networks this user can access the daemon. Wild-card can be used so access from a single computer can be set as “192.168.1.8” but access for the hole subclass can be set as “192.168.1.*”.
access-rights This is the access level this user have. This is a 32-bit value where the lower four bits define a value 0-15 that defines a privilege value which gives access to different levels of commands. The upper part of the 32-bit value is a bit field with specific rights.
This is a driver that is started through the normal driver interface, but after the start it does all it’s communication through the TCP/IP interface. This is therefore actually a Level II driver as it does all it’s communication on the higher level. It can also use the variables the daemon gives access to through the TCP/IP interface for its own configuration and state.
A driver of this type needs a username/password pair and it should always be defined for every setup.
The Host-list for the user drivers to be used, should always be the Localhost to increase security.
Default Port: 9598
The VSCP TCP protocol is very much like the POP3 protocol.
For some commands there can be data in between the two lines. For instance the “VERS” command looks like this
send: ’VERS<CR><LF>’
received line 1: ’1,0,0<CR><LF>’
received line 2: ’+OK - <CR><LF>’
An additional mode will be added to the control interface of the VSCP daemon. This interface will make it possible to start stop drivers, get information about drivers, add/delete daemon decision matrix elements etc. This thus makes it possible to remotely control many aspects of the daemon and it’s control functionality.
The interface can also be used from applications such as a control panel widget under windows or a home automation server such as the Open Home Automation Server.
| Command | Privilege | From version | Description |
| + | 0 | 0.0.2 | Repeat the last command |
| NOOP | 0 | 0.0.1 | No operation. |
| QUIT | 0 | 0.0.1 | Close the connection. |
| USER | 0 | 0.0.1 | Username for login. |
| PASS | 0 | 0.0.1 | Password for login. |
| SEND | 4 | 0.0.1 | Send an event. |
| RETR | 2 | 0.0.1 | Retrieve one or several event(s). |
| RCVLOOP | 2 | 0.0.2 | Will retrieve events in an endless loop until the connection is closed by the client. |
| CDTA | 1 | 0.0.1 | Check if there are events to retrieve. |
| CLRA | 1 | 0.0.1 | Clear all events in in-queue. |
| STAT | 1 | 0.0.1 | Get statistics information. |
| INFO | 1 | 0.0.1 | Get status information. |
| CHID | 1 | 0.0.1 | Get channel ID. |
| SGID | 6 | 0.0.1 | Set GUID for channel. |
| GGID | 1 | 0.0.1 | Get GUID for channel. |
| VERS | 0 | 0.0.1 | Get CANAL/VSCP daemon version. |
| SFLT | 4 | 0.0.1 | Set incoming event filter. |
| SMSK | 4 | 0.0.1 | Set incoming event mask. |
| BIN1 | 4 | 0.0.1 | Enter binary mode 1. |
| BIN2 | 4 | 0.0.1 | Enter binary mode 2. |
| HELP | 1 | 0.0.2 | Give command help. |
| TEST | 15 | 0.0.2 | Do test sequence. Only used for debugging. |
| SHUTDOWN | 15 | 0.0.2 | Shutdown the daemon. |
| RESTART | 15 | 0.0.2 | Restart the daemon. |
| DRIVER | 15 | 0.0.2 | Driver manipulation. |
| FILE | 15 | 0.0.2 | File handling |
| UDP | 15 | 0.0.2 | UDP |
| REMOTE | 15 | 0.0.2 | User manipulation |
| INTERFACE | 15 | 0.0.2 | Interface manipulation. |
| DM | 15 | 0.0.2 | Decision Matrix manipulation. |
| CANMODE | 0 | 0.0.2 | Set CAN Mode. |
| VARIABLE | 15 | 0.2.9 | Variable handling. |
This operation does nothing. It just replies with ”+OK”.
Close the connection to the host.
Used to enter username for a password protected server.
Used on the following form:
USER username<CR><LF>
Used to enter username for a password protected server.
Used on the following form:
PASS password<cr><lf>
Restart the daemon. Must have highest privilege to be able to do this.
shutdown the daemon. Must have highest privilege to be able to do this.
With this command drivers can be handled. The argument defines which operation is performed.
Install a new driver. Full format is DRIVER install “path to driver package”. It’s possible to just install a driver temporarily or make it persistent to the system so it is loaded when the daemon starts. The driver package is a zip’ed file with a manifest file in XML format that tells where different components should go. The package system is also aware of the OHAS web framework.
Uninstall a driver that is currently installed.
Full format is DRIVER uninstall “drivername”/id.
Upgrade a driver that is currently installed.
Full format is DRIVER upgrade “drivername”/id.
Full format is DRIVER start “drivername”/id.
Full format is DRIVER stop “drivername”/id.
Full format is DRIVER re lode “drivername”/id.
With this command files can be handled. It is implemented to enable an administrator to handle driver and configuration files from a remote location and for client applications so they can dump collected data.
Show a directory listing for a folder given by the argument.
Copy a file from one location to another.
Move a file from one location to another.
Remote user manipulation.
List user(s). Full format is REMOTE list wild-card The list user command has the following format
user1<CR><LF>
user2<CR><LF>
...
usern<CR><LF>
+OK<CR><LF>
Add a user. Full format is REMOTE add
“username”,”MD5 password”,”from-host(s)”,”access-right-list”,”event-list”,”filter”,”mask”
Remove a user. Full format is REMOTE remove “username”
Set new privilege for a user. Full format is REMOTE privilege “username”,”access-right-list”
Set new privilege for a user. Full format is REMOTE password “username”,”MD5 for password”
Set locations user can connect from. Full format is REMOTE password “username”,”host-list”
Set list of events user can send. Full format is REMOTE password “username”,”event-list”
Set user filter. Full format is REMOTE password “username”,”filter”
Set user mask. Full format is REMOTE password “username”,”mask”
For the list interfaces command the daemon respond with interface_id1, type, interface_GUID1, interface_realname1<CR><LF>
interface_id2, type, interface_GUID2, interface_realname2<CR><LF>
...
interface_idn, type, interface_GUIDn, interface_realnamen<CR><LF>
+OK<CR><LF>
| Type | Description |
| 0 | unknown (should not see this) |
| 1 | Internal daemon client |
| 2 | CANAL Driver |
| 3 | TCP/IP Driver |
| 4 | TCP/IP Client |
Full format is interface close interface_GUID
Unique access to an interface can only be queried once for one interface. So two unique operations after each other de selects the first chosen interface before acquire the second.
Enable a decision matrix row. Argument is a comma separated list with DM row number(s) or “ALL” for all rows.
Disable a decision matrix row. Argument is a comma separated list with DM row number(s) or “ALL” for all rows.
Show a decision matrix row number. Argument is DM row number(s) or “ALL” for all rows.
The list command gives a list of the following format
enabled,from,to,weekday,time,mask,filter,index,zone,subzone,control-code,action-code,action-param,comment,trig-counter,error-counter<CR><LF>
....
+OK<CR><LF>
See the DM description in the VSCP specification for information about the content of the control code etc.
Add a decision matrix row. The add-command needs a parameter of the following format
enabled,from,to,weekday,time,mask,filter,index,zone,subzone,control-code,action-code,action-param,comment
See the list command ?? for a detailed description of the items.
Delete a decision matrix row.
Argument is a comma separated list with DM row number(s).
Resets all variables and read in persistent values.
Clear trig counter for a decision matrix row.
Argument is a comma separated list with DM row number(s) or “ALL” for all rows.
Clear error counter for a decision matrix row.
Argument is a comma separated list with DM row number(s) or “ALL” for all rows.
Save current decision matrix to a file. If no filename is given dm.xml is used with the path set to the configuration folder. Se ?? for decision matrix file format.
Load decision matrix from a file. If no filename is given dm.xml is used with the path set to the configuration folder. A path + filename can be used and this file will be used instead. The last agument is replace or add (default). replace - replaces the old decision matrix content with the new and the option add adds the decision matrix from the file at the end of the current decision matrix. Se ?? for decision matrix file format.
List all defined internal variables and there values or use a wild-card to list specific variables. all, *, *aaaa*, aaaa* or *aaaa
Set an internal variable value. If the variable is not already defined it is created. Argument is
“name of variable”, type, “persistence”, ”value”
type is the numerical variable type and is optional (default is string). persistance can be “true” or “false” for variable persistence and is optional (default is false). It is possible to proceed the variable with a ’$’to indicate persistent and ’@’ for an array. To just write a value use the format
“name of variable”„,”value”
The type of a variable can not be changed if it already exists. In this case remove it first.
Read a variables value. Arguments is “name of variable” The response is
or if the variable is not defined
The format for different variable types is as follows
| Variable Type | Format for returned value |
| String | String value |
| Boolean | true | false |
| Integer | Integer value |
| Long | Long value |
| Double | Double value |
| VSCP measurement | String representing the measurement. |
| VSCP event |
head,class,type,obid,time-stamp,GUID,data1,data2,data3....
|
| VSCP GUID | Standard GUID string format. FF:FF:FF:FF:FF:FF:FF:FF:FF:FF:FF:FF:FF:FF:FF:FF |
| VSCP event data | Comma separated list with decimal values. 1,2,3,4,5,6,7,8.... |
| VSCP event class | Integer value |
| VSCP event type | Integer value |
If the variable value is persistent the persistent value is reloaded. If not the variable is set to it’s default value.
This is a combination of read + reset doing them together in an atomic way.
Removes a variable. Argument is name of variable.
This is a combination of read + remove doing them together in an atomic way.
Get the length for a string variable. No effect for other variable types (returns 0 ).
Save persistent variables.
Output format from daemon for variable list/read commands is
"variable name",type,"persistence","value"<CR><LF>
...
+OK<CR><LF>
Persistence is presented as “true” or “false”.
Defined Types
| Code | Description |
| 0 | Unassigned (variable has not been used). |
| 1 | String format |
| 2 | Boolean e.g. true,false or 0,1 |
| 3 | Integer format |
| 4 | Long integer format |
| 5 | Floating point value (double) |
| 6 | VSCP measurement data see Data Coding. |
| 7 | VSCP Event e.g. priority=5 class=10,type=40,data=0×12,1,2,3,4,5 |
| 8 | GUID e.g. 00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00 |
| 9 | Data e.g. 1,2,3,4,5… |
| 10 | Class e.g. 10 |
| 11 | Type e.g. 22 |
| 12 | Time-stamp 2008-11-07 20:10.00 |
This is how the variables look like useing the variable lista all command in the TCP/IP interface.
Used on the following form:
send head,class,type,obid,time-stamp,GUID,data1,data2,data3....
The GUID is given on the form MSB-byte:MSB-byte-1:MSB-byte-2……. The GUID can also be given as ”-” in which case the GUID of the interface is used for the event. This GUID is constructed from the Ethernet MAC address and some other parameters to be globally unique.
If time-stamp is set to zero a time-stamp will be provided by the daemon. This time-stamp will be set as soon as the the line is parsed.
Note: obid is just a place holder here to have a similar line as the receive command and is used internally by the daemon as an interface index. The value you use will always be overwritten by the daemon.
Send a full GUID event
send 0,20,3,0,0,0:1:2:3:4:5:6:7:8:9:10:11:12:13:14:15,0,1,35<CR><LF>
Send Event. The example is the same as above but the GUID of the interface will be used.
send 0,20,3,0,0,-,0,1,35<CR><LF>
Both send the CLASS1.INFORMATION TYPE=3 ON event, for zone=1, subzone=35
It is possible to send Level I events to a specific interface. To do this use the Level II mirror Level I events ( Class=512-1023 VSCP Level II Level I events - CLASS2.LEVELI). This is events with class equal to 512 - 1023 which mirrors the Level I events but have the destination GUID in data bytes 0-15. Thees data-bytes is set to the interface (14 upper bits) and the node-id for the node one wants to communicate with is in GUID[0]. This event will be sent to the correct interface.
This command can be used to retrieve one or several events from the input queue. Events are returned as
head,class,type,obid,time-stamp,GUID,data0,data1,data2,...........
GUID with MSB first.
Used on the following form:
RETR 2<CR><LF>
0,20,3,0,0,FF:FF:FF:FF:FF:FF:FF:FE:0:5:93:140:2:32:0:1
0,20,4,0,0,FF:FF:FF:FF:FF:FF:FF:FE:0:5:93:140:2:32:0:1
+OK -
If no events are available in the queue
-OK - No event(s) available.
is received by the client.
VSCP Event originating from a CANAL driver have the nickname of the node in the LSB of the GUID ( GUID[0] ). The rest of the GUID is the GUID for the interface.
If no argument is given one event is fetched even if there are more in the queue.
If you try to receive more events then there is events in the buffer -OK will be returned after the available number of events have been retrived and been listed.
This command set the channel in a closed loop that only can be interrupted by a client closing the connection. The server will now send out an event as soon as it is reserved. This is done in a very effective way with high throughput. This means the client does not have to poll for new events. It just open one channel where it sends events and do control tasks and one channel where it receive evens.
To help in determining that the line is alive
+OK
is sent with a two second interval. The format for the event data is the same as for RETR command.
Some applications may not implement this feature and should output
[-OK - Command not implemented<CR><LF>]
to indicate this.
This command are used to check how many events are in the input queue waiting for retrieval.
Used on the following form:
CDTA<CR><LF>
8 <CR><LF>
+OK -<CR><LF>
This command are used to clear all events in the input queue.
Used on the following form:
CLRA<CR><LF>
+OK - All events cleared.<CR><LF>
Get interface statistics information. The returned format is
cntBusOff,cntBusWarnings,cntOverruns,cntReceiveData,cntReceiveFrames,cntTransmitData,cntTransmitFrames
Example:
STAT<CR><LF>
0,0,0,12356,56,9182,20<CR><LF>
+OK - <CR><LF>
This command fetch the status information for the interface. Returned format is
channel_status,lasterrorcode,lasterrorsubcode,lasterrorstr
Example:
INFO<CR><LF>
7812,12,0,"Overrun"<CR><LF>
+OK - <CR><LF>
Get the channel id for the communication channel. This is the same parameter as the obid which is present in events.
Example:
CHID<CR><LF>
1234<CR><LF>
+OK - <CR><LF>
Set the GUID for this channel. The GUID is given on the form
The format is:
SGID 0:1:2:3:4:5:6:7:8:9:10:11:12:13:14:15<CR><LF>
+OK - <CR><LF>
Get the GUID for this channel. The GUID is received on the form
0:1:2:3:4:5:6:7:8:9:10:11:12:13:14:15<CR><LF>
+OK - <CR><LF>
Get the current version for the daemon. The returned format is
major-version,minor-version,sub-minor-version
Set the incoming filter. The format is
filter-priority, filter-class, filter-type, filter-GUID
example
1,0x0000,0x0006,ff:ff:ff:ff:ff:ff:ff:01:00:00:00:00:00:00:00:00,0,0,0
Note: The GUID values always is given as hexadecimal values without a preceding “0x”.
Note: If you want to filter on nickname-id you should filter on GUID LSB byte.
Set the incoming mask. The format is
mask-priority, mask-class, mask-type, mask-GUID
example
1,0x0000,0x0006,ff:ff:ff:ff:ff:ff:ff:01:00:00:00:00:00:00:00:00,0,0,0
Note: that the GUID values always is given as hexadecimal values without a preceding “0x”.
Note: If you want to mask on nickname-id you should mask on GUID LSB byte.
Set the interface in CAN mode.
The only way to leave this mode is to terminate the session an start a new one. In CAN mode the daemon will not try to interpret VSCP control events and route them to the correct interface.
Enter binary mode. Note the two versions. BIN1 is a version that require the slave to request frames. The BIN2 version send outgoing frames to the slave directly when they arrive.
Constant for this mode is defined in canal.h and have “BINARY_” as prefix.
VSCP frame Send this frame to the sever to send an event. The server will respond with an error frame but the error indication will be positive for success. This is also the frame that will be returned after a read request if one or more events are available on the server.
Command frames Currently three commands are available
NOOP command frame The noop command do nothing. The server will return a positive error frame.
Read Request A read request will get a VSCP frame in return or an error frame. Typically indicating that there is no event(s) available.
Close Request The close request will return to the standard TCP/IP interface and if the intention is to close the TCP/IP interface a “QUIT” also have to be issued after this command.
This is decision matrix definitions for high level nodes like PC based or higher end embedded devices. The VSCP daemon is an example of this. No thoughts has been wasted on trying to minimize the use of resources like memory here as for the embedded decision matrix where size is of great importance.
Events described here are internal to the high-end node and is therefore not visible for the nodes on the bus. On the other hand all events on the bus are also feed to the DM and events can also be sent from an element in the DM.
Action parameter is one byte with user specified content
For a high end node level I events are handled by the Level II matrix below by the Level I events being mirrored to the Level II equivalents.
Action parameter can have any length. There is also no limit in the number of DM rows available even if there naturally is a practical system limit.
Each decision matrix row contains a number of elements. The row itself can be active or inactive and have a groupid that can be used to hold rows that performe a combined operation togehter. For the groupid any alphanumeric combination can be used.
mask The mask is a standard VSCP Level II mask. The bits that are ones in the mask specifies the bits that should be checked in the filter. There are masks for all parts of a VSCP Level II event such as priority, class, type, guid. Set one of these to zero if they are of now interest and to ones if they are or use bit combinations to create ranges of interest.
filter The mask is a standard VSCP Level II filter. The filter is combined with the mask. First the incoming event is masked this means all bits where the mask is zero is also set to zero in the event. The result is compared to the filter and if they are the same we have a match and the decision matrix row is triggered.
If you set the mask for a row to all ones and the filter equal to the event you are interested in that row will be triggered when that event is received by the daemon. In this case you can have the mask for priority, guid set to zero so that events with all priorities and from all units (with different GUID’s) will trigger the row. If you only are interested in events from a specific node. Set the guid part of the mask to ones (FF:FF:FF:FF:FF:FF:FF:FF:FF:FF:FF:FF:FF:FF:FF:FF) and the guid part for the filter to the nodes guid.
Another way one can use to match a single event is to set both filter and mask to the same value. This will have the same effect as the above method. Just remember that the mask should have a zero in a bit position for a don’t care and a one for a significant bit and the filter shuld have the corrosponding bit set to the value that is wanted and all other bits set to zero.
The truth table for all this looks like this:
| filter ^ event-bit | mask | result |
| 0 | 0 | 1 |
| 0 | 1 | 1 |
| 1 | 0 | 1 |
| 1 | 1 | 0 |
control This is the 32-bit control word specified in the specification. See ??. Bit 31 of the matrix is the same as the rows active/inactive status. Bit 30 is a bit that can be used to disable all decision matrix enteries below the row that has this bit set. Bit 5 that specifies that the index should be checked, bit 4 that the zone should be checked and bit 3 that the subzone should be checked are not used at the moment.
action This is a 32-bit action code that specifies which action should be executed if the row is trigered. Actions and there codes are described here software: decision matrix actions.
param The parameter is a text string that makes it possible to control how the action is performed. Before the action is performed the string is checked for escapes and this makes it possible to pass runtime information in an easy way. Escapes are defined here ??
comment Make your own comments of what the row is there for here.
allowed_from It is possible to define a date/time from which the action is allowed to be executed. Specify a time on ISO format as 1970-01-01 00:00:00. If not specified there is no restriction.
allowed_to It is possible to define a date/time upto which the action is allowed to be executed. Specify a time on ISO format as 2099-12-31 23:59:59. If not specified there is no restriction.
allowed_weekdays This tells which weeksdays the action is allowed to happen on. The format is mtwtfss each representing a weekday staring with Monday. Replace the weekday with a ’-’ to marks that day as not allowed to execute action on.
allowed_time Determines the time when the action is allwed to occur This method parse a string on the form YYYY:MM:DD HH:MM:SS. Both parts can be replaced with a ’*’ to indicate that it is a no care meaning that * * is for all dates and all time while * HH:MM:SS is for all dates but a specific times. Furter all elements such as YYYY, MM, DD, HH, MM, SS can be replaced with a * to represent a no care for each where it’s present. Each can also be given as a list seperated by ’/’ characters to indicate several choices. So YYYY:MM:DD HH:0/5/10;SS means the action should be performed on a specific date and hour on every full hour, five minutes past and ten minutes past.
When the daemon is started up the internal decision matrix is loaded. This is loaded from a file dm.xml from the configuration path. The format for the file is as follows
Each event that is received by the daemon is feed through the decision matrix. When the event is received it is placed on the DM input queue after passing an initial set of filter that removes events that are of no interest to the specific implementation.
The first event in the DM queue is then run through the matrix and each DM row is compared and if there is a match the action for that row is executed.
The daemon itself place some events on the DM queue. See Internal DM events below. For example the internal LOOP event is run through the matrix between every external event feed to the queue. The LOOP event will also be seen in the matrix when no other events are present. In this case a configuration value is used to set the time between two LOOP events (sleep time) if no other events arrive.
Actions can have long argument lists. If you are an end user don’t be scared by this. The setup of DM rows is done with program support and you fill in the values in a nice GUI.
The semicolon character ’;’ is used as a separator for arguments and if needed in an argument ”%;” should be used. Also % is a special character used for escapes and should be written as %%.
Variable substitution for parameters Action parameters are strings that are passed to actions and in that way can be used to configue the action to solve different problems. The actionstring can contain escape values which are replaced with real values before the action is performed. The following escapes are currently defined.
| Substitution | Description |
| %% | The character ’%’ |
| %; | The character ’;’. Semicolon is normally used to separates arguments of an action. |
| %cr | A carriage return. |
| %lf | A line feed. |
| %crlf | A carriage return + a line feed. |
| %tab | A tab. |
| %bell | A bell. |
| %event | A full event in the standard text form. |
| %event.class | The class for the event |
| %event.type | The type for the event. |
| %event.head | head of the event. |
| %event.priority | The priority for the event (from head). |
| %event.sizedata | The number of databytes the event have. |
| %event.data | All data-bytes as a comma separated list. If no data ’empty’ is set. |
| %event.data[n] | Data byte n. If no data ’empty’ is set. |
| %event.obid | obid of event. |
| %event.hardcoded | Hardcoded bit f head as 0/1. |
| %event.guid | GUID of the event. |
| %event.timestamp | Timestamp of the event. |
| %isodate | Date in ISO format YY-MM-DD |
| %isotime | Time in ISO form HH:MM:SS. |
| %mstime | Current time in milliseconds. |
| %hour | Current hour. |
| %minute | Current minute. |
| %second | Current second. |
| %week0 | Current week number (1-52(53)). Week starts with Sunday. |
| %week1 | Current week number (1-52(53)). Week starts with Monday. |
| %weektxt | Get week nane in textual short form. |
| %weektxtfull | Get week name in textual long form. |
| %month | Current month number (1-12). |
| %monthtxt | Get current month in textual short form. |
| %monthtxtfull | Get current month in textual long form. |
| %year | Current year. |
| %quarter | Current quarter(1-4). |
| %variable:variable_name | value of variable. |
| %path_config | Return the directory containing the system config files. Unix: /etc Windows: C:\Documents and Settings\All Users\Application Data Mac: /Library/Preferences |
| %path_datadir | Return the location of the applications global, i.e. not user-specific, data files. Unix: prefix/share/appname Windows: the directory where the executable file is located Mac: appname.app/Contents/SharedSupport bundle subdirectory |
| %path_documentsdir | Return the directory containing the current user’s (the account the daemon/server is run as) documents. Unix: ~ (the home directory) Windows: C:\Documents and Settings\username\Documents Mac: ~/Documents |
| %path_executable | Return the directory and the filename for the current executable. Unix: /usr/local/bin/exename Windows: C:\Programs\AppFolder\exename.exe Mac: /Programs/exename |
| %path_localdatadir | Return the location for application data files which are host-specific and can’t, or shouldn’t, be shared with the other machines. |
| %path_pluginsdir | Return the directory where the loadable modules (plugins) live. Unix: prefix/lib/appname Windows: the directory of the executable file Mac: appname.app/Contents/PlugIns bundle subdirectory |
| %path_resourcedir | Return the directory where the application resource files are located. The resources are the auxiliary data files needed for the application to run and include, for example, image and sound files it might use. Unix: prefix/share/appname Windows: the directory where the executable file is located Mac: appname.app/Contents/Resources bundle subdirectory |
| %path_tempdir | Return the directory for storing temporary files. |
| %path_userconfigdir | Return the directory for the user config files. Unix: ~ (the home directory) Windows: C:\Documents and Settings\username\Application Data Mac: ~/Library/Preferences |
| %path_userdatadir | Return the directory for the user-dependent application data files: Unix: ~/.appname Windows: C:\Documents and Settings\username\Application Data\appname Mac: ~/Library/Application Support/appname |
| %path_localdatadir | Return the directory for user data files which shouldn’t be shared with the other machines. |
| %toliveafter | Inserts Carpe diem quam minimum credula postero. |
Can perfectly be used as arguments for triggered external program execution.
Run external program. Run an external program. The daemon must have execute access rights to be able to launch the program.
Note that the semicolon symbol (’;’) is used internally and if it is part of a program argument %; should be written.
Example Start a new instance of notepad every minute at a specific date and time iterval.
http GET & POST This action access a given URL given by the action parameter. Can be used to write data to a remote datasource using web server scripts or simular.
Send event to remote VSCP daemon This action can be used to send an event to a remote vSCP daemon.
Store in variable Store data in a variable. The variable is named in the argument. If the variable is not available it is created.
example with integer: test_int,3,true,24000
example with string: test_string,1,true,"This is a string"
example with event: test_event,7,false,0,20,1,2,3,4,5,6
Add to a variable Add data to a variable. The variable is named in the argument.
If the variable does not exist it is created.
Subtract from a variable Subtract the data from a variable. The variable is named in the argument.
Multiply with a variable Multiply the data with a variable. The variable is named in the argument.
Divide the data with a variable Divide the data with a variable. The variable is named in the argument.
Check variable, set to true Check if variable is greater then a specified value and set some other variable to true if it is. The variable is named in the argument. If the variable is not available it is created. This action is typically used as a timer together with the send event conditional action to stop resends on timeout.
500;counter;flag
Will check if counter is greater then 500 and set flag to true when it is.
Check variable, set to false Check if variable is greater then a specified value and set some other variable to false if it is. The variable is named in the argument. If the variable is not available it is created. This action is typically used as a timer together with the send event conditional action to stop resends on timeout.
500;counter;flag
Will check if counter is greater then 500 and set flag to false when it is.
Send event Send event when another event is received.
Example This example send an event every ten seconds. It happens all weekdays during a specified time period from 1977-01-01 00:00:00 to 2099-12-31 23:59:59. The optional variable bSent is set to false when the event has been sent.
Send event conditional Send an event if a specfied variable is true.
This action is specified to make it possible to define DM entries that wait for a response form a node and resend a specified event a number of times until this response is received or a timeout occurred.
The variable is set to true by the action that initially sent the event that needs a reply. Typically this can be an event that trigges an ON event and expects a confirm. When the variable is true this action get triggered and if triggered by one of the internal timeevents it will start to send periodic events with a period equal to the internal time events period. The filter/mask should be set to trigger on some of the internal time events (loop, second, minute etc). This choice determines the interval between resend of events.
To get all this to work four DM rows are required.
Send event(s) from file This action sends event(s) from a named file.
The format for the XML file is
Write to file plain This action writes (appends) the substituted action argument string to a file. If the string should be written one on each row be sure to add %crlf for windows and %lf for Unix at the end of the actionstring.
Start a timer This action starts a timer identified by a numerical id that will count down from a specified time set in seconds. If the timer is already defined it will be reused and if active it will be reinitialized.
Stop a timer This action stops an active timer identified by a numerical id. If the timer does not exist or is inactive the action does nothing.
DM events is a special type of events that just are available in the DM loop and is generated internally by the daemon. Actions can be trigged by theese events.
The available events are:
The start and the end Date/time fields set the date/time range when the action is allowed to occur.
The action date set the date/time when the action should occur. This can be a one shot in which case the full date/time is filled in as in 2009-11-02 14:30:00 which will perform action at this time once if the start/end dates allow for that. To get repeats it is possible to use wild-cards. For example *-*-* 14:30:* (can also be written as * 14:30:*) will perform the operation every seconds from 14:30 to (but not including) 14:31 in the time range set by the start/end date/time range.
For repeating operation that is just dependent on time filter on the SECOND event so that this is the only event that trigger the row.
It is also possible to specify more then one of each element in the date/time by separating them with a slash. For example * 14:0/10/20/30/40/50:00 will do the action every ten minutes between two a clock and three a clock in the afternoon.
This functionality is provided as dll/dl with the package. It is not built into the daemon itself because of portability of the daemon itself.
Log to OHAS database The Open Home Automation Server have a database with many useful tables. This fuction writes data to this table in a standardized way.
Log to syslog/eventlog Send message to syslog server or to event log.
Send email First argument is receiver, second argument is subject, third argument is content.
Send SMS First argument is receiver, second argument is subject, third argument is content.
Access URL Only argument is URL.
All string substitution keywords are preceded with a %
Execute a program with argument when the ON event is received
Use substitutions for the arguments if event data should be transferred to the external program.
Execute heyu with argument at a specific time with constraints The external program heyu is used to control X10 devices. Here we want to turn on a group of lamps at 18:00 each night except during the summer. But never do this on Saturdays.
The daemon recognize two types of drivers. Level I drivers that confirm to the CANAL interface specification (??) and Level II drivers that use the higher end VSCP package format and full GUID.
This is just a .dll (Windows) or a .so (Linux) file with the CANAL interface exported. The interface is described here ??. Several CANAL driver comes with the VSCP & Friends package and information about them is here ??.
The good thing with the CANAL interface is that you can add the .dll or .so as a driver to canal daemon or use the dll directly from your own application.
To make a CANAL driver just create a dynamically linked library that export the CANAL interface. There are plenty of examples to use as a starting point for creating your own driver in the source tree at src/vscp/drivers/level1.
VSCP drivers or Level II drivers (fully described here ??) have two advantages over Level I drivers.
The ability to use the full GUID is good as there is no need for translation schema’s between the actual GUID and GUID’s used in interfaces. The node id is unique all over the world.
Letting the driver talk to the daemon over the TCP/IP interface if favorable in that it can do many things that previously has been impossible. The most exciting is that it can read and write variables (even create new ones if needed). This is the recommended way to use for configurations of a Level II driver. It means that configuration of all drivers can be made in one place (the daemon variable file), it gives a possibility to change runtime values in real time etc.
The level II driver is, just as the Level I driver, a dynamic link library with a specific set of exported methods. The exported methods are four of the methods from the CANAL interface and uses identical calling parameters and return values. There are some differences however noted below.
VSCP Works is a graphical toolbox for VSCP developers and users that is available for Linux and Windows. It can be used to update code in in-house nodes and nodes that sit at a location on the other side of the earth. It can be used to view events sent by a node, to configure a node using a high end interface and to simulate a node. New functionality will be added to VSCP Works as needs arise.
There is a three video walk through on Youtube that look at some of the essentials of VSCP Works
http://www.youtube.com/watch?v=uIMSG8ewvIw
http://www.youtube.com/watch?v=XenCTnhWJKM
http://www.youtube.com/watch?v=fd6cNc7iIzE
With the clinet window of VSCP works it is possible to open communication sessions either
Use the File/New VSCP Client window to open a new client window. You can now select a predefined interface to connect to or create a new session.
Below is a picture of how the window looks as on Ubuntu Linux
and on windows
FIXME
Remote interfaces have "TCP/IP:" in front of them and local interface or direct connections to CANAL drivers have "CANAL:" in front of them. The first type listed is the "Unconnected Mode" wich opens the window without a connection either to a remote server or a CANAL driver. This is here to able to investigate saved session data.
With the Add button a new TCP/IP or CANAL interface can be added. With the Edit button an available interface setting can be edited and last the remove button can be used to remove an interface.
The image below shows how the CANAL session edit window looks like on Ubunti Linux
and on windows
FIXME
Standard CANAL interface settings are available here.
A CANAL driver can have an internal XML file stored that describes the configuration string. If the driver has such information the button to the right of the configuration string can be used to run a wizard that helps in setting up both the flags value and the configuration string without needing to find the drivers documentation.
The image below shows how the remote TCP/IP server edit window looks like on Ubuntu Linux
and on windows
FIXME
For the remote TCP/IP interface some parameters need to be set also
The GUID for the interface to use on the server should be set to all zero for a standard server connection. In this case a sent event from our client will be sent on all other interfaces. If a valid interface GUID is entered here all send events will only go to devices on the selected interface. As a help to set the correct interface Get Interface button is available which will fetch all available interfaces from the server and allow a selection among them in a listbox.
Use the Set Filter button to set an incoming filter from this session. Only events that satisfy the filter/mask combination will be received.
Use the Test Connection button to test the connection to the server.
Selecting one of the interfaces and pressing OK (or dubbelclicking the line) opens the session window
Ubuntu Linux session window
and on windows
FIXME
The VSCP communication session window is divided into two areas. The upper area is the receive list and the lower area is the transmission list. Events that are received for this client is listed in the receive list also transmitted events are showed here. Further more it is possible to save the list to disk and later load it for investigation.
Currently only a chronological view is available (message log). Later another view will be added that makes it possible to see how many events of a certain class/type pair that has been received (message count).
By right clicking on the receive list some functionality will be available
Naturally it is also possible to clear the receive list window.
In the transmission object list rows are available that can be transmitted on the interface. It is possible to load and save transmission row sets which can be handy in many situations. It is possible to creat rows that is automatically transmitted with a selected period expressed in milliseconds and which continue to do so as long as they are active. It is also possible to create transmission row objects that automatically send out one or more event when another event is received.
On the right of the Transmission object list is a set of buttons
and on windows
FIXME
that control rows in the list.
The first button add a new transmission object. The second button edit a selected row and the third button delete a row.
The forth button load a transmission ro set from a file and the fifth button save the current rows.
On the right is a single button
and on windows
FIXME
This button is used to send the selected row(s). A single row can also be sent by double clicking on it but by selection several rows and clicking on this button the rows will be sent in sequence.
Some additional functionality is available by right clicking on the transmission object list.
The transmission row edit window looks like this on Ubuntu Linux
and like this on Windows
FIXME
Standard settings for events are available here. To use the GUID assigned by the daemon as the originator for the event set GUID to all zeros.
Data for the event is just a comma separated (mixed if needed) list of hexadecimal or decimal values.
Count is the number of sends of the transmission row.
Period is the time in milliseconds between automatically transmitted rows.
Trigger is a selected trigger among the available triggers.
The node configuration window can be used to set parameters for a device.
On Ubuntu Linux this window looks like this
In the above screenshot I have higlighted the registry entry that set the interval for temperature reports on the Kelvin module. To change it just click on the value and update. The operations are the same if the module is locally connected or located on the other side of the earth.
And on Windows
FIXME
Before this windows a session must be selected just as for the communication settings window. It is possible to connect through a local CANAL driver or a remote TCP/IP server. The only difference is that you need to enter a valid nickname id for a CANAL session before clicking update and that this id must be a full interface id with the least significant byte set to the nickname id of the device on that interface.
The update loads all registers from the device, both custom and standard. A clear text field is available at the bottom of the screen where data is presented in a more human suitable form. For instance the MDF URL is in clear text etc.
After updating the registers they can be edited and have threre register content changed and after that another click on the update button will write the content back.
The undo button can be used to reset all register to the content they had when the register session was opened.
In the clear register mode VSCP Work only recognize standard registers. It is therefore impossible for it to differentiate between read only and read/write registers in the custom register space. The MDF button address this.
After an update a click on the MDF button will automatically donwload the MDF file belonging to the device. It will then parse it and use the correct descriptions also for the custom registers. Further more now the abstractions can be used and entering register values can be done in a more human friendly way,
The nodeid field looks different when connected to a remote server as above or to a local CANAL driver. For a remote server the interface GUID is part of the id for the node and it tells which interface to talk to on the server. The least significant byte is the node id for the device connected to that interface. For a session connected directly to a CANAL device just the node-id is entered here.
To the right of the node-id field is a search button. It can be used to check that a node with the entered node-id really is present.
The connected/disconnected button tell if the connection to the server is active or not.
FIXME
FIXME
[[VSCP Works shortcuts]]
[[VSCP Works faq]]
The source repository is located at sourceforge. To get the full source tree use
The src tree holds PC and higher level code for Windows, PC and Mac.
The formware tree hold lower level firmware code for different hardware platforms
The docs tree contains the documentation you just read and other documentation.
The VSCP friends package have a lot of software API’s defined.
Open the VSCP Level II interface and let the driver connect to the local server using the server received username/password pair and log in to it. Parameters are a semicolon separated list with configuration parameters. The prefix is a prefix used before variable names on the form prefix_variablename that is used by the client when it get configuration data from the server. If the driver has no need to get configuration data it can be set to NULL.
It is very good if a driver fetch configuration data from the server instead of having it’s own configuration method such as reading from a file . First configuration data is in one place. Secondly configurations can be changed remotely from the client interface. If the prefix is different for drivers of the same sort several drivers of a kind can be used configured in totally different ways still fetching there configuration data from the same place.
Close the interface and instructs the driver to log of from the client TCP/IP interface.
A variable that has been changed by the client interface is reported back to the driver in this call.
The firmware code is locared under the firmware folder. Here are files for different hardware arcitectures and code common for alll of them in the common folder.
To port VSCP to a new platform is not very hard even if it involves some steps.
The most important files in the common folder is firmware_vscp.h ad firmware_vscp.c which implemenst the VSCP system on a speciic hardware. Today this code has been tested and compiles on common development tools for PIC (Microchip), AVR(Atmel), ARM(Str, Textas, Atmel, Luminary, NXP etc ) and other hardware platforms.