lundix SPC Bridge Modbus User Guide

lundix SPC Bridge Modbus

History Record

Inactivity Timeout**

(Added in firmware 1.0.4)

Introduction

SPC Bridge Modbus

SPC Bridge
SPC Bridge Modbus allows integration of Vanderbilt SPC intrusion system with a third-party system, e.g. a SCADA system, using the Modbus protocol. Using the SPC Bridge you are able to use events from all your SPC connected motion detectors, door/window contacts, fire detectors and alarm status for automations in the third-party system.

Main Features

• SPC Bridge Modbus acts as a Modbus TCP server (only one Modbus TCP client connection is allowed at a time).
• Provides SPC zone and area states/status to a Modbus TCP client, e.g. a SCADA system.
• Support for area and zone commands from a Modbus TCP client, e.g. arm/disarm, inhibit zone.
• SPC Panel Communication based on Vanderbilt official FlexC protocol.
• Web based Admin GUI
• Recommended for maximum 128 zones and 16 areas. (The Modbus Register Map is designed for 256 zones and 16 areas. The recommendation is only an estimation. The actual limit depends on the use case, e.g. number of SPC events, number of motion detectors and the Modbus polling rate)
• Recommended Modbus Client poll rate >= 2 seconds.

Hardware Specification

SPC Bridge|
---|---
Processor| 400MHz, 24K MIPS
Flash| 16MB
RAM| 64MB
Power input| 9 – 12V DC
Network| 2 x 10M/100M RJ45 Connectors
WiFi| 802.11 b/g/n
USB| 1 x USB 2.0 host connector
Type Approval| FCC Part15 Subpart B, Subpart C, CE NB, C-Tick

Modbus
SPC Bridge Modbus provides a Modbus TCP server. The default port for Modbus TCP Client connection is 502, but port number can be reassigned if desired. Only one Client connection is accepted at a time. For increased security it is possible to restrict which Client (client ip address) is allowed to connect.

There is any stated time for the poll rate. A lot of factors will come into play that can affect the response time, such as the type of request and how much data is being requested. Read multiple  might take slightly longer for a response but more data will be transferred at once vs a read single might take less time to respond to but you will need to send more requests increasing the time. As a general recommendation you should use a poll rate >= 2 seconds.

Installation

Prerequisites

• Vanderbilt SPC panel with firmware >= 3.6 (3.6 was the first version with support for FlexC)
• Network router with DHCP server enabled
• SPC Bridge and SPC panel connected to same local network
• Internet access (to be able to use time synchronization via NTP)
• A Modbus TCP client, e.g. a SCADA system

First Time Installation Workflow

1. Read carefully End-User License Agreement for SPC Bridge (EULA) in last section in this document. If you do not agree to the terms of the EULA, do not install or use the SPC Bridge.
2. Connect the SPC Bridge LAN port, with a regular network cable, to your network switch or router.
3. Power up the device by connecting the included power adapter to a wall socket and then to the SPC Bridge.
4. Wait (~3 minutes) until the SPC Bridge has fully started.
5. Open a web browser and access your router (DHCP-server) to find the IP address assigned to the SPC Bridge. Type the IP address in the web browser to go to the SPC Bridge sign in page.
6. Assign a static IP address to the SPC Bridge. Follow instructions in section System Administration, Static IP Address.
7. Configure SPC communication. Follow the instructions in section SPC Bridge Configuration, SPC Communication.
8. Test the SPC Communication. See SPC Communication Test.
9. Configure the Modbus communication.

System Administration

The SPC Bridge is based on a standard Linux platform, OpenWrt, that is very common on routers. The System Administration Web GUI contains many settings intended only for advanced users. Only the settings described in this section should be changed by normal users.

System Administration Login
Type IP address of the SPC Bridge in the web browser address field, go to SPC Bridge sign in page and click on System Administration in the top bar.

This will open the OpenWRT sign in page. Enter username (root) and password (default: dragino) and click on Login.

NOTE! To return to SPC Bridge sign in page you need to type the SPC Bridge IP address in the web browser address field.

Static IP Address
Default will SPC Bridge use DHCP to get an IP Address. To be sure that the SPC Bridge keeps the IP address after a network/router restart you should assign the SPC Bridge a static IP Address. In the System Administration GUI, go to Network -> Interfaces and:

1. Select LAN – Edit.
2. In Interfaces – LAN, select Static address in the Protocol option menu
3. Click on Switch Protocol
4. In Common Configuration – General Setup fill in; IPv4 address, netmask, gateway and custom DNS servers.
5. In DHCP Server – General Setup; check the checkbox Ignore interface. NOTE! It is very important to disable the DHCP server in the SPC Bridge to avoid conflict with your normal DHCP server.
6. Click on Save & Apply.
7. Redirect your browser to the new IP Address.

Time Setting
To set correct Timezone, go to System -> System and select Timezone in section System Properties – General Settings.
The device is as default using NTP to synchronize time. This setting is in System -> System section Time Synchronization.

NOTE! The device has no RTC clock. During boot the device can have incorrect time. Some events in the system log can therefore have incorrect timestamps.

Change Administration Password
The default administration password for accessing the device is dragino. Of security reasons it is highly recommended to change the password as soon as possible. Go to System -> Administration section Device Password to change the password. The same password is used in both Administration Web GUI and for ssh access to the device.

SPC Bridge Configuration

SPC Bridge Sign In
Type IP address of the SPC Bridge in the web browser address field, go to SPC Bridge sign in page, enter username (spcbridge) and password (default Spcbridge!) and click Login.

SPC Communication (FlexC)
To setup the communication link between SPC Panel and SPC Bridge you have to configure the link in both SPC Panel and SPC Bridge ends.

SPC Panel – FlexC Settings.
Use Vanderbilt SPC Web interface and define the FlexC communication following this instructions:

1. Select Full Engineer mode
2. Create a specific user for the SPC Bridge communication, e.g spcbridge. User profile should be Manager and you need also to define a web password for the user. (To be able to set a web password you need to login as the user in the SPC web interface).
3. Select Communications -> FlexC -> Event Profiles. Click on Add to add a new event profile. Give the event profile the name SPC Bridge Events and select (check) the report checkboxes for all event types. (You may consider reducing these settings later to just necessary events for the application)
4. Select Communications -> FlexC -> FlexC ATS. Select Add Custom ATS and change following from the default settings:
   • ATS Name = SPC Bridge
   • Event Profile = SPC Bridge Events (created in step 3)
   • ATS Polling Timeout = 60 seconds
   • Uncheck Generate FTC and Re-queue Events
5. Select Add ATP to FlexC RCT and change following from the default settings:
   • SPT Account Code = 999
   • RCT URL or IP Address = IP Address of the SPC Bridge
   • ATP Category = Cat 6 [Ethernet]
6. Open Advanced ATP Settings and change following from the default settings:
   • Encryption Key Mode = Fixed Encryption
   • Encryption key (64 hex digits) = Your own key. Must be exactly 64 hex digits (0-9, a-f).
7. Leave Full Engineer mode.

NOTE! In Full Engineer mode the SPC panel is not reporting any events to the SPC Bridge.

SPC Bridge – SPC Communication Settings
In the SPC Bridge Web interface, login and select SPC ->SPC Communication and fill in the form according to:

match corresponding key in SPC Panel FlexC settings. (Default key: 000011112222…ddddeeeeffff)

NOTE! Of security reason a saved encryption key is never shown again. Just leave the field blank if you don’t want to change the key.

SPC Account Code| ATP Account Code. Must match corresponding key in SPC Panel FlexC settings.
---|---
RCT ID| RCT Id. Must match corresponding id in SPC Panel FlexC settings.
RCT TCP Port| RCT TCP Port. Must match corresponding value in SPC Panel FlexC settings.
SPC Username and Password| Credentials for FlexC communication. User must be defined in the SPC Panel and have a corresponding web password.

Valid username: max 16 characters, not including space, double quotes, backslash or tilde characters.

Valid password: max 16 characters, not including space, double quotes, backslash or tilde characters.

NOTE! Of security reason a saved password is never shown again. Just leave the field

blank if you don’t want to change the password.

SPC Communication Test
To be sure that the communication between SPC Bridge and SPC panel is working properly you can use the tests provided in SPC ->SPC Communication Test. In the option menu you can choose between query SPC areas, zones or the system log.

Modbus TCP Server

Modbus Server Port| The port the Modbus Client should use for connection to SPC Bridge Modbus. Default value is 502.|
---|---|---
Client Inactivity Timeout| The time the Modbus Server will wait to receive a message from the client before the server shuts

down the connection with the client. 0 – 3600 seconds. Default 60 seconds.

NOTE! If set to 0 a failed/broken connection will never be detected and shut down and a restart of SPC Bridge is necessary to restore the Modbus Server to normal mode.

Allowed Modbus Client| IP Address of Modbus Client allowed to connect to SPC Bridge Modbus. Default value 0.0.0.0 allows

any Client to connect.

NOTE! Of security reason, it is highly recommended to set the IP address of the Modbus Client in

Allowed Modbus Client.

NOTE! Of security reason, it is highly recommended to set the IP address of the Modbus Client in Allowed Modbus Client.

Modbus Datapoints
Interface -> Modbus Datapoints shows the current values of the Modbus datapoints and can be used for troubleshooting. The objects are divided in following categories:

• Com Status
• SPC Area Arm Status
• SPC Area Status
• SPC Zone Input States
• SPC Zone Status
• SPC Area Commands
• SPC Zone Commands

See section 5.3 Modbus Register Map for the datapoints details.

Write only: Modbus client is allowed to change the value. (Read is not supported)

System Info
System -> System Info shows some basic information about the SPC Bridge hardware and software.

System User
To change the password for the SPC Bridge user (spcbridge) go to System -> User and enter a new password twice. Note! Username is not possible to change.

Modbus Communication

Modbus Function Codes
SPC Bridge Modbus supports following function codes:

125
06| Write a single holding register (4x). Value type: unsigned 16 bits integer

(UINT16)

| –

Modbus Error Codes
SPC Bridge Modbus can reply with following errors:

allowed by the Modbus server
2| Illegal Data Address| The data address (register number) received in the query is not an allowed address for the Modbus server. If multiple registers were requested, at least one was not

permitted.

3| Illegal Data Value| The value contained in the query’s data field is not acceptable to the Modbus

server.

Modbus Register Map
Register Types
SPC Bridge Modbus use following Modbus Registers:

(BOOL)
Input Register (3x)| 0 – 350| Input registers. Value type: unsigned 16 bits integer (UINT16)
Holding Register (4x)| 0 – 24| Holding register. Value type: unsigned 16 bits integer (UINT16)

Communication Status
Following data are available:

Register Number| Modbus Address| Name| Values| Format| Access
---|---|---|---|---|---
30001| 0| SPC com status| 0 = SPC communication is under initialization (datapoint values are not reliable),

1 = SPC communication is OK,

2 = SPC communication has failed (datapoint values are not reliable)

To test SPC communication please see section 4.3.

| UINT16| Read only
 |  |  |  |  |
---|---|---|---|---|---
30002| 1| Area command reply status| 0 = Last area command succeeded,

1-255 = Area command failed error code.

Codes are listed in section 7.1 SPC Command Error Codes.

| UINT16| Read only
30003| 2| Zone command reply status| 0 = Last zone command succeeded,

1-255 = Zone command failed error code.

Codes are listed in section 7.1 SPC Command Error Codes.

| UINT16| Read only

SPC Area Commands
Common for all SPC areas following commands will be available:

Register Number| Modbus Address| Name| Values| Format| Access
---|---|---|---|---|---
40012| 11| Area unset command| ID of area to unset

The success/error of the command is

reported in “Area command reply status”.

| UINT16| Read/Write
40013| 12| Area partset A command| ID of area to partset A

The success/error of the command is

reported in “Area command reply status”.

| UINT16| Read/Write
40014| 13| Area partset B command| ID of area to partset B

The success/error of the command is reported in “Area command reply status”.

| UINT16| Read/Write
40015| 14| Area fullset command| ID of area to fullset (immediately)

The success/error of the command is

reported in “Area command reply status”.

The fail to set reason is reported in “Area fail

to set reason”

| UINT16| Read/Write
40016| 15| Area delayed fullset command| ID of area to fullset when exit time has expired

The success/error of the command is

reported in “Area command reply status”.

The fail to set reason is reported in “Area fail to set reason” (after exit time has expired or been canceled)

| UINT16| Read/Write

SPC Zone Commands
Common for all SPC zones following commands will be available:

Register Number| Modbus Address| Name| Values| Format| Access
---|---|---|---|---|---
40022| 21| Zone inhibit command| ID of zone to inhibit

The success/error of the command is

reported in “Zone command reply status”.

| UINT16| Read/Write
40023| 22| Zone deinhibit command| ID of zone to deinhibit

The success/error of the command is

reported in “Zone command reply status”.

| UINT16| Read/Write
40024| 23| Zone isolate command| ID of zone to isolate

The success/error of the command is

reported in “Zone command reply status”.

| UINT16| Read/Write
40025| 24| Zone deisolate command| ID of zone to deisolate

The success/error of the command is

reported in “Zone command reply status”.

| UINT16| Read/Write

Zone ID = 1 to maximum number of zones (256).

SPC Area Arm Status
For each SPC area following arm status will be available:

Relative **Register Number *| Relative Modbus Address **| Name| Values| Format| Access**
---|---|---|---|---|---
+1| +1| Area X unset| 0 = Area is not unset,

1 = Area is unset (disarmed)

| BOOL| Read only
+2| +2| Area X partset A| 0 = Area is not partset A, 1 = Area is partset A| BOOL| Read only
+3| +3| Area X partset B| 0 = Area is not partset B, 1 = Area is partset B| BOOL| Read only
+4| +4| Area X fullset| 0 = Area is not fullset,

1 = Area is fullset (armed)

| BOOL| Read only
+5| +5| Area X intrusion alarm| 0 = Area has no intrusion alarm ***,

1 = Area has at least one intrusion alarm ***

| BOOL| Read only
+6| +6| Area X fire alarm| 0 = Area has no fire alarm ****,

1 = Area has at least one fire alarm ****

| BOOL| Read only
+7| +7| Area X tamper alarm| 0 = Area has no tamper alarm *****,

1 = Area has at least one tamper alarm *****

| BOOL| Read only
+8| +8| Area X confirmed alarm| 0 = Area has no confirmed alarm ***,

1 = Area has at least one confirmed alarm

| BOOL| Read only
+9| +9| Not used|  |  |
+10| +10| Not used|  |  |
---|---|---|---|---|---

• X = 1 to maximum number of areas (16).
• • Register number = 10271 + (X-1) * 10 + ‘relative register number’
• * Modbus address = 270 + (X-1) 10 + ‘relative modbus address’.
• * Value is based on Alarm status for zone types Alarm, Exit/Entry, Glassbreak and Exit/Entry2. ** Value is based on Alarm status for zone type Fire.
• ***** Value is based on Alarm status for zone type Tamper and Tamper status for all zone types.

Example.

SPC Area Status
For each SPC area following area status will be available:

Relative **Register Number *| Relative Modbus Address **| Name| Values| Format| Access**
---|---|---|---|---|---
+1| +1| Area X unset user id| 1 – 255 = SPC User ID of user who last unset the area,

0 = User Id is unknown

Will be updated every time Area mode changes to Unset and if value changes of other reason e.g at startup.

| UINT16| Read only
+2| +2| Area X fullset user id| 1 – 255 = SPC User ID of user who last fullset the area,

0 = User Id is unknown

| UINT16| Read only
 |  |  | Will be updated when Area mode changes to Fullset (and if value changes of other reason

e.g at startup)

|  |
---|---|---|---|---|---
+3| +3| Area X fail to set reason| 0 = Area fullset succeeded, 1 = Interlocked,

2 = Calendar was preventing area fullset, 100 (0x64) = An area was preventing area fullset,

101  (0x65) = A (open) zone was preventing area fullset,

102  (0x66) = An alert was preventing area fullset,

200 (0xC8) = Other reason was preventing area fullset

Will be updated every time Area mode changes to new value and if value changes of other reason e.g at exit delay and startup.

| UINT16| Read only
+4| +4| Not used|  |  |
+5| +5| Not used|  |  |

X = 1 to maximum number of areas (16).

• Register number = 30271 + (X-1) * 5 + ‘relative register number’ * Modbus address = 270 + (X-1) 5 + ‘relative modbus address’
  Example.

SPC Zone Input States
For each SPC zone (alarm input) following input value will be available:

Register Number| Modbus Address| Name| Values| Format| Access|
---|---|---|---|---|---|---
10011 + X| 10 + X| Zone X state| 0 = Zone is Closed, 1 = Zone is Open| BOOL| Read only|

X = 1 to maximum number of zones (256).
Example.

SPC Zone Status
For each SPC zone (alarm input) following status value will be available:

Register Number| Modbus Address| Name| Values| Format| Access|
---|---|---|---|---|---|---
30011 + X| 10 + X| Zone X status| 0 = OK,

1 = Inhibited,

2 = Isolated,

3 = Soak,

4 = Tamper,

5 = Alarm,

6 = OK,

7 = Trouble,

8 = Masked,

9 = Post Alarm

| UINT16| Read only|

X = 1 to maximum number of zones (256).

Example.

Advanced Users

Backup of Configuration Settings
In System Administration -> System -> Backup / Flash Firmware, section Backup /Restore, you can save a backup copy of your settings on your PC and later use it to restore the settings.

Upgrading software
In System Administration -> System -> Backup / Flash Firmware, you can upgrade the firmware to a new version. The firmware/image file should have the name dragino-spc-bridge-Modbus-vX.X.X-squashfs-sysupgrade.bin. For minor upgrades you can keep your current settings by selecting Keep settings. For major upgrades it is preferable to not keep the settings, because they can be incompatible with the new firmware.

1. Copy the image file provided by Lundix to the desktop of your PC.
2. In SPC Bridge System Administration GUI, go to System->Backup/Flash firmware
3. Just to be sure, do a backup copy of your settings with Download backup
4. Under Flash new firmware image
   • Check Keep settings if you would like to preserve your current settings.
   • Select Image file. Select and open the new image file.
   • Click on Flash image. The file is now uploaded and verified. Click Proceed to continue the installation
5. Wait at least 5 minutes until the installation is finished. (LED Power is ON and LED LAN is ON or Blinking)
6. Go back to sign in page, sign in again and check the settings

SSH Access
The device has as default ssh access enabled. Login using username root and same password as in the System Administration GUI (default dragino). The settings for the SSH access can be changed in the System Administration->System -> Administration, section SSH Access.

Resetting the SPC Bridge
The SPC Bridge has a toggle button which can be used to reset the device. When the SPC Bridge is running in normal mode, you can use a paper clip or similar to press and hold the toggle button.

• If pressing the toggle button and hold it for 5 seconds, it will reset the network settings and other settings will be kept.
• If pressing the toggle button and hold it for 30 seconds, it will reset ALL settings to factory default

Appendices

SPC Command Error Codes

End-User License Agreement for SPC Bridge (EULA)
IMPORTANT PLEASE READ THE TERMS AND CONDITIONS OF THIS LICENSE AGREEMENT CAREFULLY BEFORE USING THE SPC BRIDGE SOFTWARE OR HARDWARE. SPC Bridge End- User License Agreement (“EULA”) is a legal agreement between you (either an individual or a single entity) and Lundix IT, Sweden, for the SPC Bridge software and hardware product(s) (referred to as the  “PRODUCT”) which may also include associated software components, media, printed materials, and “online” or electronic documentation. By installing, copying, or otherwise using the PRODUCT, you agree to be bound by the terms of this EULA. This license agreement represents the entire agreement concerning the PRODUCT between you and Lundix IT (referred to as “licenser”), and it supersedes any prior proposal, representation, or understanding between the parties. If you do not agree to the terms of this EULA, do not install or use the PRODUCT. The PRODUCT is protected by copyright laws and international copyright treaties, as well as other intellectual property laws and treaties. The software is licensed, not sold.

GRANT OF LICENSE.
The PRODUCT is licensed as follows:

• The FlexC communication program is based on Vanderbilt propriety protocol FlexC and therefore NOT open-source.
• All other software in SPC Bridge is licensed under many different open source licenses.
• Backup Copies. You may make copies of the software as may be necessary for backup and archival purposes.

DESCRIPTION OF OTHER RIGHTS AND LIMITATIONS.

• Maintenance of Copyright Notices.
  You must not remove or alter any copyright notices on any and all copies of the PRODUCT.

• Prohibition on Reverse Engineering, Decompilation, and Disassembly.
  You may not reverse engineer, decompile, or disassemble the program SPC Flex Gateway.

• Support Services.
  Lundix IT may provide you with support services related to the PRODUCT (“Support Services”). Any supplemental software code provided to you as part of the Support Services shall be considered part of the PRODUCT and subject to the terms and conditions of this EULA.

• Compliance with Applicable Laws.
  You must comply with all applicable laws regarding use of the PRODUCT.

COPYRIGHT
All title, including but not limited to copyrights, in and to the PRODUCT and any copies thereof are owned by Lundix IT or its suppliers. All title and intellectual property rights in and to the content which may be accessed through use of the PRODUCT is the property of the respective content owner and may be protected by applicable copyright or other intellectual property laws and treaties. This EULA grants you no rights to use such content. All rights not expressly granted are reserved by Lundix IT.

NO WARRANTIES
Lundix IT expressly disclaims any warranty for the PRODUCT. The PRODUCT is provided ‘As Is’ without any express or implied warranty of any kind, including but not limited to any warranties of merchantability, noninfringement, or fitness of a particular purpose. Lundix IT does not warrant or assume responsibility for the accuracy or completeness of any information, text, graphics, links or other items contained within the PRODUCT. Lundix IT makes no warranties respecting any harm that may be caused by the transmission of a computer virus, worm, time bomb, logic bomb, or other such computer program. Lundix IT further expressly disclaims any warranty or representation to Authorized Users or to any third party.

LIMITATION OF LIABILITY
In no event shall Lundix IT be liable for any damages (including, without limitation, lost profits, business interruption, or lost information) rising out of ‘Authorized Users’ use of or inability to use the PRODUCT, even if Lundix IT has been advised of the possibility of such damages. In no event will Lundix IT be liable for loss of data or for indirect, special, incidental, consequential (including lost profit), or other damages based in contract, tort or otherwise. Lundix IT shall have
no liability with respect to the content of the PRODUCT or any part thereof, including but not limited to errors or omissions contained therein, libel, infringements of rights of publicity, privacy, trademark rights, business interruption, personal injury, loss of privacy, moral rights or the disclosure of confidential information.

Open Source Software
The SPC Bridge software is based on OpenWrt, a Linux distribution that bundles lots of third party software, under many different licenses. Source code for OpenWrt is available on http://dev.openwrt.org.

The most frequently used licenses are:
GNU General Public License (GPL) and GNU Lesser General Public License (LGPL) version 2. These firmware images contain software licensed under the GPLv2. A copy of that license can be found at http://www.gnu.org/licenses/gpl-2.0.txt. Apache License version 2.0. These firmware images contain software licensed under the APLv2. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0. Modified files carry prominent notices stating who made the changes. MIT License. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Open Source Hardware
The SPC Bridge hardware is based on the open source hardware Dragino, http://www.dragino.com. The Dragino hardware design is released under the Creative Commons License, https://creativecommons.org/licenses/. The modular Dragino design enables rapid development cycles for commercial products.

References

• OpenWrt
• Apache License, Version 2.0
• Dragino :: Open Source WiFi, Linux Appliance
• gnu.org/licenses/gpl-2.0.txt
• Sobre las licencias - Creative Commons

Read User Manual Online (PDF format)

Download This Manual (PDF format)

Download this manual  >>