Merge branch 'main' of github.com:Robopipe/api

Author: adamberkes

docs/api/rest-api-reference/cameras.md

@@ -35,3 +35,31 @@ If you're using PoE devices, make sure that they are connected to a network with
 {% swagger src="../../.gitbook/assets/oas.yml" path="/cameras/{mxid}/ir" method="post" %}
 [oas.yml](../../.gitbook/assets/oas.yml)
 {% endswagger %}
+
+## IR Perception
+
+The PRO line-up of Luxonis devices has notch IR filters at 940nm on the stereo camera pair, which allows both visible light and IR light from illumination LED/laser dot projector to be perceived by the camera.
+
+{% hint style="warning" %}
+This product is classified as a **Class 1 Laser Product** under the **EN/IEC 60825-1, Edition 3 (2014)** internationally. You should take safety precautions when working with this product.
+{% endhint %}
+
+{% hint style="info" %}
+RGB cameras do not perceive IR light, only monochromatic sensors have IR perception.
+{% endhint %}
+
+### Dot Projector
+
+A laser dot projector emits numerous tiny dots in front of the device, aiding in disparity matching, particularly on surfaces with low visual features or texture, such as walls or floors. This method, known as ASV (Active Stereo Vision), functions similarly to passive stereo vision but incorporates active depth enhancement.
+
+### Flood IR (Led)
+
+LED lighting enables visibility in environments with minimal or no light. It allows you to execute AI or computer vision (CV) tasks on frames illuminated by the infrared (IR) LED.
+
+{% swagger src="../../.gitbook/assets/oas.yml" path="/cameras/{mxid}/ir" method="get" %}
+[oas.yml](../../.gitbook/assets/oas.yml)
+{% endswagger %}
+
+{% swagger src="../../.gitbook/assets/oas.yml" path="/cameras/{mxid}/ir" method="post" %}
+[oas.yml](../../.gitbook/assets/oas.yml)
+{% endswagger %}

docs/controller/os.md

@@ -1,2 +1,43 @@
 # OS
 
+## Description
+
+Robopipe OS is a custom pre-configured OS image based on [Debian](https://www.debian.org/). It comes with all the packages and tools you need to build a AI/CV application pre-installed. You can find all releases along with the configuration scripts in [this repository](https://github.com/Robopipe/OS).
+
+## Default configuration
+
+### Users
+
+The default user you should use when working on the controller directly is `admin`. The password is `robopipe.io`.
+
+### Hostname & mDNS
+
+A hostname is assigned to the controller on startup. The assigned hostname is in the format `robopipe-<id>`, where _id_ is determined dynamically on each startup. When the controller is started it will scan the local network, and assign itself the lowest possible _id_ which is not already taken. This means that the first controller you start will have _id_ 1, the next will have _id_ 2 and so on. At the same time, it will also broadcast an [mDNS](https://en.wikipedia.org/wiki/Multicast_DNS) record based on its hostname (`robopipe-<id>.local`). This means that the controller can be addresses not only by its IP address, but also by its hostname in the local network. This behaviour is enabled via `robopipehostname` service, if you wish to disable it, you can do so using:
+
+```bash
+sudo systemctl disable robopipehostname # this will take effect on the next startup
+```
+
+### SSH
+
+SSH server is running on the controller by default on port 22.
+
+### Robopipe API
+
+Robopipe API is configured to start automatically at startup. If you wish to disable this, you can do so using:
+
+```bash
+sudo systemctl disable robopipeapi
+```
+
+## Service Mode
+
+Sevice mode is used for backing up the operating system, uploading new OS images or restoring access to the unit. This mode does not publish an mDNS record.
+
+### Entering the Service Mode
+
+* Turn off the controller
+* Press and hold the _SERVICE_ button on your controller (usually located next to USB labels)
+* Turn on the controller while still hodling the _SERVICE_ button
+* Release the _SERVICE_ button when all the LEDs start blinking periodically
+

docs/getting-started/connection.md

@@ -24,16 +24,16 @@ Connect the luxonis camera directly to the controller via USB and then connect t
 
 ### Accessing the controller
 
-The easiest way to check if everything is running is to head over to `http://robopipe-controller-<id>.local`, where _id_ is the a number assigned to each controller on startup, based on the order in which you start the controllers, e.g. the first controller you connect will have id `1`, the next will have id `2` and so on. You should see output:&#x20;
+The easiest way to check if everything is running is to head over to `http://robopipe-<id>.local`, where _id_ is the a number assigned to each controller on startup, based on the order in which you start the controllers, e.g. the first controller you connect will have id `1`, the next will have id `2` and so on. You should see output:&#x20;
 
 ```
 Hello from Robopipe API!
 ```
 
-The controller is also accesible via [SSH](https://en.wikipedia.org/wiki/Secure_Shell). The default hostname is set to `robopipe-controller-<id>.local`. The default user is `admin` with password `robopipe.io`. Enter this command into your terminal to connect to the controller, enter `robopipe.io` when prompted for password:
+The controller is also accesible via [SSH](https://en.wikipedia.org/wiki/Secure_Shell). The default hostname is set to `robopipe-<id>.local`. The default user is `admin` with password `robopipe.io`. Enter this command into your terminal to connect to the controller, enter `robopipe.io` when prompted for password:
 
 ```bash
-ssh admin@robopipe-controller-1.local
+ssh admin@robopipe-1.local
 ```
 
 When connecting for the first time, you will be asked to verify the authenticity of the controller's key. Enter `yes` and press enter.

docs/getting-started/hello-world.md

@@ -20,45 +20,45 @@ The complete example with all the python code is available below. The jupyter no
 
 {% file src="../.gitbook/assets/hello_world_train.ipynb" %}
 
-## Listing devices
+## Listing cameras
 
-In order to capture training data we need to specify device from which to capture from. To do this we will list all devices.
+In order to capture training data we need to specify camera and specific stream from which to capture images. To do this we will first list all cameras and streams.
 
 {% code fullWidth="false" %}
 ```python
 import requests
 
 ID = 1 # substitue with the id of your controller
-API_BASE = f"http://robopipe-controller-{ID}.local"
+API_BASE = f"http://robopipe-{ID}.local"
 
 # fetch connected devices from the robopipe controller
-def get_devices():
+def get_cameras():
     return requests.get(f"{API_BASE}/cameras").json()
 
-devices = get_devices()
+cameras = get_cameras()
 ```
 {% endcode %}
 
-Devices will contain an array of connected devices, containing their MXID along with other information. To find out more about devices API head over to the [API reference](../api/rest-api-reference/cameras.md#cameras).
+Cameras will contain an array of connected cameras, containing their MXID along with other information. To find out more about cameras API head over to the [API reference](../api/rest-api-reference/cameras.md#cameras).
 
-We will use the first device.
+We will use the first camera.
 
 ```python
-mxid = devices[0].get("mxid")
+mxid = cameras[0].get("mxid")
 ```
 
-We will also need to select a camera. To list all cameras you can use the function below.
+We will also need to select a stream. Stream is either a single sensor on the camera or a combination of multiple sensors, usually used in detecting depth. To list all streams you can use the function below.
 
 ```python
-# retrieve the list of cameras associated with the selected device (mxid)
-def get_cameras(mxid: str):
-    return requests(f"{API_BASE}/cameras/{mxid}/sensors").json()
+# retrieve the list of streams associated with the selected camera (mxid)
+def get_streams(mxid: str):
+    return requests(f"{API_BASE}/cameras/{mxid}/streams").json()
 ```
 
-In my case, I will choose the first returned camera, which is _CAM\_A_. _CAM\_A_ is usually the RGB camera on most devices.
+In my case, I will choose the first returned stream, which is _CAM\_A_. _CAM\_A_ is usually the RGB camera on most cameras.
 
 ```python
-sensor_name = list(get_cameras().keys())[0]
+stream_name = list(get_streams().keys())[0]
 ```
 
 ## Capturing images
@@ -86,7 +86,7 @@ def capture_data():
 
         if key == "s":
             image_response = requests.get(
-                f"{API_BASE}/cameras/{mxid}/sensors/{sensor_name}/still"
+                f"{API_BASE}/cameras/{mxid}/streams/{stream_name}/still"
             )
             image = image_response.content
             save_image(f"data/{i}.jpeg", image)
@@ -95,10 +95,10 @@ def capture_data():
             break
 ```
 
-To capture data we simply call `capture_data()`. This will, however, capture the data in full camera resolution, which might not be desired. In our case, the model will be trained on images of size 200x200. We can create another function, which will properly configure the camera, so that the captured images are the right size. There are numerous options which you can configure via the [config](../api/rest-api-reference/streams.md#cameras-mxid-sensors-sensor_name-config) and [control](../api/rest-api-reference/streams.md#cameras-mxid-sensors-sensor_name-control) API.
+To capture data we simply call `capture_data()`. This will, however, capture the data in full camera resolution, which might not be desired. In our case, the model will be trained on images of size 200x200. We can create another function, which will properly configure the camera, so that the captured images are the right size. There are numerous options which you can configure via the [config](../api/rest-api-reference/streams.md#cameras-mxid-sensors-sensor_name-config) and [control](../api/rest-api-reference/streams.md#cameras-mxid-sensors-sensor_name-control) APIs.
 
 ```python
-def configure_camera(width: int, height: int):
+def configure_stream(width: int, height: int):
     data = {"still_size": (width, height)}
     return requests.post(
         f"{API_BASE}/cameras/{mxid}/sensors/{sensor_name}/config", data
@@ -262,8 +262,9 @@ To deploy out model we will use our API.
 ```python
 def deploy_model(path="model.blob"):
     requests.post(
-        f"{API_BASE}/cameras/{mxid}/sensors/{sensor_name}/nn",
+        f"{API_BASE}/cameras/{mxid}/streams/{sensor_name}/nn",
         files={"model": open(path, "rb")},
+        data={"nn_config": }
     )
 ```
 
@@ -273,11 +274,11 @@ Calling this function will take a few seconds, since the camera needs to load th
 import anyio
 import websockets
 
-WS_BASE=f"ws://robopipe-controller-{ID}.local"
+WS_BASE=f"ws://robopipe-{ID}.local"
 
 async def main():
     async with websockets.connect(
-        f"{WS_BASE}/cameras/{mxid}/sensors/{sensor_name}/nn"
+        f"{WS_BASE}/cameras/{mxid}/stream/{sensor_name}/nn"
     ) as ws:
         while True:
             msg = await ws.recv()