-
Notifications
You must be signed in to change notification settings - Fork 0
/
index.html
268 lines (231 loc) · 18.7 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Connection Guide for Revolution Pi and Cumulocity</title>
<link href="https://fonts.googleapis.com/css2?family=Ubuntu:wght@400;700&display=swap" rel="stylesheet">
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.0.0-beta3/css/all.min.css">
<link rel="stylesheet" href="styles.css">
</head>
<body>
<div class="guide">
<h1>Guide to Connecting the Revolution Pi with Cumulocity Using Thin-edge.io</h1>
<div class="table-of-contents">
<h2>Table of Contents</h2>
<ul>
<li><a href="#introduction">Introduction</a></li>
<li><a href="#revpi-setup">Setting Up Your Revolution Pi</a>
<ul>
<li><a href="#wiring">Wiring and Power Connection</a></li>
<li><a href="#ssh">Setting Up SSH Access</a></li>
<li><a href="#updates">System Updates and Installing Additional Packages</a></li>
</ul>
</li>
<li><a href="#cumulocity-client">Installing and Configuring the Cumulocity Client</a>
<ul>
<li><a href="#create-certs">Creating and Uploading Certificates</a></li>
<li><a href="#start-tedge">Starting the Thin-edge.io Client</a></li>
<li><a href="#send-measurement">Testing - Sending Measurement Values</a></li>
<li><a href="#check-tedge">Verifying Data Reception</a></li>
</ul>
</li>
<li><a href="#sending-data">Sending RevPi's IO Data to the Thin-Edge Connector</a>
<ul>
<li><a href="#admin-interface">Accessing RevPi's Admin Interface</a></li>
<li><a href="#configure-ios">Configure IOs and Fieldbus Data on the Revolution Pi</a></li>
<li><a href="#send-values">Send Connected Values to the Thin-edge Client</a></li>
</ul>
</li>
<li><a href="#cumulocity-features">Activate cumulocity device management features</a>
</li>
</ul>
</div>
<section id="introduction">
<h2>Introduction</h2>
<p>This guide provides comprehensive instructions for connecting a Revolution Pi to the Cumulocity IoT platform using Thin-Edge.io, covering installation, configuration, and data transmission.</p>
</section>
<section id="revpi-setup">
<h2>Setting up your Revolution Pi</h2>
<section id="wiring">
<h3>Wiring & Power Connection</h3>
<p>Use either a <a href="https://www.amazon.com/s?k=24V+DIN+rail+power+supply&crid=1N0CKS5KTR1JT&sprefix=24v+din+rail+power+supply%2Caps%2C249&ref=nb_sb_noss_1"> 24V DC DIN rail power supply</a> or for desktop use, use a <a href="https://www.amazon.com/s?k=24V+DC+30W+plug-in+power+adapter&crid=X0CNIC6WNPQE&sprefix=24v+dc+30w+plug-in+power+adapter%2Caps%2C476&ref=nb_sb_noss">24V DC plug-in power adapter</a> to power the Revolution Pi. A typical power adapter should have at least 30W. Use a <a href="https://www.amazon.com/s?k=barrel+pigtail+connector+female+open+wire+ends&crid=11GQLQQMV6SPK&sprefix=barrel+pigtail+connector+female+open+wire+ends+%2Caps%2C213&ref=nb_sb_noss">barrel jack pigtail connector with open wire ends</a> to connect it to the RevPi.</p>
<h3>Establishing Network Connection</h3>
<p>After powering up, connect the Revolution Pi to your network using an Ethernet cable. Access the device by navigating to <code>http://revpi1234.local</code> in a web browser, where <code>1234</code> represents the serial number found on the front of the Revolution Pi.</p>
</section>
<section id="ssh">
<h3>Setting up SSH Access</h3>
<h4>For macOS Users</h4>
<p>To connect to your device via SSH on macOS, follow these steps:</p>
<ol>
<li>Open the Terminal application. You can find it in Applications > Utilities > Terminal.</li>
<li>Type the following command and press Enter:
<div class="code-block">
<pre><code>ssh pi@revpi<SERIAL-NUMBER>.local</code></pre>
<button class="copy-btn"><i class="fa fa-copy"></i> Copy</button>
</div>
</li>
<li>Replace <SERIAL-NUMBER> with the actual serial number of your device. This is usually found on the front of your RevPi device.</li>
<li>When prompted, enter the password provided on the sticker located on the right side of your device.</li>
</ol>
<p>Ensure your macOS and the device are on the same network to facilitate the connection.</p>
<h4>For Windows 7/10/11 Users</h4>
<p>Windows users will need to ensure they have an SSH client installed. Windows 10 and 11 have a built-in SSH client in Command Prompt or PowerShell, while Windows 7 users may need to install one, such as PuTTY.</p>
<ol>
<li>For Windows 10/11:
<ol type="a">
<li>Open Command Prompt or PowerShell.</li>
<li>Type the following command and press Enter:
<div class="code-block">
<pre><code>ssh pi@revpi<SERIAL-NUMBER>.local</code></pre>
<button class="copy-btn"><i class="fa fa-copy"></i> Copy</button>
</div>
</li>
</ol>
</li>
<li>For Windows 7:
<ol type="a">
<li>Download and install PuTTY from <a href="https://www.putty.org/">https://www.putty.org/</a>.</li>
<li>Open PuTTY and enter <code>revpi<SERIAL-NUMBER>.local</code> in the 'Host Name' field.</li>
<li>Ensure the connection type is set to SSH.</li>
<li>Click 'Open' to initiate the connection.</li>
</ol>
</li>
<li>In both cases, replace <SERIAL-NUMBER> with your device's serial number, as found on the device.</li>
<li>When prompted, use the password located on the sticker on the right side of your device.</li>
</ol>
<p>Make sure your computer and the device are connected to the same network.</p>
</section>
<section id="updates">
<h3>System Updates and Installing Additional Packages</h3>
<p>Once logged in via SSH:</p>
<div class="code-block">
<pre><code>sudo apt update && sudo apt upgrade && sudo apt dist-upgrade</code></pre>
<button class="copy-btn"><i class="fa fa-copy"></i> Copy</button>
</div> <p><strong>Explanation:</strong> This command sequence updates the list of available packages, upgrades all installed packages to their latest versions, and then performs a distribution upgrade.</p>
<p><strong>Estimated Duration:</strong> The total time can vary significantly based on your system’s internet speed, the number of updates, and the Revolution Pi model. It some cases it can take more than 15 minutes.</p>
<div class="code-block">
<pre><code>sudo apt install mqtt-revpi-client opcua-revpi-server</code></pre>
<button class="copy-btn"><i class="fa fa-copy"></i> Copy</button>
</div>
<p><strong>Explanation:</strong> Installs the packages for No-Code OPC-UA and MQTT support.</p>
</section>
<section id="cumuzlocity-client">
<h2>Installing and configuring the cumulocity client</h3>
<h3>Download and install the Thin-Edge.io client</h3>
<div class="code-block">
<pre><code>curl -fsSL https://thin-edge.io/install.sh | sh -s</code></pre>
<button class="copy-btn"><i class="fa fa-copy"></i> Copy</button>
</div>
<h3>Configuring Thin-edge.io</h3>
<p>Configure the Cumulocity IoT tenant URL:</p>
<div class="code-block">
<pre><code>sudo tedge config set c8y.url your-tenant.cumulocity.com</code></pre>
<button class="copy-btn"><i class="fa fa-copy"></i> Copy</button>
</div>
<p>Replace your-tenant.cumulocity.com with your actual tenant link without the https. aIf you don't have a cumulocity account yet, you can go to the cumulocity website and register a demo account.</p>
<h3 id="create-certs">Creating and Uploading Certificates</h3>
<p>Your device will authenticate with the cloud using a certificate. You have to create and upload a certificate for each device.</p>
<div class="code-block">
<pre><code>sudo tedge cert create --device-id revpi<SERIAL-NUMBER></code></pre>
<button class="copy-btn"><i class="fa fa-copy"></i> Copy</button>
</div>
<p>Replace SERIAL-NUMBER with your device's serial number.</p>
<div class="code-block">
<pre><code>sudo tedge cert upload c8y --user "your_username@example.com"</code></pre>
<button class="copy-btn"><i class="fa fa-copy"></i> Copy</button>
</div>
<p>Replace <code>"your_username@example.com"</code> with your actual Cumulocity user account detaiLS. If you get an error message 403 forbidden, please go to cumulocity's user management and add the role tenant admin.</p>
<h3 id="start-tedge">Starting the Thin-edge.io Client</h3>
<p>Start the tedge client to ensure it can connect to Cumulocity:</p>
<div class="code-block">
<pre><code>sudo tedge connect c8y</code></pre>
<button class="copy-btn"><i class="fa fa-copy"></i> Copy</button>
</div>
<p>This command will start the tedge client and establish a connection to the Cumulocity cloud using MQTT.</p>
<h3 id="send-measurement">Testing - Sending Measurement Values</h3>
<p>Send a test measurement to Cumulocity to verify connectivity:</p>
<div class="code-block">
<pre><code>tedge mqtt pub 'c8y/s/us' '211,100'</code></pre>
<button class="copy-btn"><i class="fa fa-copy"></i> Copy</button>
</div>
<p>This command sends a temperature measurement (type 211) with a value of 100 to Cumulocity.</p>
<h3 id="check-tedge">Verifying Data Reception</h3>
<p>Verify that the measurement has been received by checking in the Cumulocity UI:</p>
<p>You can log into your Cumulocity account and navigate to the 'Device Management' section to view the 'Measurements' tab for your device.</p>
<p>Now reboot your revolution pi ,so taht the installed packages all get loaded.</p>
<div class="code-block">
<pre><code>sudo reboot</code></pre>
<button class="copy-btn"><i class="fa fa-copy"></i> Copy</button>
</div>
</section>
<section id="revpi-data">
<h2 id="sending-data">Sending RevPi's IO Data to the Thin-Edge connector</h2>
<p>Like PLCs, Revolution Pi has a process image. That's a central space where all values from IOs and connected fieldbus devices are stored. The process image helps you to have a single source of truth for all IO data and a single point, all the software you are using can connect to. The web tool Pictory provided on the admin website of your RevPi allows you to configure the process image and provide names for your IOs. It also offers No-Code connectors for MQTT, OPC-UA, MODBUS and more.</p>
<h3 id="admin-interface">Accessing Revpi's admin interface</h3>
<p>Navigate to the RevPi's web interface by entering the following URL in a browser, replacing <code><serial></code> with the device's serial number:</p>
<pre><code>http://revpi<serial>.local</code></pre>
<p>Upon accessing the URL, a security warning may appear due to the use of an HTTP connection. This section explains how to proceed safely.</p>
<p>There will be a security warning.</p>
<p><strong>In Firefox:</strong> Click 'Advanced...', then select 'Accept the Risk and Continue' to proceed to the website.</p>
<p><strong>In Chrome:</strong> Click 'Advanced' and then choose 'Proceed to revpi<serial>.local (unsafe)' to access the site.</p>
<div class="info-box">
<h3>Why is there a warning?</h3>
<p>The warning comes, becuase for HTTPS encryption the customer has to create an own SSL/TLS certificate. As this has not been done yet, the system is showing the message. As long as the RevPi is in a local network, this is okay but it can be changed by your IT by providing certificates.</p>
</div>
<h3 id="configure-ios">Configure IOs and Fieldbus Data on the Revolution Pi Using Pictory</h3>
<p>This steps enable your Revolution Pi to interact with a variety of sensors and actuators through configured IO modules.</p>
<p>To configure analog or digital IOs on your Revolution Pi, start by logging into the admin web interface. Use the username <code>admin</code> and the password found on the sticker on the right side of your Revolution Pi.</p>
<ol>
<li>After logging in, click the 'Start Pictory' button to launch the Pictory graphical editor.</li>
<li>In the Pictory editor, you will see a graphical representation of your Revolution Pi. On the left, there is a panel with various devices such as Analog IO (AIO), Digital IO (DIO), and virtual devices for fieldbusses like Modbus TCP.</li>
<li>Drag and drop the desired devices (AIO, DIO, or fieldbus modules) from the panel to your Revolution Pi diagram to add them.</li>
<li>Click on the newly added AIO or DIO on your diagram to configure their settings. Here, you can rename the inputs and outputs and check the 'Export' checkbox if the data should be sent to Cumulocity.</li>
<li>For fieldbusses like Modbus TCP, add them as virtual devices and configure as necessary for your network setup.</li>
</ol>
<h3 id="send-values">Send Connected Values to the Thin-edge Client</h3>
<p>The Cumulocity client, thin-edge, facilitates communication with Cumulocity IoT via MQTT. This integration includes an MQTT broker as part of thin-edge. Follow the steps below to set up the MQTT client that sends data from the Revolution Pi to the thin-edge MQTT broker.</p>
<h4>Option 1: No-code with Pictory</h4>
<p>The Revolution Pi admin tool pictory is capable of sending values from RevPi to Cumulocity in fixed intervals.</p>
<ol>
<li>Within the Pictory graphical editor, drag the virtual device labeled 'MQTT' to the right side of your Revolution Pi.</li>
<li>Click on the MQTT device in your diagram to open its settings dialog.</li>
<li>Set the server to "localhost" to ensure the MQTT client communicates with the local MQTT broker provided by thin-edge. Keep all other settings at their default values.</li>
<li>Save your configurations with "Save as start config" then click "reset driver" to ensure all settings are applied and active.</li>
</ol>
<p>Now all vlaue on the Revolution Pi with an active export checkbox will be transmitted to Cumulocity and will be visible in the device telemetry.</p>
<p>For this you might need an updated versionb of Pictory toop make sure Meaurements are send as JSON. Otherwise they will be sent but don't show up in the measurements in cumulocity.</p>
<h4>Option 2: NodeRed</h4>
<p>You can use NodeRed on the Revolution Pi to send values to thin-edge's local mosquitto broker. Therefore use an MQTT node and configure it to localhost.
Make sure you send you values as JSON in the format described in the Thin-Edge documentation section "Sending measurements".
</p>
<h4>Option 3: Codesys</h4>
<p>
If your background is PLC programming, you might like to install and use Codesys. Codesys helps you to program structured text, ladder diagrams and function blocks. It also has an MQTT client that you can use to send Measurements and Alarms.
</p>
<h4>Option 4: Python</h4>
<p>
If you like to program in python, you can use the RevPiModIo2 Library to interact with Revolution Pi IOs and python libraries for MQTT to send them to This-Edge's local MQTT broker.
</p>
</section>
<section id="cumulocity-features">
<h3>Activate cumulocity device management features</h3>
<p>Revolution is capable of using all device features Cumulocity has to offer.</p>
<ul>
<li>Measurements</li>
<li>Warnings / Alarms</li>
<li>Configuration Management</li>
<li>Software Management</li>
<li>Logfile retrieval</li>
<li>Remote Actions</li>
<li>Container Management</li>
<li>Remote Access via SSH</li>
<li>Remote Access via VNC</li>
</ul>
<p>Please refer to the Cumulocity team on how to configure this.</p>
</section>
</section>
</div>
<script src="script.js"></script>
</body>
</html>