Permalink
Fetching contributors…
Cannot retrieve contributors at this time
255 lines (196 sloc) 18.9 KB

VSCP L1 Framework

License Release Coverity Scan Build Status Build Status

  1. VSCP
  2. Framework
  3. Structure
  4. Getting started
  5. Bootloader
  6. Typical infrastructure
  7. Issues, Ideas and bugs
  8. License

VSCP

Logo

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

Framework

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

Core

core-diagram

  • 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.

Event abstraction

core-diagram

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.

Configuration parameters

Common

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

vscp_config_overwrite.h
Feature switch Default Description
VSCP_CONFIG_ENABLE_LOGGER disabled Enable log functionality (CLASS1.Log). Use the macros in vscp_logger.h to send log messages.
VSCP_CONFIG_SILENT_NODE disabled Silent node configuration, which is used for e. g. RS-485 connections. 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.
VSCP_CONFIG_HARD_CODED_NODE disabled Hard-coded node (fixed nickname id)
VSCP_CONFIG_HEARTBEAT_SUPPORT_SEGMENT disabled Enable segment controller heartbeat support for nodes.
VSCP_CONFIG_HEARTBEAT_NODE enabled Enable sending node heartbeat (mandatory since 2015-09-10).
VSCP_CONFIG_IDLE_CALLOUT disabled Enable idle callout. If VSCP stops working and enters idle state, the application will be notified.
VSCP_CONFIG_ERROR_CALLOUT disabled Enable error callout. If VSCP stops working and enters error state, the application will be notified.
VSCP_CONFIG_BOOT_LOADER_SUPPORTED disabled Enable boot loader support.
VSCP_CONFIG_ENABLE_DM enabled Enable decision matrix (standard).
VSCP_CONFIG_DM_PAGED_FEATURE disabled Enable decision matrix special paged feature.
VSCP_CONFIG_ENABLE_DM_EXTENSION disabled Enable the decision matrix extension to be able to compare to a configureable zone/sub-zone and event parameters.
VSCP_CONFIG_ENABLE_DM_NEXT_GENERATION disabled Enable the decision matrix next generation.
VSCP_CONFIG_ENABLE_LOOPBACK disabled Enable a loopback for all sent VSCP events. This feature is interesting to invoke decision matrix actions by own sent VSCP events.
VSCP_CONFIG_ENABLE_SEGMENT_TIME_CALLOUT disabled Enable a time update callout for every received segment master heartbeat, in case the event contains a new time since epoch.
VSCP_CONFIG_PROTOCOL_EVENT_NOTIFICATION disabled Usually the core handles all protocol class events and they are not forwarded to the application. Enable this to forward the events as well. If application handles the event, the core won't handle it. Attention: Handling events which the core is waiting for can cause bad behaviour.
VSCP_CONFIG_ENABLE_CUSTOM_HEARTBEAT disabled By default a heartbeat is sent, with 0 as user data and without extended data. If you need a custom heartbeat and able to define user and extended data by yourself, enable this.
Parameter Default Description
VSCP_CONFIG_NODE_SEGMENT_INIT_TIMEOUT 5000 Timeout in ms for the node segment initialization.
VSCP_CONFIG_PROBE_ACK_TIMEOUT 2000 Timeout in ms for the probe acknowledge.
VSCP_CONFIG_MULTI_MSG_TIMEOUT 1000 Timeout in ms to observe multi-message handling.
VSCP_CONFIG_HEARTBEAT_NODE_PERIOD 30000 Node heartbeat period in ms (recommended 30s - 60s).
VSCP_CONFIG_DM_PAGE 1 Decision matrix location: First page of the decision matrix.
VSCP_CONFIG_DM_OFFSET 0 Decision matrix location: Offset in the first page of the decision matrix.
VSCP_CONFIG_DM_ROWS 10 Number of decision matrix rows.
VSCP_CONFIG_DM_NG_PAGE 2 Decision matrix next generation: Location in the application register space. Note that the dm ng always starts at the begin of the page! This design decision was just for simplification, nothing else.
VSCP_CONFIG_DM_NG_RULE_SET_SIZE 80 Decision matrix next generation: Maximum size in bytes of a rule set.
VSCP_CONFIG_LOOPBACK_STORAGE_NUM 4 Number of messages in the loopback cyclic buffer. Note, that if you want to store up to 3 events, you have to configure 4, because of the technical implementation of the cyclic buffer.

Device data

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

vscp_dev_data_config_overwrite.h
Feature switch Default Description
VSCP_DEV_DATA_CONFIG_ENABLE_FAMILY_CODE enabled Enable the support of the family code.
VSCP_DEV_DATA_CONFIG_ENABLE_GUID_STORAGE_PS disabled Enable this define to load the GUID from persistent storage.
VSCP_DEV_DATA_CONFIG_ENABLE_GUID_STORAGE_EXT disabled Enable this define to load the GUID from external storage, e.g. from MCU GUID.
VSCP_DEV_DATA_CONFIG_ENABLE_NODE_ZONE_STORAGE_PS disabled Enable this define to load the node zone from persistent storage.
VSCP_DEV_DATA_CONFIG_ENABLE_NODE_SUB_ZONE_STORAGE_PS disabled Enable this define to load the node sub-zone from persistent storage.
VSCP_DEV_DATA_CONFIG_ENABLE_MANUFACTURER_DEV_ID_STORAGE_PS disabled Enable this define to load the manufacturer device id from persistent storage.
VSCP_DEV_DATA_CONFIG_ENABLE_MANUFACTURER_SUB_DEV_ID_STORAGE_PS disabled Enable this define to load the manufacturer sub device id from persistent storage.
VSCP_DEV_DATA_CONFIG_ENABLE_MDF_URL_STORAGE_PS disabled Enable this define to load the MDF URL from persistent storage.
VSCP_DEV_DATA_CONFIG_ENABLE_STD_DEV_FAMILY_CODE_STORAGE_PS disabled Enable this define to load the standard device family code from persistent storage. Note, that the feature family code has to be enabled, otherwise this define won't be considered.
VSCP_DEV_DATA_CONFIG_ENABLE_STD_DEV_TYPE_STORAGE_PS disabled Enable this define to load the standard device type from persistent storage. Note, that the feature family code has to be enabled, otherwise this define won't be considered.
Parameter Default Description
VSCP_DEV_DATA_CONFIG_NODE_GUID 00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00 Node GUID
VSCP_DEV_DATA_CONFIG_NODE_ZONE 0xff Node zone. Note, 0xff means all zones.
VSCP_DEV_DATA_CONFIG_NODE_SUB_ZONE 0xff Node sub-zone. Note, 0xff means all sub zones.
VSCP_DEV_DATA_CONFIG_MANUFACTURER_ID 0x0000 Manufacturer id (0x0000 means unknown)
VSCP_DEV_DATA_CONFIG_MANUFACTURER_DEVICE_ID 0x00000000 Manufacturer device id
VSCP_DEV_DATA_CONFIG_MANUFACTURER_SUB_DEVICE_ID 0x00000000 Manufacturer sub device id
VSCP_DEV_DATA_CONFIG_MDF_URL empty MDF URL (only 32 characters are allowed!), without "http://" which is implied Note, the encoding is UTF-8!
VSCP_DEV_DATA_CONFIG_VERSION_MAJOR 0 Major firmware version (format: major.minor.sub-minor)
VSCP_DEV_DATA_CONFIG_VERSION_MINOR 1 Minor firmware version (format: major.minor.sub-minor)
VSCP_DEV_DATA_CONFIG_VERSION_SUB_MINOR 0 Sub-minor firmware version (format: major.minor.sub-minor)
VSCP_DEV_DATA_CONFIG_STANDARD_DEVICE_FAMILY_CODE 0x00000000 Standard device family code.
VSCP_DEV_DATA_CONFIG_STANDARD_DEVICE_TYPE 0x00000000 Standard device type.

Structure

+---common              (Common sourcecode, used for examples and projects)
|   +---avr             (Common sourcecode for Atmel AVR microcontrollers)
|   \---pc              (Common sourcecode for PC)
+---examples            (Examples which are showing how to use the VSCP framework)
|   +---arm             (Examples with ARM based microcontrollers)
|   +---avr             (Examples with Atmel AVR microcontrollers)
|   \---pc              (PC example for windows and linux)
+---projects            (Projects)
|   +---avr             (Projects with Atmel AVR microcontrollers)
|   \---pc              (PC projects)
+---tools               (General tools, used by examples and projects)
|   \---xslt            (XML transformation processor)
\---vscp                (VSCP framework)
    +---doc             (Documentation)
    |   +---doxfiles    (Doxygen related files)
    |   \---html        (Doxygen generated documentation in HTML)
    +---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)

Getting started

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

  1. Copy 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

Copy the VSCP framework to your project

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

Initialization of the VSCP framework

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.

Processing of the VSCP framework

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 framework timer

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.

VSCP transport adaption

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.

Control the VSCP lamp

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.

Connect the initialization button

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.

Persistent memory

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.

Ready to run

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

Have fun!

Typical infrastructure

typical-infrastructure

Issues, Ideas and bugs

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.

License

The whole source code is published under the MIT license.