1. DL manuals
  2. B+B SmartWorx
  3. Gateway
  4. SmartSwarm 300
  5. User Manual

B+B SmartWorx SmartSwarm 300 User Manual

Summary of SmartSwarm 300

  • Page 1

    Smartswarm 300 series user manual www.Infopulsas.Lt / info@infopulsas.Lt.

  • Page 2: Phone (815) 433-5100

    Smartswarm 300 series : 2 advantech b+b smartworx americas 707 dayton road ottawa, il 61350 usa phone (815) 433-5100 fax (815) 433-5105 advantech b+b smartworx european headquarters westlink commercial park oranmore, co. Galway, ireland phone +353 91-792444 fax +353 91-792445 www.Advantech-bb.Com su...

  • Page 3

    Smartswarm 300 series : 3 contents list of tables .................................................................................................................................................................. 7 1. Introduction ........................................................................

  • Page 4

    Smartswarm 300 series : 4 4.2 power connector pwr ...................................................................................................................................... 34 4.3 ethernet port (eth0 and eth1) .................................................................................

  • Page 5

    Smartswarm 300 series : 5 9.2 create an empty slave map ............................................................................................................................... 57 9.3 import a slave map .............................................................................................

  • Page 6

    Smartswarm 300 series : 6 10.4.1 custom topic space ................................................................................................................................ 103 10.4.2 default topic space ...........................................................................................

  • Page 7

    Smartswarm 300 series : 7 15.1.8 debug and agents ................................................................................................................................... 124 15.1.9 tsed .........................................................................................................

  • Page 8

    Smartswarm 300 series : 8 table 11. Led indicators .............................................................................................................................................. 42 table 12. The modbus to mqtt application .................................................................

  • Page 9

    Smartswarm 300 series : 9 table 37. Event / payload matrix ................................................................................................................................. 93 table 38. The default topic ...................................................................................

  • Page 10

    Smartswarm 300 series : 10 1. Introduction smartswarm 351 is an iot gateway appliance powered by b+b smartworx smartswarm technology. It is intended for use in applications where users need to pass data from legacy modbus rtu installations into an iot platform or application, but who can’t tolerate ...

  • Page 11

    Smartswarm 300 series : 11 1.1 why enrich data? Modbus data is impossible to interpret without very detailed knowledge of the devices producing the data and the sensors connected to them. Anyone looking at modbus data can see that the value of unit 31, register 40075 is 2397 – but has no way to inte...

  • Page 12

    Smartswarm 300 series : 12 2. Document structure this document is organized in accordance with the following flow. Connect your hardware configure your device’s connectivity to configure the modbus interface configure the mqtt interface build your slave maps configure rules and topics verify your da...

  • Page 13

    Smartswarm 300 series : 13.

  • Page 14

    Smartswarm 300 series : 14 the next chapter walks through an example workflow. This workflow is intended to be an example of how to get your modbus data publishing to an mqtt server quickly, without getting stuck in the details. The remaining chapters will provide the necessary details..

  • Page 15

    Smartswarm 300 series : 15 3. Example workflow in this section we will walk through an example workflow. 3.1 connect your hardware first, ensure that your hardware is physically connected. Connect your antennae to the ant and div connectors. Insert a valid and data-provisioned sim card into sim 1. I...

  • Page 16

    Smartswarm 300 series : 16 that’s all you need to do: the device will now attempt to (a) make a wan connection using the cellular network; then (b) make a secure connection to smartworx hub (on hub.Bb-smartworx.Com). When (a) is successful, the wan led will turn on (yellow). When (b) is successful, ...

  • Page 17

    Smartswarm 300 series : 17 open a browser page, and login to smartworx hub on https://hub.Bb-smartworx.Com . In this example, we assume that (a) you have an account to login with smartworx hub, and (b) you are using the cloud instance of smartworx hub to manage your devices..

  • Page 18

    Smartswarm 300 series : 18 go to the “devices”->”claim device” screen to bring your new smartswarm device into your device farm. Type in your device’s device-id (this is written both on the device itself and on the box that you took your device out of) and select ‘check device id’ to check that your...

  • Page 19

    Smartswarm 300 series : 19 now configure the modbus settings so that they match the actual modbus configuration of your modbus network. Apply the changes..

  • Page 20

    Smartswarm 300 series : 20 3.4 configure the mqtt interface select mqtt from the list on the left hand pane and configure your mqtt interface. We assume that you already have an mqtt broker that you can publish to. In our example we know we have an mqtt broker available at 52.51.11.241, using the de...

  • Page 21

    Smartswarm 300 series : 21 in this example we are not configuring any security in the mqtt interface. We recommend that you use “no security” only until you have verified your connection and data-flow. If you do not apply transport layer security settings, your data will be published to the mqtt ser...

  • Page 22

    Smartswarm 300 series : 22 3.5.1 discover your slaves using the “discover” option, you can let the smartswarm device self-learn the modbus slave network. Actually, your smartswarm device has been self-learning already. Your device has been physically connected to the modbus network since the beginni...

  • Page 23

    Smartswarm 300 series : 23 in our example, only one slave device has been discovered on the modbus network. In this case the discovered slave is at address 1. We will refer to this slave as “slave 1” later. Although not shown in this example, you can now edit this slave, and enrich the discovered sl...

  • Page 24

    Smartswarm 300 series : 24 in our example we are going to load a pre-prepared slave-map from a template file. To create the pre-prepared slave-map we took the datasheet of a slave device (an emerson liebert nfinity ups), and we populated the template accordingly. Here’s an example from the modbus “i...

  • Page 25

    Smartswarm 300 series : 25 table 1. Example modbus slave datasheet for discrete inputs we derived the following “inputs” excel sheet information from this datasheet, using the provided excel template. : table 2. Example excel sheet data derived from slave datasheet (inputs).

  • Page 26

    Smartswarm 300 series : 26 note that the address field in our template is declared as the offset from the base address of the register type. In our example the device uses the 10,xxx range for its input status registers. (other devices may use 10x,xxx.) so the first is register (10,001) corresponds ...

  • Page 27

    Smartswarm 300 series : 27 table 4. Example excel sheet data derived from slave datasheet (input registers) next, optionally fill in the “meta” data in the excel sheet: table 5. Example excel sheet meta data now, we’re going to import this pre-prepared excel file into smartworx hub. We click on “loa...

  • Page 28

    Smartswarm 300 series : 28 don’t forget to apply changes. 3.5.3 export slave maps once you have slave maps on your system - whether you created them manually, imported them, or discovered them and subsequently enriched them - you can then export them. This is very useful if you have many slave devic...

  • Page 29

    Smartswarm 300 series : 29 in our example there were some input registers discovered on slave 1 during the “discovery” stage. Go to the input registers tab, and enrich the registers. In our example we’re enriching the slave’s input register data from the slave’s datasheet (an emerson power monitorin...

  • Page 30

    Smartswarm 300 series : 30 there’s a line entry in this table for every discovered register on this slave (even for the non-enriched registers). The mqtt topic has taken custom values, which are derived from the meta data. You may leave these as-is, or you may override the custom-defaults and define...

  • Page 31

    Smartswarm 300 series : 31 publish using the defined mqtt topic “server_room/power_monitor/liebert”, but do not also publish on the “default topic” (see chapter 10). Save rules next: this saves your enrichment and rules to the smartworx hub database. Push rules now: this applies the entire enrichmen...

  • Page 32

    Smartswarm 300 series : 32 we recommend that you choose appropriate mqtt topics for your slave registers, which enable ease-of- use for your solution domain. By defining your topics carefully, you can enable ease-of-consumption of the data. In some cases, you will want to consume the data on dashboa...

  • Page 33

    Smartswarm 300 series : 33 4. Connect your hardware 4.1 mounting the device the unit may be mounted in any orientation. It can be simply placed on a flat surface, or it can be din rail mounted using the supplied ckd2 holder. 4.1.1 installing/removing from a din rail the ckd2 holder, which is used fo...

  • Page 34

    Smartswarm 300 series : 34 4.2 power connector pwr panel socket 2-pin pin ident description 1 gnd(-) negative pole of dc supply voltage 2 vcc(+) positive pole of dc supply voltage (+10 to +60 v dc) table 6. Power connector the unit accepts the connection of power supplies in the range +10 v to +60 v...

  • Page 35

    Smartswarm 300 series : 35 pin signal mark description data flow direction 1 txd+ transmit data – positive pole input/output 2 txd- transmit data – negative pole input/output 3 rxd+ receive data – positive pole input/output 4 — — — 5 — — — 6 rxd- receive data – negative pole input/output 7 — — — 8 —...

  • Page 36

    Smartswarm 300 series : 36 connector purpose default setting eth0 lan port (default) connect your laptop or pc to this port to get a local web-server for device configuration and diagnostics. Dhcp server ip address: 192.168.1.1 netmask: 255.255.255.0 eth1 wan port (default) connect this port to your...

  • Page 37

    Smartswarm 300 series : 37 4.4.2 sim card reader two sim card readers for 3 v and 1.8 v sim cards are placed on the rear panel of the device. Only the first of these (sim1) is currently supported by smartswarm 351. In order to operate on a cellular network it is necessary to insert an activated, dat...

  • Page 38

    Smartswarm 300 series : 38 4.5 rs-232 rs-485 serial interface - connection to modbus network these interfaces are physically connected on five-pin and four-pin terminal block connectors on the front panel. The insulation strength is up to 2.5 kv. Attention, connectors are not isolated from each othe...

  • Page 39

    Smartswarm 300 series : 39 2 tx+ transmit + (do not connect) output 3 rx- receive - input 4 rx+ receive + input table 9. Rs-485 pinout note: this device will only operate in passive (receive-only) mode. It is not possible to configure it as a modbus master, or for it to transmit on the modbus networ...

  • Page 40

    Smartswarm 300 series : 40 2 rts input 3 gnd — 4 rxd input 5 txd output table 10. Rs-232 pinout in order to operate on rs-232 based modbus rtu networks, it is necessary to arrange for the smartswarm 351 to receive information from both the rs-232 transmit and receive signals, in order that it can mo...

  • Page 41

    Smartswarm 300 series : 41 in some situations this is not an issue, but there are some risks with this approach. ● the scada master will see a repeat of its command, followed by the slave reply, and this combination may be rejected as invalid depending upon the characteristics of the scada master dr...

  • Page 42

    Smartswarm 300 series : 42 sim green off reset button pressed or the device is booting on ready for operation. Sim 1 is enabled wan yellow off there is no cellular connection between the smartswarm device and the cellular service provider on a cellular connection has been successfully established be...

  • Page 43

    Smartswarm 300 series : 43 5.1 step 1 - connect to local webserver connect a local laptop or desktop pc to eth0. Open a browser and navigate to 192.168.1.1. Note that if you have another lan connection (e.G. Via wi-fi) you may need to disconnect this second session, depending upon your network setti...

  • Page 44

    Smartswarm 300 series : 44 if a configuration for the device has already been created in smartworx hub it will be automatically downloaded to the device during this first connection. 5.5 factory defaults if the unit is not connecting as expected it may be reset to factory defaults at any time by pre...

  • Page 45

    Smartswarm 300 series : 45 6. Smartswarm 351 on smartworx hub once you have claimed your device on smartworx hub you may edit and configure it. If your device is currently offline, all changes you make are queued. All of your changes will be immediately applied as soon as the device comes online. 6....

  • Page 46

    Smartswarm 300 series : 46 from here you may select the name of the application (“modbus-to-mqtt”) in order to configure the modbus-to- mqtt application. 6.2 the modbus-to-mqtt application the settings for the modbus-to-mqtt application are split into 3 functional areas: functional area description ...

  • Page 47

    Smartswarm 300 series : 47 table 12. The modbus to mqtt application 7. Configure the modbus interface when configuring the modbus interface, please ensure that you match the modbus master configuration on the modbus network you are monitoring. Setting description port rs-232 or rs-485. The smartswar...

  • Page 48

    Smartswarm 300 series : 48 response timeout specifies the maximum time interval, in seconds, in which a response to a command is expected from a connected slave device. If the interval is set too short, valid replies may be missed. If set too long, retries sent by the master may be interpreted as a ...

  • Page 49

    Smartswarm 300 series : 49 setting description host enter the ip address of the mqtt broker. This is the address that the smartswarm 351 will publish mqtt topics to. Port tcp/ip port used by the mqtt broker. The default port for mqtt is 1883 when tls is enabled the default port is 8883. Ensure that ...

  • Page 50

    Smartswarm 300 series : 50 username/password username and password fields may be used to authenticate and authorize the client when connecting. These fields are optional: if you setup your mqtt broker to require them, then you will require them here also. The password is sent in plaintext if it isn’...

  • Page 51

    Smartswarm 300 series : 51 enable tls enable tlsv1.2 as the secure transport layer. Security settings must match the broker settings. Client certificate valid x.509 certificate containing the client’s public key. This certificate will be sent to the broker when the ssl/tls session is established. Cl...

  • Page 52

    Smartswarm 300 series : 52 qos the quality of service level is an agreement between sender and receiver of a message regarding the guarantees of delivering a message. There are 3 qos levels in mqtt: ● at most once (0) ● at least once (1) ● exactly once (2) with qos for mqtt, there are always two dif...

  • Page 53

    Smartswarm 300 series : 53 9. Slave maps and enrichment if you have some knowledge of the modbus network that is being sniffed, you can “enrich” the modbus data by telling the smartswarm device how to interpret these addresses and substitute some more meaningful strings. There are two fundamentally ...

  • Page 54

    Smartswarm 300 series : 54 the “decoder” interface screen displays all the modbus slaves currently known by smartworx hub for this device. When you first use smartworx hub to enrich your new smartswarm device the list of slaves will be empty..

  • Page 55

    Smartswarm 300 series : 55 option method description export maps export your current maps. All of your existing slave maps will be exported to a .Zip archive file. All maps are exported in .Json format. There is one map file for each slave. The .Zip archive will be stored into your browser’s downloa...

  • Page 56

    Smartswarm 300 series : 56 9.1 discover in discover mode you simply wait for your device to learn the network. The time you need to wait depends on the configuration of the modbus master. After waiting for an appropriate period of time, click on “sync maps”. This will pull the learned information in...

  • Page 57

    Smartswarm 300 series : 57 you will now be able to edit these maps to add enrichment data and events. See chapters 9.4, 10 on how to do this. 9.2 create an empty slave map clicking on new map allows you to enter an empty slave map. Enter a slave number between 1 and 247 and click ok. The map is then...

  • Page 58

    Smartswarm 300 series : 58 9.3 import a slave map you may import a complete set of pre-prepared slave and register information, complete with full enrichment. If you wish to do this we recommend that you begin by exporting as much of the mapping information as you can from your modbus control system...

  • Page 59

    Smartswarm 300 series : 59 9.4.1 understanding your slave editor editor button description save save all current changes to the smartworx hub database. Use this button when you want to save your current edits, but you don’t wish to push your edits to the device just yet. If you get interrupted, or s...

  • Page 60

    Smartswarm 300 series : 60 holding registers (4x) rules and topics save rules rules and topics save all current rules/events changes to the smartworx hub database. Use this button while you’re still editing your rules and topics. Push rules rules and topics push all existing (saved) rules/events to ...

  • Page 61

    Smartswarm 300 series : 61 location location user-defined text e.G. Warehouse/room401 manufacturer manufacturer user-defined text (usually the manufacturer of the slave) name name user-defined text e.G. Ahu fan product code product_code user-defined text e.G. Wil-flex-450 byte order value_byte_order...

  • Page 62

    Smartswarm 300 series : 62 on smartworx hub, for each register type, the address entered corresponds with the modbus register offset for that specific register type. E.G. Holding register address 5 corresponds to register 400006 click on the appropriate tab to view registers. 9.4.3.1 input registers...

  • Page 63

    Smartswarm 300 series : 63 name name a description of the register function e.G. Energy meter the name field is not used for any algorithmic purpose within the device: it will become part of the enrichment-data published for this register. Alias alias an alternate name for the register e.G. Power us...

  • Page 64

    Smartswarm 300 series : 64 min min the expected minimum enriched value for this register. For example, if we know that the register value represents temperature with a minimum value of 0 degrees celsius, the value entered here would be “0”. This min field value is not used for any algorithmic purpos...

  • Page 65

    Smartswarm 300 series : 65 str value val this field is only relevant for enum data types. The str value field enables us to specify a string value that we can use to add contextualized meaning to each relevant state of bit-field data. E.G. A 16 bit register may be represented by an enum data type. E...

  • Page 66

    Smartswarm 300 series : 66 from the graph, we can calculate the slope as ???????????????????? = 10 − 0 4095 − 819 = 0.00305 the scaling factor is the inverse of this. It can also be thought of as the “one in x” gradient of the graph. ???????????????????????????? = 1 0.00305 = 327.6 the zero value is where the graph intersects the y-ax...

  • Page 67

    Smartswarm 300 series : 67 ???????????????????? = 0 − ???????????????? ???????????????????? 819 − 0 ???????????????? ???????????????????? = −???????????????????? ???? 819 = −2.5 we can repeat this same example using an enriched value in degrees fahrenheit instead of degrees celsius. The register value ranges from 819 to 4095, corresponding to a temperature range of 32 to 50f. Now the ...

  • Page 68

    Smartswarm 300 series : 68 the zero value is where the graph intersects the y-axis. It can also be thought of as the enriched value that corresponds to a raw value of 0. ???????????????????? = 32 − ???????????????? ???????????????????? 819 − 0 ???????????????? ???????????????????? = 32 − ???????????????????? ???? 819 = +27.5 here’s what these two examples would look like on smartworx ...

  • Page 69

    Smartswarm 300 series : 69 int16 ✔ ✔ ✔ ✔ ✔ ✔ ✔ ✔ ✔ ✔ uint32 ✔ ✔ ✔ ✔ ✔ ✔ ✔ ✔ ✔ ✔ int32 ✔ ✔ ✔ ✔ ✔ ✔ ✔ ✔ ✔ ✔ float32 ✔ ✔ ✔ ✔ ✔ ✔ ✔ ✔ ✔ ✔ string ✔ ✔ ✔ ✔ ✔ ✔ counter ✔ ✔ ✔ ✔ ✔ ✔ ✔ ✔ ✔ table 23. Data types and field values registers which are discovered will have no meaningful information filled in. Some ...

  • Page 70

    Smartswarm 300 series : 70 the nature of a counter also has implications for the type of event that can be triggered by it. See section “events (when)”. 9.4.5 adding registers to add a register click the + icon. This will create a new row with the same values as the current row. Enter the address an...

  • Page 71

    Smartswarm 300 series : 71 in the next example, register 40 is also an enum type which uses the first 3 bits of the register. ● bit 0 has 2 states: “pump off” and “pump on”. ● bit 1 has 2 states: “normal operation” and “min speed” ● bit 2 has 2 states: “normal operation” and “max speed”. Note how on...

  • Page 72

    Smartswarm 300 series : 72 enum data types this could alter the intended meaning of modbus register. Unless you’re sure, we recommend leaving these fields in their default states (zero value = 0; scaling = 1). In the above screenshot registers 65 and 14 are enum types. Register 65 uses two 2-bit val...

  • Page 73

    Smartswarm 300 series : 73 10. Rules and topics 10.1 introduction the smartswarm 351 converts modbus data to mqtt. In the process it adds data enrichment, including scaling factors and meta-data. By default, all data is blocked and nothing is published on mqtt until you specifically allow it. Bear i...

  • Page 74

    Smartswarm 300 series : 74 the published payload data will have all of the enrichment data included. You then specify how you want the data to be published. For example, on what mqtt topic, with what qos, etc. The rules and topics screen is visible as a tab in the editor for each slave. For example:...

  • Page 75

    Smartswarm 300 series : 75 10.2 events (when) on any row in the rules and topics table, click the event field to see the drop-down list of available events: note: only one instance of each event type should be added to a register. Adding multiple events of the same type will have no effect, as only ...

  • Page 76

    Smartswarm 300 series : 76 inputs, coils input registers, holding registers event enum numeric 1 string counter read ✔ ✔ ✔ ✔ ✔ change ✔ ✔ ✔ ✔ ✔ high threshold ✔ low threshold ✔ delta ✔ ✔ high rate ✔ ✔ low rate ✔ ✔ scheduled ✔ ✔ ✔ ✔ ✔ global read ✔ ✔ ✔ ✔ global change ✔ ✔ ✔ ✔ table 26. Events and dat...

  • Page 77

    Smartswarm 300 series : 77 in smartworx hub, when you select this event type. No further configuration is required: 10.2.2 change trigger a publish when an enriched register value changes. This event is applicable to any register type and any data type: inputs, coils input registers, holding registe...

  • Page 78

    Smartswarm 300 series : 78 in smartworx hub, when you select this event type on an input or a coil, no further configuration is required. However, if it is selected on an input register or a holding register, an additional field appears at the top of the table: in the “change by” field, you may ente...

  • Page 79

    Smartswarm 300 series : 79 it is important to remember that the change is measured with respect to the last time the register was observed on modbus, not to the last time it was published on mqtt. In the diagram above, the green bars represent the ±10% change that is dynamically calculated after eac...

  • Page 80

    Smartswarm 300 series : 80 the following example shows a numeric register that ramps monotonically from 0, incrementing by 1 on each modbus master access. The red annotations show when mqtt publishes will be triggered, assuming that a change rule is applied, with “change by” = 10%. ● if the register...

  • Page 81

    Smartswarm 300 series : 81 delta ✔ ✔ table 29. Delta event note: as explained in the counter section, a counter is always increasing. A drop in value is assumed to indicate a single roll-over event. Therefore, for an 8-bit counter (range 0 - 255), a change in value from 254 to 253 is an increase of ...

  • Page 82

    Smartswarm 300 series : 82 10.2.4 high threshol d trigger when the enriched register value increases above a fixed threshold. This event is only applicable to input registers and holding registers, not discrete inputs and coils. It is applicable to numeric data types only. It is not applicable to a ...

  • Page 83

    Smartswarm 300 series : 83 the following rules are stateful: high threshold, low threshold, high rate, low rate. The following example shows a register that follows a sinusoidal waveform. The modbus master is polling the register every 200ms. Assume that a “high threshold” rule is applied, with thre...

  • Page 84

    Smartswarm 300 series : 84 note how 5 mqtt publishes are caused by the multiple threshold crossings. Using a bigger value for hysteresis provides more noise rejection: 10.2.5 low threshold trigger when the enriched register value decreases below a fixed threshold.. This event is only applicable to i...

  • Page 85

    Smartswarm 300 series : 85 when you select the low threshold event type on a register, you must enter two fields: ● the threshold field specifies the value below which the register must decrease in order to trigger an mqtt publish. ● the hysteresis field allows you to prevent multiple mqtt publishes...

  • Page 86

    Smartswarm 300 series : 86 notes: ● on start-up, if the first value is already below the threshold, that is considered a state transition. In this case, the first value of 0 will trigger an mqtt publish. ● when the value increases above the threshold (plus the hysteresis), we publish again. ● when t...

  • Page 87

    Smartswarm 300 series : 87 the change value represents the instantaneous rate of change per second. The mqtt publish will only be triggered if the enriched register value has changed faster than this. Note: this rule is stateful. For example, when the rate threshold is crossed in either direction an...

  • Page 88

    Smartswarm 300 series : 88 in the diagram above the green triangles represent the “10 per second” rate of change against which each new sample is compared when it is received. At the top and bottom of a sine-wave the rate of change is low, so the trigger condition is not met. Even though the rate li...

  • Page 89

    Smartswarm 300 series : 89 the second sample (actually, the first pair of samples) will trigger an mqtt publish, because 50 4 > 10 1 after this the system will remain in the “alarm on” state forever, because the rate of change is always greater than the threshold. No further mqtt messages will be pu...

  • Page 90

    Smartswarm 300 series : 90 inputs, coils input registers, holding registers enum numeric string counter low rate ✔ table 33. Low rate event as for “high rate”, when you select the “low rate” event type on a register you must enter a “change” value, which represents the rate of change per second: not...

  • Page 91

    Smartswarm 300 series : 91 as expected, we get the complement of the previous result for the “high rate” case. The “low rate” event type is roughly equivalent to the “low threshold” event type, but it operates on the derivative of the waveform. However, note that there is no equivalent for rate “hys...

  • Page 92

    Smartswarm 300 series : 92 10.2.9 global read trigger a publish when any register of the selected type has been read (or written) by the modbus master. This event is applicable to any register type and any data type. For a counter it returns the raw value of the register, not the accumulated value. ...

  • Page 93

    Smartswarm 300 series : 93 10.3 payloads (what) for every event type, you can decide what to publish when that event happens. Payload description default only the register that triggered the event will be published. Slave all registers on this slave will be published. Hr all holding registers on thi...

  • Page 94

    Smartswarm 300 series : 94 10.3.1 payload examples 10.3.1.1 the default payload with this rule, if the enriched value of register 1 goes above 100 the payload for register 1 will be published. The published payload data will be in .Json format. For this hr example, the actual enriched register value...

  • Page 95

    Smartswarm 300 series : 95 } }, "type": "modbusslave", "id": "10_hr_1_hi" } 10.3.1.2 the hr payload with this rule, if the enriched value of register 1 goes above 100 the payload data for all holding registers will be published. The num_value in the payload for each of the holding-registers will be ...

  • Page 96

    Smartswarm 300 series : 96 "state": "validated", "var_pct": 2.000000, "at": "2016-07-14t17:38:32.721z", "address": 2, "units": "deg c", "new_value": true, "new_read": true }, { "value_from": "response", published_on": "hi\/on", "name": "hr_3", "min": 0, "address_offset": 0, "max": 90, "zero_value": ...

  • Page 97

    Smartswarm 300 series : 97 if there are no input registers, discrete inputs, or coils defined for the slave, then there will be place-holders in the published json data schema to show where the data for those register values would be, if they existed. If there has not been any actual data seen on mo...

  • Page 98

    Smartswarm 300 series : 98 }], "is": [], "ir": [] }, "meta": { "description": "slave_1", "value_byte_order": "sno", "name": "power_meter", "installation_date": "14\/07\/2016", "location": "test_rack", "address": { "devid": "6500004", "portid": 1, "slaveid": 10, "swmid": 0 }, "manufacturer": "na" } }...

  • Page 99

    Smartswarm 300 series : 99 "value_from": "response", "alias": "this is a coil example", "state": "validated", "var_pct": 0, "new_read": false, "address": 1, "new_value": false, "at": "2016-07-15t15:11:00.373z" }], "hr": [{ "value_from": "response", "published_on": "hi\/off", "name": "hr_1", "min": 0...

  • Page 100

    Smartswarm 300 series : 100 "str_value": "on", "num_value": 1, "value_from": "response", "alias": "ipv", "state": "validated", "var_pct": 100, "new_read": false, "address": 6, "new_value": false, "at": "2016-07-15t15:12:37.350z" }, { "published_on": "hi\/off", "name": "battery status", "str_value": ...

  • Page 101

    Smartswarm 300 series : 101 "zero_value": 0, "num_value": 1491.000000, "scaling": 1, "alias": "opfreq", "state": "validated", "var_pct": 69.000000, "new_read": false, "address": 60, "new_value": false, "at": "2016-07-15t15:14:37.395z" }] }, "meta": { "description": "slave_1", "value_byte_order": "sn...

  • Page 102

    Smartswarm 300 series : 102 "num_value": 1762.000000, "scaling": 1, "alias": "air temperature", "state": "validated", "var_pct": 0, "at": "2016-07-14t19:41:04.109z", "address": 2, "units": "deg c", "new_value": false, "new_read": true }, { "value_from": "response", "published_on": "hi\/on", "name": ...

  • Page 103

    Smartswarm 300 series : 103 for every individual rule, the custom mqtt topic, the default topic, or both, may be disabled. If you are using cellular for the uplink mqtt connection, you are probably limited by bandwidth and/or monthly data usage. The default behavior of the smartswarm 351 is for ever...

  • Page 104

    Smartswarm 300 series : 104 ● if the slave meta data is changed at some point in time the mqtt topic string will not be automatically updated for any existing rules. This is to prevent problems for any mqtt clients which may have already been configured to subscribe to the old topic string. ● the pr...

  • Page 105

    Smartswarm 300 series : 105 if the event is one of the stateful types, then a state value of “off” or “on” is appended. (i.E. For events of type high threshold, low threshold, high rate, low rate.) because the default topic string can not be changed by the user, you can rely on the topic space hiera...

  • Page 106

    Smartswarm 300 series : 106 "slaveid": 1, "swmid": 0 }, "description": "warehouse heaters", "installation_date": "29/03/2016", "location": "test rack", "manufacturer": "carlo gavazzi", "name": "em24", "product_code": " em24.Din.Av9.3.X.Is.X ", value_byte_order": "sword", "version": "1.0" }.

  • Page 107

    Smartswarm 300 series : 107 11. Verify your data flow in order to verify your data flow, we recommend that you verify each step below. Step what to verify reference 1 verify your physical connection to the modbus bus. Section 4.5 appendix 3 2 verify that your smartswarm device has a secure connectio...

  • Page 108

    Smartswarm 300 series : 108 8 verify the mqtt topic that your events will be published on. Section 10 (topics - how) appendix 3 table 40. Verify your data flow.

  • Page 109

    Smartswarm 300 series : 109 12. Other documentation document title where? Modbus serial line protocol and implementation guide http://www.Modbus.Org/docs/modbus_over_serial_line_v1_02.Pdf mqtt and the nist cybersecurity framework” http://docs.Oasis-open.Org/mqtt/mqtt-nist-cybersecurity smartworx hub...

  • Page 110

    Smartswarm 300 series : 110 antenna connectors 2 x sma – 50 ohm user interface 2x eth usb i/o rs-485 rs-232 ethernet (10/100 mbit/s) usb 2.0 (not currently supported) 6-pin panel socket (not currently supported) 4 pin panel socket 5 pin panel socket table 42. Environmental 13.2 type tests table 43 t...

  • Page 111

    Smartswarm 300 series : 111 lte module for emea lte parameters bit rate 100 mbps (dl) / 50 mbps (ul) 3gpp rel. 8 standard supported bandwidths: 5 mhz, 10 mhz, 20 mhz supported frequencies: 800 / 900 / 1800 / 2100 / 2600 mhz hspa+ parameters bit rate 21,1 mbps (dl) / 5,76 mbps (ul) 3gpp rel. 7 standa...

  • Page 112

    Smartswarm 300 series : 112 14. Appendix 2 - general settings 14.1 configurable it ems for every smartswarm device, there are some general settings and options that are available to you. 14.1.1 settings the network settings enable you to configure the operation of the eth ports and the cellular inte...

  • Page 113

    Smartswarm 300 series : 113 we recommend that you do not change the eth0 default settings. By default, eth1 runs as a dhcp client. By default, the cellular interface is not configured. But note that you may have previously configured the cellular interface locally on your device. Changing network se...

  • Page 114

    Smartswarm 300 series : 114 at the time of writing, it is not possible to turn off the dhcp server that runs on eth0. Please be careful not to connect eth0 of the device into a lan port that is also serving dhcp addresses. 14.1.3 openvpn you may configure up to 2 openvpn tunnels to run on your devic...

  • Page 115

    Smartswarm 300 series : 115 before you begin to use an openvpn service, we recommend that you are familiar with the openvpn documentation, which is available here: https://openvpn.Net/index.Php/open-source/documentation/howto.Html#client openvpn enable tunnel enable or disable this tunnel interface....

  • Page 116

    Smartswarm 300 series : 116 key the private key (for the device) that is used to generate the certification request. The certification request is what you send to the certification authority. Table 47. Openvpn fields when openvpn feature is enabled, the client key, the client certificate, and the ca...

  • Page 117

    Smartswarm 300 series : 117 14.1.4 ntp client you may specify up to 4 network time protocol servers for this device. 14.2 non-configurable items 14.2.1 firewall there is a built-in firewall on your smartswarm device. This firewall cannot be re-configured by the user. The default firewall policy is t...

  • Page 118

    Smartswarm 300 series : 118 tunnel* ✔ ✔ ✔ table 48. Firewall rules note that some firewall exception rules will be applied automatically, depending upon whether you have configured openvpn. For example, the *tunnel interface will only exist when you have enabled an openvpn tunnel..

  • Page 119

    Smartswarm 300 series : 119 15. Appendix 3 - diagnostics and troubleshooting there is a local web-server interface on eth0 of the smartswarm device. This interface is intended to be used for two purposes: a) configure the device’s outbound (wan) connectivity (using either the cellular interface, or ...

  • Page 120

    Smartswarm 300 series : 120 there are nine tabs: home; settings; troubleshooting; agents; hub client; cellular; logs; debug and modbus 15.1.1 home from the home tab, you can see some important information about your smartswarm device: ● firmware version ● components version ● serial number ● u-boot ...

  • Page 121

    Smartswarm 300 series : 121.

  • Page 122

    Smartswarm 300 series : 122 15.1.4 hub client using this tab, you can change the default smartworx hub server instance that your device connects. By default, your device will connect to hub.Bb-smartworx.Com using https on port 443. If, for example, you have a hosted instance of smartworx hub, you ca...

  • Page 123

    Smartswarm 300 series : 123 15.1.6 logs the smartswarm device will keep debug message logs internally. During the troubleshooting session it may be important to open the logs tab, and to take a copy of the messages from one of the debug-logs available. To see the logs you must turn on “follow” mode ...

  • Page 124

    Smartswarm 300 series : 124 15.1.8 debug and agents it’s best to use the debug and agents tabs in conjunction with each other. In the debug tab you can see some static debug information and you can select which agent(s) you wish to see run-time information from..

  • Page 125

    Smartswarm 300 series : 125 in the agents tab you can see run-time information (output) from the enabled application agents. Note that, even if an agent has been “enabled” on the debug tab, it will only appear on the agents tab if there is data actually being published by that agent..

  • Page 126

    Smartswarm 300 series : 126 in the screenshots shown here we have enabled the alb002 agent for debug purposes. You can use the alb002 agent to verify that your serial interface is configured correctly. If you enable debug on agent alb002, and your serial interface settings are correct, you should se...

  • Page 127

    Smartswarm 300 series : 127 this is provided so that you can verify your data-flow and data-enrichment process. If you see data streaming through the tsed interface you will know that your complex events are triggering successfully, and there will be data published to the mqtt interface. Note: you w...

  • Page 128

    Smartswarm 300 series : 128 16. Appendix 4 - slave map formats maps may be imported in json or microsoft excel formats. These files are available for download from smartworx hub. 16.1 excel excel can be used to create slave maps. Download the map template file directly from smartworx hub. Most modbu...

  • Page 129

    Smartswarm 300 series : 129 item description devid serial number of the smartswarm 351 device which can be found on the device label portid 0 when interface is rs-232 1 when interface is rs-485 slaveid the number of the slave (1 - 247) swmid this is always 0 table 50. Excel sheet, address tab exampl...

  • Page 130

    Smartswarm 300 series : 130 example of the cs (coils) tab: example of the is (discrete inputs) tab: after completing the sheet, save the sheet with an appropriate filename (e.G. Map-2.Xlsx). This file can now be imported into smartworx hub by clicking the load maps link..

  • Page 131

    Smartswarm 300 series : 131 16.2 json the alternative import-map format is json format. This section will show some examples of appropriate json formatted input maps. The json map below is a minimal example of a slave map with no registers defined. { "id": "", "model": { "meta": { "address": { "devi...

  • Page 132

    Smartswarm 300 series : 132 } ] to add an input register to the map insert the following under the ir section. To add another register, repeat the section separated by a comma. "ir": [ { "address": "3", "name": "power consumption", "datatype": "uint16", "length": "16", "zero_value": "0", "scaling": ...

  • Page 133

    Smartswarm 300 series : 133 "address": 40, "address_offset": 2, "name": "pump command", "alias": "", "datatype": { "enum_type": { "num": [ 0, 1 ], "val": [ "normal operation", "max speed" ] } }, "length": 1, "zero_value": null, "max": null, "min": null, "scaling": null, "units": "", "state": "valida...

  • Page 134

    Smartswarm 300 series : 134 there are a number of ways to specify the addresses of registers in the slave device. Smartswarm 351 uses the convention of a base register type (coil, status, input or holding) and an offset, starting from zero, within that register type. Hence, a register defined within...

  • Page 135

    Smartswarm 300 series : 135 * for output command types, the unit interprets these as inputs to the iot enrichment process. It does not support output of data from the iot system. The following types of data recovered in modbus registers can be interpreted and decoded by smartswarm 351: data type boo...

  • Page 136

    Smartswarm 300 series : 136 17.2 mqtt background mqtt (message queuing telemetry transport) is a transport protocol originally developed in 2001 by ibm and arcom specifically to address the need for reliable, pushed data delivery for m2m systems over unreliable networks. It has subsequently been rel...

  • Page 137

    Smartswarm 300 series : 137 ● a '#' character represents a complete sub-tree of the hierarchy and thus must be the last character in a subscription topic string, such as sensor/#. This will match any topic starting with sensor/, such as sensor/1/temp and sensor/2/humidity. ● a '+' character represen...

  • Page 138

    Smartswarm 300 series : 138 manner. This allows applications to understand the difference between a unit which is not publishing data because nothing has happened, and one which is not publishing data because it has failed – a critical requirement for push based messaging systems. Mqtt summary mqtt ...

  • Page 139

    Smartswarm 300 series : 139 18. Appendix 6 – dashboards having enriched our network and added rules and topics to publish the data we are interested in, we now need a way to display this data. There are several ways to visualize the published data. ● use an mqtt client such as mqtt-spy ● browser ext...

  • Page 140

    Smartswarm 300 series : 140 ● once you have configured the mqtt node, click deploy. Check that the mqtt payload is being received by clicking on the debug node. The output will be printed in the debug tab. ● add the following nodes and connect as per diagram below topics is a switch node which gives...

  • Page 141

    Smartswarm 300 series : 141 sp and pc are json nodes which transform the input into a json object..

  • Page 142

    Smartswarm 300 series : 142 transform is a template node which allows us to select the payload property as an input to another node. In this case, num_value is the payload property that we want. The template will depend on the register type and, in the case of multiple registers, the index of the re...

  • Page 143

    Smartswarm 300 series : 143 rpm is a gauge node on which we will display the oranmore/pump/p1/sp topic. Click the pencil icon to create a new tab called example. This will be the name of the menu on our page which we will click to view the dashboard. Fill in the other fields as per the diagram below...

  • Page 144

    Smartswarm 300 series : 144 power is a chart node on which we will display the oranmore/pump/p1/pc topic. Fill in the other fields as per the diagram below and click ok. In this case we choose the example tab, so it is available under the same menu as the gauge control. Field description tab menu un...

  • Page 145

    Smartswarm 300 series : 145 as the data changes it will automatically update the controls on the page. All the nodes are now configured and connected, and are deployed by clicking deploy. The message successfully deployed will be displayed. Open a new tab in the browser and add the node-red server a...

  • Page 146

    Smartswarm 300 series : 146 advantech b+b smartworx technical support phone: 1-800-346-3119 (monday - friday, 7 a.M. To 5:30 p.M. Cst) fax: 815-433-5109 email: support@advantech-bb.Com web: www . Advantech-bb.Com.