- Available for: Linux, Windows
- Driver Linux: libvscpl2drv-tcpipsrv.so
- Driver Windows: vscpl2drv-tcpipsrv.dll
The tcp/ip driver act as a tcp/ip server for the VSCP tcp/ip link protocol. Users or IoT/m2m devices with different privileges and rights can connect to the exported interface and send/receive VSCP events.
The VSCP tcp/ip link protocol is described here.
With the simple interface the driver uses (described here) it is also possible to use it with other software as a component.
You can install the driver using the debian package with
sudo apt install ./vscpl2drv-tcpipsrv_x.y.z.deb
the driver will be installed to /var/lib/vscp/drivers/level2
After installing the driver you need to add it to the vscpd.conf file (/etc/vscp/vscpd.conf). Se the configuration section below for how to do this.
You also need to set up a configuration file for the driver itself. If you don't need to dynamically edit the content of this file a good and safe location for it is in the /etc/vscp/ folder alongside the VSCP daemon configuration file.
If you need to do dynamic configuration a good place to put the file is in the /var/vscp/lib/vscp/vscpd/ folder or maybe a subfolder here. Make sure the vscp user can read/write the location.
A sample configuration file is make available in /usr/share/vscpl2drv-tcpipsrv.so after installation.
tbd
- git clone --recurse-submodules -j8 https://github.com/grodansparadis/vscp.git
- git clone --recurse-submodules -j8 https://github.com/grodansparadis/vscpl2drv-tcpipsrv.git development
- sudo apt install pandoc (comment: optional)
- sudo apt install build-essential
- sudo apt install cmake
- sudo apt install libexpat-dev
- sudo apt install libssl-dev
- sudo apt install rpm (comment: only if you want to create install packages)
- cd vscpl2drv-tcpipsrv
- mkdir build
- cd build
- cmake ..
- make
- make install
- sudo cpack .. (comment: only if you want to create install packages)
Install of pandoc is only needed if man pages needs to be rebuilt. This is normally already done and available in the repository.
You need the vcpkg package manager on windows. Install it with
git clone https://github.com/microsoft/vcpkg.git
then go into the folder
cd vcpkg
Run the vcpkg bootstrapper command
bootstrap-vcpkg.bat
The process is described in detail here
To integrate with Visual Studio run
vcpkg integrate install
Install the required libs
vcpkg install pthread:x64-windows
vcpkg install expat:x64-windows
vcpkg install openssl:x64-windows
Full usage is describe here
You need to checkout the VSCP main repository code in addition to the driver repository. You do this with
git clone https://github.com/grodansparadis/vscp.git
cd vscp
git checkout development
and the vscpl2drv-tcpipsrv code
git clone https://github.com/grodansparadis/vscpl2drv-tcpipsrv.git
If you check out both at the same directory level the -DVSCP_PATH=path-vscp-repository in next step is not needed.
Build as usual but use
cd vscpl2drv-tcpipsrv
mkdir build
cd build
cmake .. -CMAKE_BUILD_TYPE=Release|Debug -DCMAKE_TOOLCHAIN_FILE=E:\src\vcpkg\scripts\buildsystems\vcpkg.cmake -DVSCP_PATH=path-vscp-repository
The CMAKE_TOOLCHAIN_FILE path may be different in your case
Note that Release|Debug should be either Release or Debug
The windows build files can now be found in the build folder and all needed files to run the project can after build - be found in build/release or build/Debug depending on CMAKE_BUILD_TYPE setting.
Building and configuration is simplified with VS Code installed. Configure/build/run can be done (se lower toolbar). Using VS Code it ,ay be useful to add
"cmake.configureSettings": {
"CMAKE_BUILD_TYPE": "${buildType}"
}
to your settings.json file.
To build at the command prompt use
msbuild vscp-works-qt.sln
Note that you must have a developer command prompt
Install NSIS from this site.
Run
cpack ...
in the build folder.
The VSCP daemon configuration is (normally) located at /etc/vscp/vscpd.conf. To use the libvscpl2drv-tcpipsrv.so driver there must be an entry in the level2 driver section of this file
"drivers": {
"level2": [
The format is
{
"enable" : true,
"name" : "tcpip-srv",
"path-driver" : "/var/lib/vscp/drivers/level2/libvscpl2drv-tcpipsrv.so",
"path-config" : "/etc/vscp/tcpipsrv.json",
"guid" : "FF:FF:FF:FF:FF:FF:FF:F5:02:88:88:00:00:00:00:01",
"mqtt": {
"bind": "",
"host": "test.mqtt.org",
"port": 1883,
"mqtt-options": {
"tcp-nodelay": true,
"protocol-version": 311,
"receive-maximum": 20,
"send-maximum": 20,
"ssl-ctx-with-defaults": 0,
"tls-ocsp-required": 0,
"tls-use-os-certs": 0
},
"user": "vscp",
"password": "secret",
"clientid": "the-vscp-daemon tcpipsrv driver",
"publish-format": "json",
"subscribe-format": "auto",
"qos": 1,
"bcleansession": false,
"bretain": false,
"keepalive": 60,
"bjsonmeasurementblock": true,
"reconnect": {
"delay": 2,
"delay-max": 10,
"exponential-backoff": false
},
"tls": {
"cafile": "",
"capath": "",
"certfile": "",
"keyfile": "",
"pwkeyfile": "",
"no-hostname-checking": true,
"cert-reqs": 0,
"version": "",
"ciphers": "",
"psk": "",
"psk-identity": ""
},
"will": {
"topic": "vscp-daemon/{{srvguid}}/will",
"qos": 1,
"retain": true,
"payload": "VSCP Daemon is down"
},
"subscribe" : [
{
"topic": "vscp/tcpipsrv/{{guid}}/#",
"qos": 0,
"v5-options": 0,
"format": "auto"
}
],
"publish" : [
{
"topic": "vscp/{{guid}}/{{class}}/{{type}}/{{nodeid}}",
"qos": 1,
"retain": false,
"format": "json"
}
]
}
}
Set enable to "true" if the driver should be loaded by the VSCP daemon.
This is the name of the driver. Used when referring to it in different interfaces.
This is the path to the driver. If you install from a Debian package this will be /var/lib/vscp/drivers/level2/libvscpl2drv-tcpipsrv.so.
This is the path to the driver configuration file (see below). This file determines the functionality of the driver. A good place for this file is in /etc/vscp/tcpipsrv.json It should be readable only by the user the VSCP daemon is run under (normally vscp) as it holds credentials to log in to a remote VSCP tcp/ip link interface. Never make it writable at this location.
All level II drivers must have a unique GUID. There is many ways to obtain this GUID, Read more here. The tool vscp_eth_to_guid is a useful tool that is shipped with the VSCP daemon that will get you a unique GUID if you are working on a machine with an Ethernet interface.
See the VSCP configuration documentation for info about this section. It is common for all drivers.
On start up the configuration is read from the path set in the driver configuration of the VSCP daemon, usually /etc/vscp/conf-file-name and values are set from this location. If the write parameter is set to "true" the above location is a bad choice as the VSCP daemon will not be able to write to it. A better location is /var/lib/vscp/drivername/configure.xml or some other writable location.
The configuration file have the following format
{
"debug" : true,
"write" : false,
"key-file" : "/etc/vscp/vscp.key",
"max-out-queue" : 32000,
"max-in-queue" : 32000,
"interface" : "9598",
"encryption" : "aes256",
"path-users" : "/home/akhe/development/VSCP/vscpl2drv-tcpipsrv/debug/users.json",
"tls" : {
"certificate" : "",
"certificate-chain" : "",
"verify-peer" : false,
"ca-path" : "",
"ca-file" : "",
"verify-depth" : 9,
"default-verify-paths" : true,
"cipher-list" : "DES-CBC3-SHA:AES128-SHA:AES128-GCM-SHA256",
"protocol-version" : 3,
"short-trust" : false
},
"logging" : {
"file-enable-log": true,
"file-log-level" : "debug",
"file-pattern" : "[vcpl2drv-tcpipsrv %c] [%^%l%$] %v",
"file-path" : "/tmp/vscpl2drv-tcpipsrv.log",
"file-max-size" : 5242880,
"file-max-files" : 7,
"console-enable-log": true,
"console-log-level" : "debug",
"console-pattern" : "[vcpl2drv-tcpipsrv %c] [%^%l%$] %v"
},
"filter" : {
"in-filter" : "incoming filter on string form",
"in-mask" : "incoming mask on string form",
"out-filter" : "outgoing filter on string form",
"out-mask" : "outgoing mask on string form"
}
}
A default configuration file is written to /usr/share/vscp/drivers/level2/vscpl2drv-tcpipsrv when the driver is installed.
Set debug to true to get debug information written to the log file. This can be a valuable help if things does not behave as expected.
If write is true dynamic changes to the configuration file will be possible to save dynamically to disk. That is, settings you do at runtime can be saved and be persistent. The safest place for a configuration file is in the VSCP configuration folder /etc/vscp/ but for dynamic saves are not allowed if you don't run the VSCP daemon as root (which you should not). Next best place is to use the folder /var/lib/vscp/drivers/level2/configure.json.
If you never intend to change driver parameters during runtime consider moving the configuration file to the VSCP daemon configuration folder is a good choice.
Currently not used.
Response timeout in milliseconds. Connection will be restarted if this expires.
Maximum number of events in the send queue.
Maximum number of events in the input queue.
Set the interface to listen on. Default is: tcp://localhost:9598. The interface is either secure (TLS) or insecure. It is not possible to define interfaces that accept connections of both types.
if "tcp:// part is omitted the content is treated as it was present.
If port is omitted, default 9598 is used.
For TLS/SSL use prefix "stcp://"
Response and commands from/to the tcp/ip link server can be encrypted using AES-128, AES-192 or AES-256. Set here as
"none|aes128|aes192|aes256"
Default: is no encryption.
The user database is separated from the configuration file for security reasons and should be stored in a folder that is only readable by the user of the host, usually the VSCP daemon.
The format for the user file is specified below.
Settings for TLS (Transport Layer Security), SSL. Not used at the moment.
As TLS/SSL is not supported yet (it will be) in this driver it is important to understand that if used in an open environment like the internet it is not secure. People listening on the traffic can see both data and username/password credentials. It is therefore important to use the driver in a controlled environment and as early as possible move the flow of events to a secure environment like MQTT with TLS activated. This is often not a problem in a local cable based environment but is definitely a problem using wireless transmission that lack encryption.
A solution is to use a SSL wrapper like this one.
Path to SSL certificate file. This option is only required when at least one of the listening_ports is SSL The file must be in PEM format, and it must have both private key and certificate, see for example ssl_cert.pem. If this option is set, then the webserver serves SSL connections on the port set up to listen on.
Default: /srv/vscp/certs/server.pem
T.B.D.
Enable client's certificate verification by the server.
Default: false
Name of a directory containing trusted CA certificates for peers. Each file in the directory must contain only a single CA certificate. The files must be named by the subject name’s hash and an extension of “.0”. If there is more than one certificate with the same subject name they should have extensions ".0", ".1", ".2" and so on respectively.
Path to a .pem file containing trusted certificates for peers. The file may contain more than one certificate.
Sets maximum depth of certificate chain. If client's certificate chain is longer than the depth set here connection is refused.
Default: 9
Loads default trusted certificates locations set at openssl compile time.
Default: true
List of ciphers to present to the client. Entries should be separated by colons, commas or spaces.
| Selection | Description | | ========= | =========== | | ALL | All available ciphers | | ALL:!eNULL | All ciphers excluding NULL ciphers | | AES128:!MD5 | AES 128 with digests other than MD5 |
See this entry in OpenSSL documentation for full list of options and additional examples.
Default: "DES-CBC3-SHA:AES128-SHA:AES128-GCM-SHA256",
Sets the minimal accepted version of SSL/TLS protocol according to the table:
Selected protocols | setting |
---|---|
SSL2+SSL3+TLS1.0+TLS1.1+TLS1.2 | 0 |
SSL3+TLS1.0+TLS1.1+TLS1.2 | 1 |
TLS1.0+TLS1.1+TLS1.2 | 2 |
TLS1.1+TLS1.2 | 3 |
TLS1.2 | 4 |
Default: 4.
Enables the use of short lived certificates. This will allow for the certificates and keys specified in ssl_certificate, ssl_ca_file and ssl_ca_path to be exchanged and reloaded while the server is running.
In an automated environment it is advised to first write the new pem file to a different filename and then to rename it to the configured pem file name to increase performance while swapping the certificate.
Disk IO performance can be improved when keeping the certificates and keys stored on a tmpfs (linux) on a system with very high throughput.
Default: false
In this section is the log console and log file settings. Before the configuration file is read logging will be sent to the console.
Modes for logging can be set as of below. In debug/trace mode the debug flag above defines how much info is logged.
Enable logging to a console by setting to true.
Log level for console log. Default is "info".
Level | Description |
---|---|
"trace" | Everything is logged |
"debug" | Everything except trace is logged |
"info" | info and above is logged |
"err" | Errors and above is logged |
"critical" | Only critical messages are logged |
"off" | No logging |
Format for consol log.
Enable logging to a file by setting to true.
Log level for file log. Default is "info".
Level | Description |
---|---|
"trace" | Everything is logged |
"debug" | Everything except trace is logged |
"info" | info and above is logged |
"err" | Errors and above is logged |
"critical" | Only critical messages are logged |
"off" | No logging |
Log file pattern as described here.
Set a writable path to a file that will get log information written to that file. This can be a valuable help if things does not behave as expected.
Max size for log file. It will be rotated if over this size. Default is 5 Mb.
Maximum number of log files to keep. Default is 7.
Filter and mask is a way to select which events is received by the driver. A filter have the following format
priority,vscpclass,vscptype,guid
All values can be give in decimal or hexadecimal (preceded number with '0x'). GUID is always given i hexadecimal (without preceded '0x').
Default: setting is
0,0,0,00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00
Read the vscpd manual for more information about how filter/masks work.
The default filter/mask pair means that all events are received by the driver.
Filter and mask is a way to select which events is received by the driver. A mask have the following format
priority,vscpclass,vscptype,guid
All values can be give in decimal or hexadecimal (preceded number with '0x'). GUID is always given i hexadecimal (without preceded '0x').
The mask have a binary one ('1') in the but position of the filter that should have a specific value and zero ('0') for a don't care bit.
Default setting is
0,0,0,00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00
Read the vscpd manual for more information about how filter/masks work.
The default filter/mask pair means that all events are received by the driver.
The user database is separated from the driver configuration file due to security reasons. It should be places in a file that is only readable by the vscp user, the user the VSCP daemon us run under.
A good location for the file is /etc/vscp/users.json Set user and group to vscp and rights to 0x700.
The installation script install a sample user file to /usr/share/vscpl2drv-tcpipsrv/. This file can be used as a starting point for your own setup. It defines two users. admin and user both with password secret.
The user configuration file is on JSON format and looks like this.
{
"users" : [
{
"user" : "admin",
"fullname" : "Full name",
"note" : "note about user-item",
"credentials" : "hash over 'user:password'",
"filter" : "outgoing filter",
"rights" : "comma separated list of rights",
"remotes" : "comma separated list of hosts. First char: '+' = allow '-' = deny",
"events" : "comma separated list of events where each item is specified as [TX|RX|BOTH;vscp-class;vscp.type;priority]"
}
]
}
Any number of users can be specified
The login user name
Hash calculated over "user:password" stored as 'pw:salt'
With the VSCP daemon is a script vscp-mkpassword installed that can be used to generate passwords.
Rights for this user as a 32-bit rights number.
Full name for user.
This is a list with events the user is allowed to send and/or receive. If empty all events can be sent and received by the users.
VSCP class. Can be set to -1 to allow all classes.
VSCP type. Can be set to -1 to allow all types.
The direction the user is allowed to handle. Set to "rx" to allow only receive. Set to "tx" to allow only transmit. Set to "both" or empty to allow sending and receiving.
Max priority (0-7) this user can use for send events. Trying to send an event with a higher priority will replace the event value with the value set here. Note that 0 is the highest priority.
The users.json file looks like this
{
"users" : [
{
"name" : "admin",
"password" : "487636FDE3637C7C853AAC9EAF6FA062;357C71CA59F760C08C4125C444A22A91FD1FE1FB0E5628771A572BAF6F61B71F",
"fullname" : "Miss. Super User",
"rights" : "admin",
"remotes" : [
"+127.0.0.0/24",
"+192.168.0.0/16"
],
"events" : "",
"filter" : "",
"mask" : "",
"note" : "A normal user. username='admin' password='secret'"
},
{
"name" : "user",
"password" : "0839DD1BE692164847B601E6520CE23B;3E1B4D950F04EA3BFA2C43160B9D98ECC76B249F79A1062F041C526978591BA3",
"fullname" : "Mr. Sample User",
"rights" : "user",
"remotes" : "",
"events" : "",
"filter" : "",
"mask" : "",
"note" : "A normal user. username='user' password='secret'"
}
]
}
### Windows
See information from Linux. The only difference is the disk location from where configuration data is fetched.
Use the libvscpl2drv-tcpipsrv when you need a VSCP tcp/ip link interface to MQTT. Events you write to the driver subscribed topics will be sent over the tcp/ip channels. And events sent using the tcp/ip interface will be published on the configured publish topics.
The libvscpl2drv-tcpiplink go through subscribe/publish topic techniques.
Add the following to the level II section of the VSCP daemon configuration file
{
"enable" : true,
"name" : "tcpip-srv",
"path-driver" : "/var/lib/vscp/drivers/level2/libvscpl2drv-tcpipsrv.so",
"path-config" : "/etc/vscp/tcpipsrv.json",
"guid" : "FF:FF:FF:FF:FF:FF:FF:F5:02:88:88:00:00:00:00:01",
"mqtt": {
"bind": "",
"host": "test.mosquitto.org",
"port": 1883,
"mqtt-options": {
"tcp-nodelay": true,
"protocol-version": 311,
"receive-maximum": 20,
"send-maximum": 20,
"ssl-ctx-with-defaults": 0,
"tls-ocsp-required": 0,
"tls-use-os-certs": 0
},
"user": "vscp",
"password": "secret",
"clientid": "the-vscp-daemon tcpipsrv driver",
"publish-format": "json",
"subscribe-format": "auto",
"qos": 1,
"bcleansession": false,
"bretain": false,
"keepalive": 60,
"bjsonmeasurementblock": true,
"reconnect": {
"delay": 2,
"delay-max": 10,
"exponential-backoff": false
},
"tls": {
"cafile": "",
"capath": "",
"certfile": "",
"keyfile": "",
"pwkeyfile": "",
"no-hostname-checking": true,
"cert-reqs": 0,
"version": "",
"ciphers": "",
"psk": "",
"psk-identity": ""
},
"will": {
"topic": "vscp-daemon/{{srvguid}}/will",
"qos": 1,
"retain": true,
"payload": "VSCP Daemon is down"
},
"subscribe" : [
{
"topic": "vscp/tcpipsrv/{{guid}}/#",
"qos": 0,
"v5-options": 0,
"format": "auto"
}
],
"publish" : [
{
"topic": "vscp/{{guid}}/{{class}}/{{type}}/{{nodeid}}",
"qos": 1,
"retain": false,
"format": "json"
}
]
}
}
Copy /var/share/vscpl2drv-tcpipsrv/tcpipsrv.json and /var/share/vscpl2drv-tcpipsrv/users.json to /etc/vscp
sudo cp /var/share/vscpl2drv-tcpipsrv/tcpipsrv.json /etc/vscp
sudo cp /var/share/vscpl2drv-tcpipsrv/users.json /etc/vscp
Restart the vscp daemon
sudo systemctl restart vscpd
Now you should be able to login to the tcp/op interface. Try
telnet localhost 9598
and issue the following command when the server responds with something like
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
Welcome to the VSCP tcp/ip server [l2drv].
Version: 15.0.0-0
Copyright © 2000-2021 Ake Hedman, the VSCP Project, https://www.vscp.org
+OK - Success.
user pass
pass secret
Uf you get
+OK - Success
you are successfully connected. You can issue
help
for a list of commands. (They are all described in detail in the VSCP specification https://grodansparadis.github.io/vscp-doc-spec/#/./vscp_tcpiplink
Now send a VSCP test event to the published topics
send 0,20,3,,,,0:1:2:3:4:5:6:7:8:9:10:11:12:13:14:15,0,1,35
This is the (CLASS1.INFORMATION, Type=3, VSCP_TYPE_INFORMATION_ON)[https://grodansparadis.github.io/vscp-doc-spec/#/./class1.information?id=type3] event. The three databytes are index (0), zone (1) and subzone (35) an dthe GUID is set to 0:1:2:3:4:5:6:7:8:9:10:11:12:13:14:15
The ",,,,"means default are used for date tiem and timestamp and object id, They will be set to current UTC time and a valid timestamp.
You can instead send
send 0,20,3,,,,-,0,1,35
in which case the interface GUID will be used.
Use mosquittp_sub for example to se the published events. Like this
mosquitto_sub -h test.mosquitto.org -p 1883 -t vscp/#
note
Install mosquitto pub/sub with
sudo tp install mosquitto-clients
if you don't have them installed
note
To repeat a command in the VSCP tcp/ip link interface press
'+' + <ENTER>
To check if you have received any event use the
chkdata
command and to retrive the events use
retr n
where n is the number of events you want to retreive.
You can also go into a revive loop with
rcvloop
now all events wil be listed as soon as they arrive. Use
quitloop
to terminate the receive loop.
When you ar ready use
quit
to terminate the session.
- The VSCP site - https://www.vscp.org
- The VSCP document site - https://docs.vscp.org/
- VSCP discussions - https://github.com/grodansparadis/vscp/discussions