Skip to content

Commit e2572b9

Browse files
maxsittmaxsitt
committed
Update usage.md
Restructure Usage section. Add infos about using the RPi hotspot. Add different use cases for the startup settings. Add info box about X_LINK_ERROR.
1 parent e3fe4c7 commit e2572b9

File tree

1 file changed

+146
-42
lines changed

1 file changed

+146
-42
lines changed

‎docs/software/usage.md‎

Lines changed: 146 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -1,43 +1,47 @@
11
# Usage
22

3-
If you run into any problems, please create a
4-
[GitHub issue](https://github.com/maxsitt/insect-detect/issues){target=_blank}.
3+
## Wi-Fi vs RPi Hotspot
54

6-
??? bug "RuntimeError: X_LINK_DEVICE_ALREADY_IN_USE"
5+
To connect to the Raspberry Pi via SSH or open the web app in a browser,
6+
both your device and the RPi need to be connected to the same network.
7+
You have three main options:
78

8-
``` bash
9-
RuntimeError: Failed to connect to device, error message: X_LINK_DEVICE_ALREADY_IN_USE
10-
```
9+
1. Wi-Fi network that both your device and the RPi are connected to.
10+
2. Hotspot from your device that the RPi is connected to.
11+
3. Hotspot from the RPi that your device is connected to.
1112

12-
If you run into the error shown above, the most common cause is that a
13-
previously started script is already communicating with the OAK camera
14-
(e.g. cron job at boot). You can show all currently running processes by
15-
using the process manager [htop](https://en.wikipedia.org/wiki/Htop){target=_blank}.
13+
The RPi can usually only be used *either* as wireless client (connects to
14+
network with internet access) *or* as access point (creates own hotspot without
15+
internet access). For an **unsupported** experimental workaround, check the
16+
[RaspAP Docs](https://docs.raspap.com/features-experimental/ap-sta/){target=_blank}.
1617

17-
Start htop by running:
18+
If you don't need internet access on your RPi (e.g. during fieldwork), there
19+
are some advantages of letting the RPi create a hotspot: Any device can connect
20+
to it and open the web app, which can be useful if multiple people want to set
21+
up camera traps in the field. Also this option is more reliable than letting
22+
the RPi connect to a hotspot from your device (every device is different!).
1823

19-
``` bash
20-
htop
21-
```
22-
23-
If you see one of the Python scripts in the list of processes, you can hit
24-
++f9++ with the script selected. This will open the `SIGTERM` option and by
25-
confirming with ++enter++ the process will be stopped. Close htop by pressing
26-
++q++ and you should now be able to connect to the OAK camera again.
24+
With the default `startup` configuration, the RPi will automatically start a
25+
hotspot as fallback mechanism when no configured Wi-Fi network is available
26+
(SSID and password = hostname).
2727

2828
---
2929

3030
## Web App
3131

32-
You can use the Insect Detect
33-
[web app](https://github.com/maxsitt/insect-detect/blob/main/webapp.py){target=_blank}
34-
to stream frames from the OAK camera via HTTP to the browser-based interface
35-
(based on the [NiceGUI](https://github.com/zauberzeug/nicegui/){target=_blank} framework).
36-
It includes real-time camera control (e.g. manual focus) and customization of all
37-
[configuration](https://github.com/maxsitt/insect-detect/blob/main/configs/config_custom.yaml){target=_blank}
38-
parameters, as well as selecting the
32+
With the [web app](https://github.com/maxsitt/insect-detect/blob/main/webapp.py){target=_blank},
33+
you can view the OAK camera live stream including detected and tracked insects
34+
in the browser-based user interface
35+
(based on [NiceGUI](https://github.com/zauberzeug/nicegui/){target=_blank}).
36+
It also allows real-time camera control (e.g. setting manual focus) and customization of all
37+
[configuration parameters](https://github.com/maxsitt/insect-detect/blob/main/configs/config_custom.yaml){target=_blank},
38+
as well as selecting the
3939
[active config](https://github.com/maxsitt/insect-detect/blob/main/configs/config_selector.yaml){target=_blank}
4040
that is used by both the web app and the recording script.
41+
When using the web app in the field while setting up your camera trap, you
42+
can also save deployment metadata, such as location and background setting.
43+
The `Advanced` section includes current system info (e.g. temperature,
44+
CPU/RAM usage) and viewing of log files.
4145

4246
Run the [`webapp.py`](https://github.com/maxsitt/insect-detect/blob/main/webapp.py){target=_blank}
4347
script with the Python interpreter from the virtual environment where you
@@ -47,17 +51,13 @@ installed the required packages (e.g. `env_insdet`):
4751
env_insdet/bin/python3 insect-detect/webapp.py
4852
```
4953

50-
Use the link that is printed to the Terminal to open the web app in your browser.
51-
You can use any device that is connected to the same network as the Raspberry Pi
52-
(e.g. phone or tablet) to open the web app. If the link based on your hostname
53-
does not work, use the RPi's IP address instead.
54+
Use one of the links that is shown in the Terminal to open the web app in your
55+
browser. If the hostname-based link does not work, use the IP address instead.
56+
Always use the link with the IP address if your device is connected to the RPi
57+
hotspot, this should be `http://10.42.0.1:5000` if not using https, or
58+
`https://10.42.0.1:8443` if https is enabled.
5459

55-
If the Raspberry Pi is connected to a hotspot from your phone, you can use the
56-
[Network Analyzer](https://play.google.com/store/apps/details?id=net.techet.netanalyzerlite.an&hl=en){target=_blank}
57-
app to find its IP address.
58-
59-
Stop the web app by either using the button in your browser window
60-
or by pressing ++ctrl+c++ in the Terminal.
60+
Stop the web app with the `Stop App` button or by pressing ++ctrl+c++ in the Terminal.
6161

6262
---
6363

@@ -82,12 +82,7 @@ env_insdet/bin/python3 insect-detect/trigger_capture.py
8282

8383
Stop the script by pressing ++ctrl+c++ in the Terminal.
8484

85-
For fully autonomous monitoring in the field, enable `auto_run` in the `startup`
86-
settings of your custom config file and add `trigger_capture.py` as
87-
`primary` script. This will run the recording script automatically after each boot
88-
(triggered by the power management board).
89-
90-
**Processing pipeline:**
85+
### Processing Pipeline
9186

9287
- A custom **YOLO insect detection model** is run in real time on device (OAK)
9388
and uses a continuous stream of downscaled LQ frames as input.
@@ -111,3 +106,112 @@ settings of your custom config file and add `trigger_capture.py` as
111106
enabled in the configuration, **intelligent power management** is activated which
112107
includes battery charge level monitoring with conditional recording durations.
113108
- With the default configuration, running the recording consumes **~3.8 W** of power.
109+
110+
---
111+
112+
Depending on the specific requirements of your field deployment, different
113+
behaviours can be configured in the `startup` settings that are run after
114+
each boot:
115+
116+
### Use Case 1: Interactive
117+
118+
If you deploy the camera trap for only one recording session, e.g. while doing
119+
other field work in parallel, you might want to just run the web app automatically
120+
after boot to save deployment metadata and/or modify configuration parameters.
121+
Click the `Start Rec` button in the web app after everything is set up to start
122+
the recording script manually.
123+
124+
``` yaml hl_lines="6-8"
125+
startup:
126+
hotspot_setup:
127+
enabled: true # Create RPi Wi-Fi hotspot if it doesn't exist (uses hostname for SSID and password)
128+
network_setup:
129+
enabled: true # Create/update all configured Wi-Fi networks in NetworkManager (including hotspot)
130+
auto_run:
131+
enabled: true # Automatically run configured Python script(s) after boot
132+
primary: webapp.py # Primary Python script in "insect-detect" directory that is run first
133+
fallback: # Fallback Python script in "insect-detect" directory (can be empty)
134+
delay: 180 # Wait time (seconds) before stopping primary script and running fallback script
135+
```
136+
137+
### Use Case 2: Autonomous
138+
139+
For long-term field deployment, you want to run the recording script
140+
`trigger_capture.py` automatically after each boot. Please make sure to
141+
modify and save all relevant configuration parameters either beforehand or
142+
when setting up the camera trap.
143+
144+
``` yaml hl_lines="6-8"
145+
startup:
146+
hotspot_setup:
147+
enabled: true # Create RPi Wi-Fi hotspot if it doesn't exist (uses hostname for SSID and password)
148+
network_setup:
149+
enabled: true # Create/update all configured Wi-Fi networks in NetworkManager (including hotspot)
150+
auto_run:
151+
enabled: true # Automatically run configured Python script(s) after boot
152+
primary: trigger_capture.py # Primary Python script in "insect-detect" directory that is run first
153+
fallback: # Fallback Python script in "insect-detect" directory (can be empty)
154+
delay: 180 # Wait time (seconds) before stopping primary script and running fallback script
155+
```
156+
157+
### Use Case 3: Hybrid
158+
159+
There might be scenarios where you want to optionally connect to the web app
160+
after a scheduled wake-up time, e.g. to modify settings or check log files.
161+
For this use case, you can set `webapp.py` as `primary` auto-run script and
162+
`trigger_capture.py` as `fallback` script. If no user interaction (opening the
163+
web app in your browser) is detected for the configured `delay` time, the
164+
web app will be terminated and the recording script will be started automatically.
165+
166+
``` yaml hl_lines="6-10"
167+
startup:
168+
hotspot_setup:
169+
enabled: true # Create RPi Wi-Fi hotspot if it doesn't exist (uses hostname for SSID and password)
170+
network_setup:
171+
enabled: true # Create/update all configured Wi-Fi networks in NetworkManager (including hotspot)
172+
auto_run:
173+
enabled: true # Automatically run configured Python script(s) after boot
174+
primary: webapp.py # Primary Python script in "insect-detect" directory that is run first
175+
fallback: trigger_capture.py # Fallback Python script in "insect-detect" directory (can be empty)
176+
delay: 180 # Wait time (seconds) before stopping primary script and running fallback script
177+
```
178+
179+
---
180+
181+
## Troubleshooting
182+
183+
If you run into any problems while using the
184+
[`insect-detect`](https://github.com/maxsitt/insect-detect){target=_blank}
185+
software, please create an
186+
[issue](https://github.com/maxsitt/insect-detect/issues){target=_blank}.
187+
188+
??? bug "RuntimeError: X_LINK_DEVICE_ALREADY_IN_USE"
189+
190+
``` bash
191+
RuntimeError: Failed to connect to device, error message: X_LINK_DEVICE_ALREADY_IN_USE
192+
```
193+
194+
If you run into the error shown above, the most common cause is that a
195+
previously started script is already communicating with the OAK camera.
196+
Show all running processes by starting the process manager
197+
[htop](https://en.wikipedia.org/wiki/Htop){target=_blank}:
198+
199+
``` bash
200+
htop
201+
```
202+
203+
If you see one of the Python scripts in the list of processes, you can hit
204+
++f9++ with the script selected. This will open the `SIGTERM` option and by
205+
confirming with ++enter++ the process will be stopped. Close htop by pressing
206+
++q++ and you should now be able to connect to the OAK camera again.
207+
208+
??? bug "Couldn't read data from stream: 'frame' (X_LINK_ERROR)"
209+
210+
``` bash
211+
RuntimeError: Communication exception - possible device error/misconfiguration. Original message 'Couldnt read data from stream: 'frame' (X_LINK_ERROR)'
212+
```
213+
214+
If you run into the error shown above, the most common cause is a loose
215+
USB cable between OAK camera and Raspberry Pi. Other reasons can be a
216+
damaged cable or Micro-USB adapter. Please make sure to exclude these
217+
reasons, e.g. by testing a different cable and/or adapter.

0 commit comments

Comments
 (0)