Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.
Awesome Lists | Featured Topics | Projects
https://github.com/blueandi/vscp-framework

Very Simple Control Protocol (VSCP) Level 1 Framework
https://github.com/blueandi/vscp-framework
automation c99 homeautomation vscp vscp-framework
Last synced: 29 days ago
JSON representation
Very Simple Control Protocol (VSCP) Level 1 Framework
Host: GitHub
URL: https://github.com/blueandi/vscp-framework
Owner: BlueAndi
License: other
Created: 2015-01-06T13:27:49.000Z (almost 10 years ago)
Default Branch: master
Last Pushed: 2024-08-23T13:10:48.000Z (3 months ago)
Last Synced: 2024-10-06T12:04:53.530Z (about 1 month ago)
Topics: automation, c99, homeautomation, vscp, vscp-framework
Language: C
Homepage:
Size: 47.4 MB
Stars: 12
Watchers: 12
Forks: 8
Open Issues: 1
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.md
Awesome Lists containing this project

README

        # VSCP L1 Framework

[![License](https://img.shields.io/badge/license-MIT-blue.svg)](http://choosealicense.com/licenses/mit/)

[![Repo Status](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active)

[![Release](https://img.shields.io/github/release/BlueAndi/vscp-framework.svg)](https://github.com/BlueAndi/vscp-framework/releases)

[![Coverity Scan Build Status](https://img.shields.io/coverity/scan/4825.svg)](https://scan.coverity.com/projects/4825?tab=overview)

[![Build Status](https://github.com/BlueAndi/vscp-framework/workflows/CI/badge.svg?branch=master)](https://github.com/BlueAndi/vscp-framework/actions?query=workflow%3ACI)

The VSCP software framework for level 1 devices provides several layers according to the [VSCP specification](https://docs.vscp.org/spec/latest).

- [VSCP L1 Framework](#vscp-l1-framework)

- [VSCP](#vscp)

- [Framework](#framework)

  - [Core](#core)

  - [Event Abstraction](#event-abstraction)

  - [Configuration Parameters](#configuration-parameters)

    - [Common](#common)

    - [Device Data](#device-data)

- [VSCP L1 Bootloader](#vscp-l1-bootloader)

- [VSCP CLI Tools](#vscp-cli-tools)

- [Structure](#structure)

- [Getting Started](#getting-started)

  - [1 Get The VSCP Framework To Your Project](#1-get-the-vscp-framework-to-your-project)

    - [1.1 Possibility 1: Copy it](#11-possibility-1-copy-it)

    - [1.2 Possibility 2: git submodule](#12-possibility-2-git-submodule)

    - [1.3 Possibility 3: PlatformIO](#13-possibility-3-platformio)

  - [2 Initialization Of The VSCP Framework](#2-initialization-of-the-vscp-framework)

  - [3 Processing Of The VSCP Framework](#3-processing-of-the-vscp-framework)

  - [4 VSCP Framework Timer](#4-vscp-framework-timer)

  - [5 VSCP Transport Adaption](#5-vscp-transport-adaption)

  - [6 Control The VSCP Lamp](#6-control-the-vscp-lamp)

  - [7 Connect The Initialization Button](#7-connect-the-initialization-button)

  - [8 Persistent Memory](#8-persistent-memory)

  - [9 Ready To Run](#9-ready-to-run)

- [Typical Infrastructure](#typical-infrastructure)

- [Issues, Ideas And Bugs](#issues-ideas-and-bugs)

- [License](#license)

- [Contribution](#contribution)

# VSCP



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

## Core

![core-diagram](http://www.plantuml.com/plantuml/proxy?cache=no&src=https://raw.githubusercontent.com/BlueAndi/vscp-framework/master/doc/doxfiles/vscp_modules.plantuml)

* 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](http://www.plantuml.com/plantuml/proxy?cache=no&src=https://raw.githubusercontent.com/BlueAndi/vscp-framework/master/doc/doxfiles/vscp_event_modules.plantuml)

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._{|

| _{VSCP\_CONFIG\_START\_NODE\_PROBE\_NICKNAME_{| _{1_{| _{Number to start probing nickname from._|}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}

### 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}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}}