Updated OSH Docs for OSH Connect Python

docs/osh-connect/getting-started/installation.md

@@ -8,26 +8,31 @@ import TabItem from '@theme/TabItem';
 
 # Installation
 
-OSHConnect can be installed in Python and Java, using *pip* (or *poetry*) for Python, and *gradle* for Java.
+OSHConnect can be installed in Python and Java, using *uv* (or *pip*) for Python, and *gradle* for Java.
+
+Before working with OSH Connect, there must be a running OSH Node. Thus, you first must create a OSH [Node](../../osh-node/introduction.md), then you can begin working with connected systems.
 
 **Installing OSHConnect**
 
 **OSHConnect-Python**
 
+OSHConnect is published to [PyPI](https://pypi.org/project/oshconnect/), but
+so far **only as alpha pre-releases** (latest `0.5.1a22`) — there is no stable
+release yet. `pip` and `uv` skip pre-releases by default, so you must opt in:
+
 [*Link to the GitHub Repository*](https://github.com/Botts-Innovative-Research/OSHConnect-Python)
 
-<Tabs>
-    <TabItem value="pip" label="pip" default>
-    ```py
-    pip install git+https://github.com/Botts-Innovative-Research/OSHConnect-Python.git
-    ```
-    </TabItem>
-    <TabItem value="poetry" label="poetry">
-    ```py
-    poetry add git+https://github.com/Botts-Innovative-Research/OSHConnect-Python.git
-    ```
-    </TabItem>
-</Tabs>
+[*Link*](https://botts-innovative-research.github.io/OSHConnect-Python/tutorial.html#creating-an-oshconnect-instance) to a more indepth documentation for OSH Connect - Python 
+
+
+```bash
+pip install "oshconnect==0.5.1a22"               # exact pin auto-allows the alpha
+pip install --pre oshconnect                     # or: latest alpha (note below)
+
+uv add "oshconnect==0.5.1a22"                    # exact pin auto-allows the alpha
+uv add "oshconnect>=0.5.1a0" --prerelease=allow  # or: allow future alphas
+```
+
 
 **OSHConnect-Java**
 

docs/osh-connect/getting-started/usage.md

@@ -11,14 +11,13 @@ For information regarding usage of OSHConnect-JavaScript, please refer to the [O
 :::
 
 ## Instantiating OSHConnect
-The intended method of interacting with OpenSensorHub is through the main OSHConnect class. 
-To do this you must first create an instance of OSHConnect:
+The intended method of interacting with OpenSensorHub is through the main OSHConnect class, which allows for ways to interact with the OSH Node, through different coding langauges. To do this you must first create an instance of OSHConnect:
 <Tabs groupId="oshconnect">
 <TabItem value="python" label="Python">
 ```python
-from oshconnect.oshconnectapi import OSHConnect, TemporalModes
+from oshconnect import OSHConnect, TemporalModes
 
-osh_connect = OSHConnect(name='OSHConnect', playback_mode=TemporalModes.REAL_TIME)
+app = OSHConnect(name='MyApp')
 ```
 </TabItem>
 
@@ -39,18 +38,16 @@ The name parameter is optional, but can be useful for debugging purposes.
 :::
 
 ## Adding a Node
-The next step is to add a Node to the OSHConnect instance. 
-A Node is a representation of a server that you want to connect to. 
+The next step is to add your running Node to the OSHConnect instance. 
+A Node is a representation of a server that you want to be connected to, which can be augmented from your OSH Connect Project. 
 The OSHConnect instance can support multiple Nodes at once.
 <Tabs groupId="oshconnect">
 <TabItem value="python" label="Python">
 ```python
-from oshconnect.oshconnectapi import OSHConnect, TemporalModes
-from oshconnect.osh_connect_datamodels import Node
-
-connect_app = OSHConnect(name='OSHConnect', playback_mode=TemporalModes.REAL_TIME)
-node = Node(protocol='http', address="localhost", port=8585, username="test", password="test")
-connect_app.add_node(node)
+node = Node(protocol='http', address='localhost', port=8585,
+            username='test', password='test',
+            enable_mqtt=True, mqtt_port=1883)
+app.add_node(node)
 ```
 </TabItem>
 
@@ -77,7 +74,7 @@ This is done by calling the system discovery method on the OSHConnect instance.
 <Tabs groupId="oshconnect">
 <TabItem value="python" label="Python">
 ```python
-osh_connect.discover_systems()
+app.discover_systems()
 ```
 </TabItem>
 
@@ -100,7 +97,7 @@ This is done by calling the datastream discovery method on the OSHConnect instan
 <Tabs groupId="oshconnect">
 <TabItem value="python" label="Python">
 ```python
-osh_connect.discover_datastreams()
+app.discover_datastreams()
 ```
 </TabItem>
 
@@ -116,16 +113,34 @@ oshSystem.discoverDatastreams();
 ```
 </TabItem>
 </Tabs>
+
 ## Retrieving Observations
+
 Once you have discovered the datastreams available for a system, you can fetch observations from a datastream.
 This is done by calling the fetch observations method on the OSHDataStream instance.
 <Tabs groupId="oshconnect">
 <TabItem value="python" label="Python">
-TODO
+```python
+from oshconnect import StreamableModes
+import time
+
+for ds in app.get_datastreams():
+	ds.set_connection_mode(StreamableModes.PULL)
+    ds.initialize()
+    ds.start()
+
+time.sleep(2)  # allow messages to arrive
+for ds in app.get_datastreams():
+    while ds.get_inbound_deque():
+        msg = ds.get_inbound_deque().popleft()
+        print(msg)
+```
 </TabItem>
 
 <TabItem value="java" label="Java">
+```java
 TODO
+```
 </TabItem>
 
 <TabItem value="cpp" label="C++">
@@ -143,11 +158,21 @@ The first major step in a common workflow is to add a new system to the OSH Conn
 <Tabs groupId="oshconnect">
 <TabItem value="python" label="Python">
 ```python
-from oshconnect.osh_connect_datamodels import System
-
-new_system = app.insert_system(
-    System(name="Test System", description="Test System Description", label="Test System",
-           urn="urn:system:test"), node)
+from oshconnect import OSHConnect, Node
+
+app = OSHConnect(name='MyApp')
+node = Node(protocol='http', address='localhost', port=8585,
+            username='admin', password='admin')
+app.add_node(node)
+
+new_system = app.create_and_insert_system(
+    system_opts={
+        'name': 'Test System',
+        'description': 'A test system',
+        'uid': 'urn:system:test:001',
+    },
+    target_node=node
+)
 ```
 </TabItem>
 
@@ -182,23 +207,30 @@ so you can be sure that your datastream is valid before inserting it.
 <Tabs groupId="oshconnect">
 <TabItem value="python" label="Python">
 ```python
-from oshconnect.osh_connect_datamodels import Datastream
-
-datarecord_schema = DataRecordSchema(label='Example Data Record', description='Example Data Record Description',
-                                     definition='www.test.org/records/example-datarecord', fields=[])
-time_schema = TimeSchema(label="Timestamp", definition="http://test.com/Time", name="timestamp",
-                         uom=URI(href="http://test.com/TimeUOM"))
-continuous_value_field = QuantitySchema(name='continuous-value-distance', label='Continuous Value Distance',
-                                        description='Continuous Value Description',
-                                        definition='www.test.org/fields/continuous-value',
-                                        uom=UCUMCode(code='m', label='meters'))
-example_text_field = TextSchema(name='example-text-field', label='Example Text Field', definition='www.test.org/fields/example-text-field')
-# add the fields to the datarecord schema, these can also be added added to the datarecord when it is created
-datarecord_schema.fields.append(time_schema)   # TimeSchema is required to be the first field in the datarecord for OSH
-datarecord_schema.fields.append(continuous_value_field)
-datarecord_schema.fields.append(example_text_field)
-# Add the datastream to the system
-datastream = new_system.add_insert_datastream(datarecord_schema)
+from oshconnect import DataRecordSchema, TimeSchema, QuantitySchema, TextSchema
+from oshconnect.api_utils import URI, UCUMCode
+
+datarecord = DataRecordSchema(
+    label='Example Record',
+    description='Example datastream record',
+    definition='http://example.org/records/example',
+    fields=[]
+)
+
+# TimeSchema must be the first field for OSH
+datarecord.fields.append(
+    TimeSchema(label='Timestamp', definition='http://www.opengis.net/def/property/OGC/0/SamplingTime',
+               name='timestamp', uom=URI(href='http://www.opengis.net/def/uom/ISO-8601/0/Gregorian'))
+)
+datarecord.fields.append(
+    QuantitySchema(name='distance', label='Distance', definition='http://example.org/Distance',
+                   uom=UCUMCode(code='m', label='meters'))
+)
+datarecord.fields.append(
+    TextSchema(name='label', label='Label', definition='http://example.org/Label')
+)
+
+datastream = new_system.add_insert_datastream(datarecord)
 ```
 </TabItem>
 
@@ -240,13 +272,15 @@ Upon successfully adding a new datastream to a system, it is now possible to sen
 <Tabs groupId="oshconnect">
 <TabItem value="python" label="Python">
 ```python
+from oshconnect import TimeInstant
+
 datastream.insert_observation_dict({
-    "resultTime": TimeInstant.now_as_time_instant().get_iso_time(),     # resultTime is required for OSH
-    "phenomenonTime": TimeInstant.now_as_time_instant().get_iso_time(), # phenomenonTime is required for OSH
-    "result": {
-        "timestamp": TimeInstant.now_as_time_instant().epoch_time,
-        "continuous-value-distance": 1.0,
-        "example-text-field": "Here is some text"
+    'resultTime': TimeInstant.now_as_time_instant().get_iso_time(),
+    'phenomenonTime': TimeInstant.now_as_time_instant().get_iso_time(),
+    'result': {
+        'timestamp': TimeInstant.now_as_time_instant().epoch_time,
+        'distance': 1.0,
+        'label': 'example observation',
     }
 })
 ```