name: maskcam-nano description: Run MaskCam face mask detection on Jetson Nano 4GB using Docker. Streams results via RTSP. Requires JetPack 4.6 and a USB camera.
MaskCam on Jetson Nano
Hardware required: Jetson Nano 4GB, JetPack 4.6, USB camera, Docker with nvidia runtime, docker-compose. MaskCam detects face mask compliance and streams annotated video over RTSP.
Execution model
Run one phase at a time. After each phase:
- Relay all command output to the user.
- If output contains
[STOP]→ stop immediately, consult the failure decision tree below. - If output ends with
[OK]→ tell the user "Phase N complete" and proceed to the next phase.
Prerequisites
| Requirement | Detail |
|---|---|
| Board | Jetson Nano 4GB |
| JetPack | 4.6 |
| Camera | USB camera connected before starting Docker |
| Docker | Installed with NVIDIA container runtime (nvidia-docker2) |
| Network | Jetson reachable on LAN for RTSP stream access |
Phase 1 — Pull Docker image
sudo docker pull maskcam/maskcam-beta
Verify:
sudo docker images | grep maskcam
# Expected: maskcam/maskcam-beta listed with a recent tag
[OK] when the image appears in docker images. [STOP] if pull fails — see failure decision tree.
Phase 2 — Get device IP address
sudo ifconfig
# Note the inet address for your active interface (e.g. eth0 or wlan0)
# Example: inet 192.168.1.42
[OK] when you have the Jetson's IP address noted. You will use it to access the RTSP stream in Phase 4.
Phase 3 — Run MaskCam
sudo docker run --runtime nvidia -it --rm \
--network host \
-v /tmp/argus_socket:/tmp/argus_socket \
maskcam/maskcam-beta
Expected: container starts and prints initialization logs, then begins processing camera frames. You should see inference output in the terminal.
[OK] when the container is running and printing frame inference results. [STOP] if the container exits immediately or errors — see failure decision tree.
Phase 4 — View RTSP stream
With MaskCam running, open the stream in VLC or any RTSP-capable player on another machine:
rtsp://<jetson-ip>:8554/maskcam
Replace <jetson-ip> with the address noted in Phase 2.
In VLC: Media -> Open Network Stream -> paste the URL above.
[OK] when the annotated video stream is visible with mask detection overlays.
Failure decision tree
| Symptom | Action |
|---|---|
docker run fails with "unknown runtime: nvidia" | NVIDIA container runtime not configured. Install nvidia-docker2: sudo apt install nvidia-docker2 then sudo systemctl restart docker. |
| Container exits immediately with "no cameras available" | USB camera not detected. Confirm camera is connected: ls /dev/video*. Reconnect camera and retry. |
| Container exits with "failed to open argus socket" | Argus socket not available. Ensure /tmp/argus_socket exists on the host: ls /tmp/argus_socket. If missing, reboot the Jetson. |
| RTSP stream URL not accessible from another machine | Check that port 8554 is not blocked: sudo ufw status. Allow if needed: sudo ufw allow 8554. Confirm you are using the correct Jetson IP from Phase 2. |
| RTSP stream connects but shows black screen | Camera may not be initializing correctly inside the container. Check container logs for camera errors. Try a different USB port. |
| Very low FPS or inference stalls | Ensure no other GPU-heavy processes are running. Check Jetson power mode: sudo nvpmodel -m 0 (max performance). |
Reference files
references/source.body.md— full Seeed Wiki tutorial with screenshots and additional context (reference only)