The VSCP software framework for level 1 devices provides several layers according to the VSCP specification.

• VSCP L1 Framework
• VSCP
• Framework
  • Core
  • Event Abstraction
  • Configuration Parameters
    • Common
    • Device Data
• VSCP L1 Bootloader
• VSCP CLI Tools
• Structure
• Getting Started
  • 1 Get The VSCP Framework To Your Project
    • 1.1 Possibility 1: Copy it
    • 1.2 Possibility 2: git submodule
    • 1.3 Possibility 3: PlatformIO
  • 2 Initialization Of The VSCP Framework
  • 3 Processing Of The VSCP Framework
  • 4 VSCP Framework Timer
  • 5 VSCP Transport Adaption
  • 6 Control The VSCP Lamp
  • 7 Connect The Initialization Button
  • 8 Persistent Memory
  • 9 Ready To Run
• Typical Infrastructure
• Issues, Ideas And Bugs
• License
• Contribution

The Very Simple Control Protocol (VSCP), an open and free protocol for IoT/m2m automation tasks.

More information can be found on the main site http://www.vscp.org

• The core functionality which has a built-in state machine to handle different use cases of the protocol and etc. (vscp_core.[ch]). Right now it supports every mandatory event and some minor optional ones.
• The decision matrix is handled separately (vscp_dm.[ch]). It contains the standard decision matrix, as described in the VSCP specification and contains an additional extension.
• The decision matrix next generation is supported too (vscp_dm_ng.[ch]). It eliminates the limitations of the standard decision matrix, incl. its extension.
• VSCP needs some mandatory persistent data, which can be modified during run time. This kind of data is in the persistent storage handled (vscp_ps.[ch]).
• The device specific data is handled separatly (vscp_dev_data.[ch]). You can decide whether this data shall be constant and configured during compile time or its loaded from persistent storage and could be modified during run time.
• The transport layer has the possibility to loop events back (vscp_transport.[ch]). This can be configured for each data (vscp_dev_data_config.[ch]), except the firmware version.
• Functionality can be configured for your needs (vscp_config.[ch]).
• Some utility functions are separated (vscp_util.[ch]) and used by different core modules or are maybe interested for the application too.
• Log functionaly is provided for debugging purposes (vscp_logger.[ch]).

The framework is independent of the hardware and the used operating system. To achieve independence all of the following layers have to be adapted to the system. This is supported by templates, which contains all necessary functions with nearly empty bodys.

The following modules have to be adapted for your needs, because it depends on the hardware, the operating system or how VSCP is integrated into your software:

• Transport adapter (vscp_tp_adapter.c)
• Timer driver (vscp_timer.c)
• Persistent memory access driver (vscp_ps_access.c)
• Action module, used by the decision matrix (standard, extension and next generation) (vscp_action.c)
• Application register access (vscp_app_reg.c)
• Callout functions, lamp handling and etc. (vscp_portable.c)

Templates exists for all of them, which makes it much easier to adapt it and less time. See in the templates folder.

Using only the core, you have to assemble the VSCP events by yourself. If you want to deal only with parameter, which are VSCP independent, use the next upper layer, the event abstraction modules.

The following configuration parameters can be enable/disable/set in the

vscp_config_overwrite.h

The following device data can be enable/disable/set in the

vscp_dev_data_config_overwrite.h

A generic VSCP L1 bootloader: https://github.com/BlueAndi/vscp-bootloader

Some tools to maintain VSCP via command line interface: https://github.com/BlueAndi/vscp-cli-tools

+---doc                 (Documentation)
|   +---doxfiles        (Doxygen related files)
|   \---html            (Doxygen generated documentation in HTML)
+---examples            (Examples which are showing how to use the VSCP framework)
|   +---arm             (Examples with ARM based microcontrollers)
|   \---avr             (Examples with Atmel AVR microcontrollers)
|---src                 (VSCP framework)
|   \---events          (These modules are using the VSCP core to send CLASS1 dedicated events)
+---templates           (Templates of the files, which the user shall adapt to its needs)
|---test                (Test of the VSCP framework)
\---tools               (General tools, used by examples and projects)
    \---xslt            (XML transformation processor)

This part shows you how to get the VSCP framework working in a "minimal" way:

1. Get the VSCP framework to your project
2. Initialization of the VSCP framework
3. Processing of the VSCP framework
4. VSCP framework timer
5. VSCP transport adaption
6. Control the VSCP lamp
7. Connect the initialization button
8. Persistent memory
9. Ready to run

There are 3 possible integrations listed, there may be more of course.

1. Copy or link the VSCP framework (./src and ./src/events) to your project.
2. Copy (!!do not link!!) all necessary template files (./templates) to your project. Recommended is a sub-directory "vscp_user".
3. Update your makefile or your project configuration.

Initial add it.

git submodule add https://github.com/BlueAndi/vscp-framework

Later update it.

git submodule update --remote

Add vscp-framework with the required version to the platformio.ini configuration. Find more informations in the PlatformIO documentation.

Example:

    lib_deps =
        vscp-framework @ 2.0.0

The VSCP framework has to be initialized, before any function is used. This is simply done by calling the function vscp_core_init() during start-up.

The VSCP framework has to be called periodically to be able to react on incoming events. Call the process routine vscp_core_process() in a constant cyclic period. The period should be lower or equal than 100 ms, but depends on several factors, like the bitrate on the choosen communication bus, the event load on the bus and etc.

The process routine handle all received VSCP events.

VSCP specifies several timing behaviour in different use cases. Therefore the framework needs some timers to achieve it.

Because timer are usually hardware and software dependend, they have to be implemented by you for your needs. Adapt the vscp_timer.c template file. Find all necessary informations in the module.

The timer handling can be processed by calling vscp_timer_process() in the same or in a different task as vscp_core_process() is called. If a different task calls it, don't forget to make the timer functions reentrant!

Because the VSCP timer module needs to know the period of processing the timers, you have to call it with the period time in ms as parameter, e.g. vscp_timer_process(1000);

Call the timer processing routine equal or lower than 1 s.

Note, that never call vscp_process() with a lower period, than vscp_timer_process(). Because vscp_process() reacts on timer timeouts and vscp_timer_process() decrease only the timers, but doesn't do more.

Now its time to connect the VSCP framework to the communication bus. This can be done by implementing the transport adapter in the vscp_tp_adapter.c template file.

To see that something is happen on your embedded device, next step is to control the VSCP lamp (in most cases a LED). Update the function vscp_portable_setLampState() in the vscp_portable.c module.

According to the VSCP specification, every embedded device should have a button to start the segment initialization. Hopefully you have one right now :-) and if it is pressed, call the function vscp_core_startNodeSegmentInit() in the vscp_core.c module.

It is important that the VSCP framework can store data in a persistent memory, e.g. an EEPROM. Implement in the vscp_ps_access.c module the low level access to the persistent memory. Its quite easy, because only byte access functions are used, so you have one read and one write function to adapt.

Now the minimal sub set is done and your node hopefully starts up with a nickname discovery.

Have fun!

If you have further ideas or you found some bugs, great! Create a issue or if you are able and willing to fix it by yourself, clone the repository and create a pull request.

The whole source code is published under the MIT license.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, shall be licensed as above, without any additional terms or conditions.