forked from Botts-Innovative-Research/OSHConnect-Python
-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathtutorial.html
More file actions
290 lines (264 loc) · 23.9 KB
/
tutorial.html
File metadata and controls
290 lines (264 loc) · 23.9 KB
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
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
<!DOCTYPE html>
<html class="writer-html5" lang="en" data-content_root="./">
<head>
<meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>OSH Connect Tutorial — OSHConnect-Python 0.2 documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css?v=b86133f3" />
<link rel="stylesheet" type="text/css" href="_static/css/theme.css?v=19f00094" />
<!--[if lt IE 9]>
<script src="_static/js/html5shiv.min.js"></script>
<![endif]-->
<script src="_static/jquery.js?v=5d32c60e"></script>
<script src="_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
<script src="_static/documentation_options.js?v=10f1778b"></script>
<script src="_static/doctools.js?v=9a2dae69"></script>
<script src="_static/sphinx_highlight.js?v=dc90522c"></script>
<script src="_static/js/theme.js"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="prev" title="API Reference" href="api.html" />
</head>
<body class="wy-body-for-nav">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search" >
<a href="index.html" class="icon icon-home">
OSHConnect-Python
</a>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="search.html" method="get">
<input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
<p class="caption" role="heading"><span class="caption-text">Contents</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="api.html">API Reference</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="#">OSH Connect Tutorial</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#osh-connect-installation">OSH Connect Installation</a></li>
<li class="toctree-l2"><a class="reference internal" href="#creating-an-instance-of-oshconnect">Creating an instance of OSHConnect</a></li>
<li class="toctree-l2"><a class="reference internal" href="#adding-a-node-to-an-oshconnect-instance">Adding a Node to an OSHConnect instance</a></li>
<li class="toctree-l2"><a class="reference internal" href="#system-discovery">System Discovery</a></li>
<li class="toctree-l2"><a class="reference internal" href="#datastream-discovery">Datastream Discovery</a></li>
<li class="toctree-l2"><a class="reference internal" href="#playing-back-data">Playing back data</a></li>
<li class="toctree-l2"><a class="reference internal" href="#accessing-data">Accessing data</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="#resource-insertion">Resource Insertion</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#adding-and-inserting-a-new-system">Adding and Inserting a New System</a></li>
<li class="toctree-l2"><a class="reference internal" href="#adding-and-inserting-a-new-datastream">Adding and Inserting a New Datastream</a></li>
<li class="toctree-l2"><a class="reference internal" href="#inserting-an-observation-into-and-opensensorhub-node">Inserting an Observation into and OpenSensorHub Node</a></li>
</ul>
</li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="index.html">OSHConnect-Python</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="Page navigation">
<ul class="wy-breadcrumbs">
<li><a href="index.html" class="icon icon-home" aria-label="Home"></a></li>
<li class="breadcrumb-item active">OSH Connect Tutorial</li>
<li class="wy-breadcrumbs-aside">
<a href="_sources/tutorial.rst.txt" rel="nofollow"> View page source</a>
</li>
</ul><div class="rst-breadcrumbs-buttons" role="navigation" aria-label="Sequential page navigation">
<a href="api.html" class="btn btn-neutral float-left" title="API Reference" accesskey="p"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
</div>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<section id="osh-connect-tutorial">
<h1>OSH Connect Tutorial<a class="headerlink" href="#osh-connect-tutorial" title="Link to this heading"></a></h1>
<p>OSH Connect for Python is a straightforward library for interacting with OpenSensorHub using OGC API Connected Systems.
This tutorial will help guide you through a few simple examples to get you started with OSH Connect.</p>
<section id="osh-connect-installation">
<h2>OSH Connect Installation<a class="headerlink" href="#osh-connect-installation" title="Link to this heading"></a></h2>
<p>OSH Connect can be installed using <cite>pip</cite>. To install the latest version of OSH Connect, run the following command:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>pip<span class="w"> </span>install<span class="w"> </span>git+https://github.com/Botts-Innovative-Research/OSHConnect-Python.git
</pre></div>
</div>
<p>Or, if you prefer <cite>poetry</cite>:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>poetry<span class="w"> </span>add<span class="w"> </span>git+https://github.com/Botts-Innovative-Research/OSHConnect-Python.git
</pre></div>
</div>
</section>
<section id="creating-an-instance-of-oshconnect">
<h2>Creating an instance of OSHConnect<a class="headerlink" href="#creating-an-instance-of-oshconnect" title="Link to this heading"></a></h2>
<p>The intended method of interacting with OpenSensorHub is through the <cite>OSHConnect</cite> class.
To this you must first create an instance of <cite>OSHConnect</cite>:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">oshconnect.oshconnectapi</span><span class="w"> </span><span class="kn">import</span> <span class="n">OSHConnect</span><span class="p">,</span> <span class="n">TemporalModes</span>
<span class="n">connect_app</span> <span class="o">=</span> <span class="n">OSHConnect</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s1">'OSHConnect'</span><span class="p">,</span> <span class="n">playback_mode</span><span class="o">=</span><span class="n">TemporalModes</span><span class="o">.</span><span class="n">REAL_TIME</span><span class="p">)</span>
</pre></div>
</div>
<div class="admonition tip">
<p class="admonition-title">Tip</p>
<p>The <cite>name</cite> parameter is optional, but can be useful for debugging purposes.
The playback mode determines how the data is retrieved from OpenSensorHub.</p>
</div>
<p>The next step is to add a <cite>Node</cite> to the <cite>OSHConnect</cite> instance. A <cite>Node</cite> is a representation of a server that you want to connect to.
The OSHConnect instance can support multiple Nodes at once.</p>
</section>
<section id="adding-a-node-to-an-oshconnect-instance">
<h2>Adding a Node to an OSHConnect instance<a class="headerlink" href="#adding-a-node-to-an-oshconnect-instance" title="Link to this heading"></a></h2>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">oshconnect.oshconnectapi</span><span class="w"> </span><span class="kn">import</span> <span class="n">OSHConnect</span><span class="p">,</span> <span class="n">TemporalModes</span>
<span class="kn">from</span><span class="w"> </span><span class="nn">oshconnect.osh_connect_datamodels</span><span class="w"> </span><span class="kn">import</span> <span class="n">Node</span>
<span class="n">connect_app</span> <span class="o">=</span> <span class="n">OSHConnect</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s1">'OSHConnect'</span><span class="p">,</span> <span class="n">playback_mode</span><span class="o">=</span><span class="n">TemporalModes</span><span class="o">.</span><span class="n">REAL_TIME</span><span class="p">)</span>
<span class="n">node</span> <span class="o">=</span> <span class="n">Node</span><span class="p">(</span><span class="n">protocol</span><span class="o">=</span><span class="s1">'http'</span><span class="p">,</span> <span class="n">address</span><span class="o">=</span><span class="s2">"localhost"</span><span class="p">,</span> <span class="n">port</span><span class="o">=</span><span class="mi">8585</span><span class="p">,</span> <span class="n">username</span><span class="o">=</span><span class="s2">"test"</span><span class="p">,</span> <span class="n">password</span><span class="o">=</span><span class="s2">"test"</span><span class="p">)</span>
<span class="n">connect_app</span><span class="o">.</span><span class="n">add_node</span><span class="p">(</span><span class="n">node</span><span class="p">)</span>
</pre></div>
</div>
</section>
<section id="system-discovery">
<h2>System Discovery<a class="headerlink" href="#system-discovery" title="Link to this heading"></a></h2>
<p>Once you have added a Node to the OSHConnect instance, you can discover the systems that are available on that Node.
This is done by calling the <cite>discover_systems()</cite> method on the OSHConnect instance.</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">connect_app</span><span class="o">.</span><span class="n">discover_systems</span><span class="p">()</span>
</pre></div>
</div>
</section>
<section id="datastream-discovery">
<h2>Datastream Discovery<a class="headerlink" href="#datastream-discovery" title="Link to this heading"></a></h2>
<p>Once you have discovered the systems that are available on a Node, you can discover the datastreams that are available to those
systems. This is done by calling the <cite>discover_datastreams</cite> method on the OSHConnect instance.</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">connect_app</span><span class="o">.</span><span class="n">discover_datastreams</span><span class="p">()</span>
</pre></div>
</div>
</section>
<section id="playing-back-data">
<h2>Playing back data<a class="headerlink" href="#playing-back-data" title="Link to this heading"></a></h2>
<p>Once you have discovered the datastreams that are available on a Node, you can play back the data from those datastreams.
This is done by calling the <cite>playback_streams</cite> method on the OSHConnect instance.</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">connect_app</span><span class="o">.</span><span class="n">playback_streams</span><span class="p">()</span>
</pre></div>
</div>
</section>
<section id="accessing-data">
<h2>Accessing data<a class="headerlink" href="#accessing-data" title="Link to this heading"></a></h2>
<p>To access the data retrieved from the datastreams, you need to access the messages available to the OSHConnect instance.
Calling the <cite>get_messages</cite> method on the OSHConnect instance will return a list of <cite>MessageWrapper</cite> objects that contain individual
observations.</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">messages</span> <span class="o">=</span> <span class="n">connect_app</span><span class="o">.</span><span class="n">get_messages</span><span class="p">()</span>
<span class="k">for</span> <span class="n">message</span> <span class="ow">in</span> <span class="n">messages</span><span class="p">:</span>
<span class="nb">print</span><span class="p">(</span><span class="n">message</span><span class="p">)</span>
<span class="c1"># or, to access the individual observations</span>
<span class="k">for</span> <span class="n">message</span> <span class="ow">in</span> <span class="n">messages</span><span class="p">:</span>
<span class="k">for</span> <span class="n">observation</span> <span class="ow">in</span> <span class="n">message</span><span class="o">.</span><span class="n">observations</span><span class="p">:</span>
<span class="n">do_something_with</span><span class="p">(</span><span class="n">observation</span><span class="p">)</span>
</pre></div>
</div>
</section>
</section>
<section id="resource-insertion">
<h1>Resource Insertion<a class="headerlink" href="#resource-insertion" title="Link to this heading"></a></h1>
<p>Other use cases of the OSH Connect library may involve inserting new resources into OpenSensorHub or another Connected Systems API server.</p>
<section id="adding-and-inserting-a-new-system">
<h2>Adding and Inserting a New System<a class="headerlink" href="#adding-and-inserting-a-new-system" title="Link to this heading"></a></h2>
<p>The first major step in a common workflow is to add a new system to the OSH Connect instance.
There are a couple of ways to do this, but the recommended method is as follows:</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>The <cite>insert_system</cite> method requires a <cite>Node</cite> object to be passed in as the second argument.
Creating one is covered in an earlier section.</p>
</div>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">oshconnect.osh_connect_datamodels</span><span class="w"> </span><span class="kn">import</span> <span class="n">System</span>
<span class="n">new_system</span> <span class="o">=</span> <span class="n">app</span><span class="o">.</span><span class="n">insert_system</span><span class="p">(</span>
<span class="n">System</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s2">"Test System"</span><span class="p">,</span> <span class="n">description</span><span class="o">=</span><span class="s2">"Test System Description"</span><span class="p">,</span> <span class="n">label</span><span class="o">=</span><span class="s2">"Test System"</span><span class="p">,</span>
<span class="n">urn</span><span class="o">=</span><span class="s2">"urn:system:test"</span><span class="p">),</span> <span class="n">node</span><span class="p">)</span>
</pre></div>
</div>
</section>
<section id="adding-and-inserting-a-new-datastream">
<h2>Adding and Inserting a New Datastream<a class="headerlink" href="#adding-and-inserting-a-new-datastream" title="Link to this heading"></a></h2>
<p>Once you have a <cite>System</cite> object, you can add a new datastream to it. This is one of the more complex operations
in the library as the schema is very flexible by design. Luckily, the schemas are validated by the underlying data
models, so you can be sure that your datastream is valid before inserting it.</p>
<div class="admonition caution">
<p class="admonition-title">Caution</p>
<p>Some implementations of the Connected Systems API may require additional fields to be filled in.
OSH Connect is primarily focused on the OpenSensorHub implementation, but does not some of the fields that
are required by and OpenSensorHub node.</p>
</div>
<p>In this example, we will add a new datastream to the <cite>new_system</cite> object that we created in the previous example.
You’ll note the creation of a <cite>DataRecordSchema</cite> object, in OSH’s implementation, a DataRecord is the root of all
datastream schemas.</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">oshconnect.osh_connect_datamodels</span><span class="w"> </span><span class="kn">import</span> <span class="n">Datastream</span>
<span class="n">datarecord_schema</span> <span class="o">=</span> <span class="n">DataRecordSchema</span><span class="p">(</span><span class="n">label</span><span class="o">=</span><span class="s1">'Example Data Record'</span><span class="p">,</span> <span class="n">description</span><span class="o">=</span><span class="s1">'Example Data Record Description'</span><span class="p">,</span>
<span class="n">definition</span><span class="o">=</span><span class="s1">'www.test.org/records/example-datarecord'</span><span class="p">,</span> <span class="n">fields</span><span class="o">=</span><span class="p">[])</span>
<span class="n">time_schema</span> <span class="o">=</span> <span class="n">TimeSchema</span><span class="p">(</span><span class="n">label</span><span class="o">=</span><span class="s2">"Timestamp"</span><span class="p">,</span> <span class="n">definition</span><span class="o">=</span><span class="s2">"http://test.com/Time"</span><span class="p">,</span> <span class="n">name</span><span class="o">=</span><span class="s2">"timestamp"</span><span class="p">,</span>
<span class="n">uom</span><span class="o">=</span><span class="n">URI</span><span class="p">(</span><span class="n">href</span><span class="o">=</span><span class="s2">"http://test.com/TimeUOM"</span><span class="p">))</span>
<span class="n">continuous_value_field</span> <span class="o">=</span> <span class="n">QuantitySchema</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s1">'continuous-value-distance'</span><span class="p">,</span> <span class="n">label</span><span class="o">=</span><span class="s1">'Continuous Value Distance'</span><span class="p">,</span>
<span class="n">description</span><span class="o">=</span><span class="s1">'Continuous Value Description'</span><span class="p">,</span>
<span class="n">definition</span><span class="o">=</span><span class="s1">'www.test.org/fields/continuous-value'</span><span class="p">,</span>
<span class="n">uom</span><span class="o">=</span><span class="n">UCUMCode</span><span class="p">(</span><span class="n">code</span><span class="o">=</span><span class="s1">'m'</span><span class="p">,</span> <span class="n">label</span><span class="o">=</span><span class="s1">'meters'</span><span class="p">))</span>
<span class="n">example_text_field</span> <span class="o">=</span> <span class="n">TextSchema</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s1">'example-text-field'</span><span class="p">,</span> <span class="n">label</span><span class="o">=</span><span class="s1">'Example Text Field'</span><span class="p">,</span> <span class="n">definition</span><span class="o">=</span><span class="s1">'www.test.org/fields/example-text-field'</span><span class="p">)</span>
<span class="c1"># add the fields to the datarecord schema, these can also be added added to the datarecord when it is created</span>
<span class="n">datarecord_schema</span><span class="o">.</span><span class="n">fields</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">time_schema</span><span class="p">)</span> <span class="c1"># TimeSchema is required to be the first field in the datarecord for OSH</span>
<span class="n">datarecord_schema</span><span class="o">.</span><span class="n">fields</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">continuous_value_field</span><span class="p">)</span>
<span class="n">datarecord_schema</span><span class="o">.</span><span class="n">fields</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">example_text_field</span><span class="p">)</span>
<span class="c1"># Add the datastream to the system</span>
<span class="n">datastream</span> <span class="o">=</span> <span class="n">new_system</span><span class="o">.</span><span class="n">add_insert_datastream</span><span class="p">(</span><span class="n">datarecord_schema</span><span class="p">)</span>
</pre></div>
</div>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>A TimeSchema is required to be the first field in the DataRecordSchema for OSH.</p>
</div>
</section>
<section id="inserting-an-observation-into-and-opensensorhub-node">
<h2>Inserting an Observation into and OpenSensorHub Node<a class="headerlink" href="#inserting-an-observation-into-and-opensensorhub-node" title="Link to this heading"></a></h2>
<p>Upon successfully adding a new datastream to a system, it is now possible to send observation data to the node.</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">datastream</span><span class="o">.</span><span class="n">insert_observation_dict</span><span class="p">({</span>
<span class="s2">"resultTime"</span><span class="p">:</span> <span class="n">TimeInstant</span><span class="o">.</span><span class="n">now_as_time_instant</span><span class="p">()</span><span class="o">.</span><span class="n">get_iso_time</span><span class="p">(),</span> <span class="c1"># resultTime is required for OSH</span>
<span class="s2">"phenomenonTime"</span><span class="p">:</span> <span class="n">TimeInstant</span><span class="o">.</span><span class="n">now_as_time_instant</span><span class="p">()</span><span class="o">.</span><span class="n">get_iso_time</span><span class="p">(),</span> <span class="c1"># phenomenonTime is required for OSH</span>
<span class="s2">"result"</span><span class="p">:</span> <span class="p">{</span>
<span class="s2">"timestamp"</span><span class="p">:</span> <span class="n">TimeInstant</span><span class="o">.</span><span class="n">now_as_time_instant</span><span class="p">()</span><span class="o">.</span><span class="n">epoch_time</span><span class="p">,</span>
<span class="s2">"continuous-value-distance"</span><span class="p">:</span> <span class="mf">1.0</span><span class="p">,</span>
<span class="s2">"example-text-field"</span><span class="p">:</span> <span class="s2">"Here is some text"</span>
<span class="p">}</span>
<span class="p">})</span>
</pre></div>
</div>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>The <cite>resultTime</cite> and <cite>phenomenonTime</cite> fields are required for OSH.
The <cite>result</cite> field is representative of the schemas included in the DataRecordSchema’s fields.
You’ll notice that they are referred to by their <cite>name</cite> field in the schema as it is the “machine” name
of the output.</p>
</div>
</section>
</section>
</div>
</div>
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
<a href="api.html" class="btn btn-neutral float-left" title="API Reference" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
</div>
<hr/>
<div role="contentinfo">
<p>© Copyright 2024, Botts Innovative Research, Inc..</p>
</div>
Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
<a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
</div>
</div>
</section>
</div>
<script>
jQuery(function () {
SphinxRtdTheme.Navigation.enable(true);
});
</script>
</body>
</html>