From 9c8cb1c6298fee17440c855327cdb29eb17b64be Mon Sep 17 00:00:00 2001 From: rain-Brian Date: Thu, 14 May 2026 13:08:52 -0700 Subject: [PATCH 1/3] =?UTF-8?q?docs:=20ecosystem=20alignment=20=E2=80=94?= =?UTF-8?q?=20MkDocs=20site,=20citation,=20issue=20templates,=20branding?= =?UTF-8?q?=20fixes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add MkDocs docs site (mkdocs.yml, docs-requirements.txt, deploy-docs.yml) - Add docs/ with 6 pages: index, hardware, setup, cite, tags, build_mkdocs - Add citation.cff (16 authors, software citation) - Add .github/ISSUE_TEMPLATE/ (bug-report, feature-request, question) - Fix SUPPORT.md: replace TODO placeholders with real support guidance - Fix README.md: hero image alt text, PyTorch-Wildlife branding, ecosystem table - Add site/, archive/, *.code-workspace to .gitignore --- .github/ISSUE_TEMPLATE/bug-report.yml | 64 +++++++++++++ .github/ISSUE_TEMPLATE/feature-request.yml | 48 ++++++++++ .github/ISSUE_TEMPLATE/question.yml | 32 +++++++ .github/workflows/deploy-docs.yml | 28 ++++++ .gitignore | 9 ++ README.md | 18 +++- SUPPORT.md | 38 +++----- citation.cff | 52 +++++++++++ docs-requirements.txt | 6 ++ docs/build_mkdocs.md | 65 +++++++++++++ docs/cite.md | 35 +++++++ docs/hardware.md | 45 +++++++++ docs/index.md | 41 ++++++++ docs/setup.md | 73 +++++++++++++++ docs/tags.md | 6 ++ mkdocs.yml | 104 +++++++++++++++++++++ 16 files changed, 637 insertions(+), 27 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/bug-report.yml create mode 100644 .github/ISSUE_TEMPLATE/feature-request.yml create mode 100644 .github/ISSUE_TEMPLATE/question.yml create mode 100644 .github/workflows/deploy-docs.yml create mode 100644 citation.cff create mode 100644 docs-requirements.txt create mode 100644 docs/build_mkdocs.md create mode 100644 docs/cite.md create mode 100644 docs/hardware.md create mode 100644 docs/index.md create mode 100644 docs/setup.md create mode 100644 docs/tags.md create mode 100644 mkdocs.yml diff --git a/.github/ISSUE_TEMPLATE/bug-report.yml b/.github/ISSUE_TEMPLATE/bug-report.yml new file mode 100644 index 0000000..f613797 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug-report.yml @@ -0,0 +1,64 @@ +name: Bug Report +description: Problems with SPARROW +labels: [bug] +body: + - type: markdown + attributes: + value: | + Thank you for submitting a Bug Report! + + - type: checkboxes + attributes: + label: Search before asking + description: > + Please search the [issues](https://github.com/microsoft/SPARROW/issues) to see if a similar bug report already exists. + options: + - label: > + I have searched the SPARROW [issues](https://github.com/microsoft/SPARROW/issues) and found no similar bug report. + required: true + + - type: textarea + attributes: + label: Bug + description: Provide console output with error messages and/or screenshots of the bug. + placeholder: | + πŸ’‘ ProTip! Include as much information as possible (error messages, screenshots, logs, tracebacks, etc.) to receive the most helpful response. + validations: + required: true + + - type: textarea + attributes: + label: Environment + description: Please specify the software and hardware you used to produce the bug. + placeholder: | + - SPARROW version / commit hash: + - Hardware: Jetson Orin Nano / other + - OS: Ubuntu 22.04 + - Docker version: + validations: + required: false + + - type: textarea + attributes: + label: Minimal Reproducible Example + description: > + This is referred to by community members as creating a [minimal reproducible example](https://stackoverflow.com/help/minimal-reproducible-example). + placeholder: | + ``` + # Steps or commands to reproduce the issue + ``` + validations: + required: false + + - type: textarea + attributes: + label: Additional + description: Anything else you would like to share? + + - type: checkboxes + attributes: + label: Are you willing to submit a PR? + description: > + (Optional) We encourage you to submit a [Pull Request](https://github.com/microsoft/SPARROW/pulls) (PR) to help contribute to SPARROW for everyone, especially if you have a good understanding of how to implement a fix or feature. + options: + - label: Yes I'd like to help by submitting a PR! diff --git a/.github/ISSUE_TEMPLATE/feature-request.yml b/.github/ISSUE_TEMPLATE/feature-request.yml new file mode 100644 index 0000000..9b9bbb2 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature-request.yml @@ -0,0 +1,48 @@ +name: Feature Request +description: Suggest an enhancement for SPARROW +labels: [enhancement] +body: + - type: markdown + attributes: + value: | + Thank you for submitting a SPARROW Feature Request! + + - type: checkboxes + attributes: + label: Search before asking + description: > + Please search the [issues](https://github.com/microsoft/SPARROW/issues) to see if a similar feature request already exists. + options: + - label: > + I have searched the SPARROW [issues](https://github.com/microsoft/SPARROW/issues) and found no similar feature request. + required: true + + - type: textarea + attributes: + label: Description + description: A short description of your feature. + placeholder: | + What new feature would you like to see in SPARROW? + validations: + required: true + + - type: textarea + attributes: + label: Use case + description: | + Describe the use case of your feature request. It will help us understand and prioritize the feature request. + placeholder: | + How would this feature be used, and who would use it? + + - type: textarea + attributes: + label: Additional + description: Anything else you would like to share? + + - type: checkboxes + attributes: + label: Are you willing to submit a PR? + description: > + (Optional) We encourage you to submit a [Pull Request](https://github.com/microsoft/SPARROW/pulls) (PR) to help contribute to SPARROW for everyone, especially if you have a good understanding of how to implement a fix or feature. + options: + - label: Yes I'd like to help by submitting a PR! diff --git a/.github/ISSUE_TEMPLATE/question.yml b/.github/ISSUE_TEMPLATE/question.yml new file mode 100644 index 0000000..db8b86e --- /dev/null +++ b/.github/ISSUE_TEMPLATE/question.yml @@ -0,0 +1,32 @@ +name: Question +description: Ask a SPARROW question +labels: [question] +body: + - type: markdown + attributes: + value: | + Thank you for asking a general question! + + - type: checkboxes + attributes: + label: Search before asking + description: > + Please search the [issues](https://github.com/microsoft/SPARROW/issues) to see if a similar question already exists. + options: + - label: > + I have searched the SPARROW [issues](https://github.com/microsoft/SPARROW/issues) and found no similar question. + required: true + + - type: textarea + attributes: + label: Question + description: What is your question? + placeholder: | + πŸ’‘ ProTip! Include as much information as possible to receive the most helpful response. + validations: + required: true + + - type: textarea + attributes: + label: Additional + description: Anything else you would like to share? diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml new file mode 100644 index 0000000..9a838ee --- /dev/null +++ b/.github/workflows/deploy-docs.yml @@ -0,0 +1,28 @@ +name: Deploy MkDocs site + +on: + push: + branches: + - main + paths: + - 'docs/**' + - 'mkdocs.yml' + - 'docs-requirements.txt' + +jobs: + deploy: + runs-on: ubuntu-latest + permissions: + contents: write + steps: + - uses: actions/checkout@v4 + + - uses: actions/setup-python@v5 + with: + python-version: '3.10' + + - name: Install MkDocs dependencies + run: pip install -r docs-requirements.txt + + - name: Deploy to GitHub Pages + run: mkdocs gh-deploy --force diff --git a/.gitignore b/.gitignore index d838ed7..3eee500 100644 --- a/.gitignore +++ b/.gitignore @@ -3,6 +3,15 @@ ## ## Get latest from https://github.com/github/gitignore/blob/main/VisualStudio.gitignore +# Docs build output (served from gh-pages branch) +site/ + +# Local archive directories +archive/ + +# Workspace files +*.code-workspace + # User-specific files *.rsuser *.suo diff --git a/README.md b/README.md index d4bc765..e093193 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -![image](https://zenodo.org/records/17547596/files/SPARROW-banner.png) +![SPARROW β€” Solar-Powered Acoustic and Remote Recording Observation Watch, edge AI for wildlife monitoring](https://zenodo.org/records/17547596/files/SPARROW-banner.png)

@@ -28,6 +28,20 @@ The resulting critical information is then transmitted via low-Earth orbit satel +--- + +## Part of the Microsoft Biodiversity Ecosystem + +| Repository | Description | +|---|---| +| [microsoft/Biodiversity](https://github.com/microsoft/Biodiversity) | Umbrella hub β€” PyTorch-Wildlife, MegaDetector, ecosystem overview | +| [microsoft/MegaDetector](https://github.com/microsoft/MegaDetector) | Animal/human/vehicle detector for camera traps | +| [microsoft/Pytorch-Wildlife](https://github.com/microsoft/Pytorch-Wildlife) | Unified AI framework: detection + species classification | +| [microsoft/SPARROW](https://github.com/microsoft/SPARROW) | This repo β€” solar-powered edge AI for wildlife monitoring | +| [microsoft/SPARROW-Studio](https://github.com/microsoft/SPARROW-Studio) | Dashboard for SPARROW data visualization | + +--- + # ✨ Key Features 1. **πŸ”‹ Autonomous operation** @@ -37,7 +51,7 @@ To learn more about project SPARROW, please checkout our SPARROW paper here πŸ‘‰ Camera traps, acoustic monitoring, and environmental sensors - SPARROW integrates multi-modal sensing to capture images, sounds, and enviromental metrics for comprehensive biodiversity monitoring. 3. **🧠 On-device AI** - Runs optimized PyTorch Wildlife models on power efficient edge GPUs (e.g., Jetson Orin Nano) for real-time image and acoustic detection, species classification, and event recognition. + Runs optimized PyTorch-Wildlife models on power efficient edge GPUs (e.g., Jetson Orin Nano) for real-time image and acoustic detection, species classification, and event recognition. 4. **🌐 Global connectivity** Even in the most remote ecosystems, SPARROW maintains a link to the cloud or on-premise infrastructure through low-Earth-orbit satellites, ensuring that vital conservation data reaches researchers in near real time. diff --git a/SUPPORT.md b/SUPPORT.md index 291d4d4..4e2effe 100644 --- a/SUPPORT.md +++ b/SUPPORT.md @@ -1,25 +1,13 @@ -# TODO: The maintainer of this repo has not yet edited this file - -**REPO OWNER**: Do you want Customer Service & Support (CSS) support for this product/project? - -- **No CSS support:** Fill out this template with information about how to file issues and get help. -- **Yes CSS support:** Fill out an intake form at [aka.ms/onboardsupport](https://aka.ms/onboardsupport). CSS will work with/help you to determine next steps. -- **Not sure?** Fill out an intake as though the answer were "Yes". CSS will help you decide. - -*Then remove this first heading from this SUPPORT.MD file before publishing your repo.* - -# Support - -## How to file issues and get help - -This project uses GitHub Issues to track bugs and feature requests. Please search the existing -issues before filing new issues to avoid duplicates. For new issues, file your bug or -feature request as a new Issue. - -For help and questions about using this project, please **REPO MAINTAINER: INSERT INSTRUCTIONS HERE -FOR HOW TO ENGAGE REPO OWNERS OR COMMUNITY FOR HELP. COULD BE A STACK OVERFLOW TAG OR OTHER -CHANNEL. WHERE WILL YOU HELP PEOPLE?**. - -## Microsoft Support Policy - -Support for this **PROJECT or PRODUCT** is limited to the resources listed above. +# Support + +## How to file issues and get help + +This project uses GitHub Issues to track bugs and feature requests. Please search the [existing issues](https://github.com/microsoft/SPARROW/issues) before filing new ones to avoid duplicates. + +- **Bug reports:** Use the [Bug Report](https://github.com/microsoft/SPARROW/issues/new?template=bug-report.yml) template +- **Feature requests:** Use the [Feature Request](https://github.com/microsoft/SPARROW/issues/new?template=feature-request.yml) template +- **Questions:** Use the [Question](https://github.com/microsoft/SPARROW/issues/new?template=question.yml) template or start a [GitHub Discussion](https://github.com/microsoft/SPARROW/discussions) + +## Microsoft Support Policy + +Support for this project is limited to the resources listed above. diff --git a/citation.cff b/citation.cff new file mode 100644 index 0000000..c1b0dba --- /dev/null +++ b/citation.cff @@ -0,0 +1,52 @@ +cff-version: 1.2.0 +message: "If you use SPARROW in your research, please cite it using this metadata." +type: software +title: "SPARROW: Solar-Powered Acoustic and Remote Recording Observation Watch" +version: "1.0.0" +date-released: "2026-05-14" +license: MIT +repository-code: "https://github.com/microsoft/SPARROW" +url: "https://microsoft.github.io/SPARROW/" +keywords: + - edge-ai + - wildlife-monitoring + - camera-traps + - acoustic-monitoring + - conservation + - jetson + - solar-powered + - PyTorch-Wildlife + - ai-for-good +authors: + - family-names: Lavista Ferres + given-names: "Juan M." + - family-names: Chalmers + given-names: Carl + - family-names: Demuro Segundo + given-names: Bruno + - family-names: Miao + given-names: Zhongqi + - family-names: Hernandez Celis + given-names: Andres + - family-names: Chacon Silva + given-names: Isai Daniel + - family-names: Kim + given-names: Allen + - family-names: Marotti + given-names: Luana + - family-names: Michaels + given-names: Amy + - family-names: Ruiz Lopez + given-names: Daniela + - family-names: Dodhia + given-names: Rahul + - family-names: Becker-Reshef + given-names: Inbal + - family-names: "Arbelaez Escalante" + given-names: "Pablo AndrΓ©s" + - family-names: Alves Torres + given-names: Federico + - family-names: Machado + given-names: Meygha + - family-names: Cintron Roman + given-names: Anthony diff --git a/docs-requirements.txt b/docs-requirements.txt new file mode 100644 index 0000000..133ec0a --- /dev/null +++ b/docs-requirements.txt @@ -0,0 +1,6 @@ +mkdocs>=1.6 +mkdocs-material>=9.7 +mkdocs-material-extensions>=1.3 +pymdown-extensions>=10.0 +mkdocstrings>=0.27 +mkdocstrings-python>=1.0 diff --git a/docs/build_mkdocs.md b/docs/build_mkdocs.md new file mode 100644 index 0000000..9313992 --- /dev/null +++ b/docs/build_mkdocs.md @@ -0,0 +1,65 @@ +--- +description: "How to build and deploy the SPARROW MkDocs documentation site locally and to GitHub Pages." +tags: + - SPARROW + - documentation + - MkDocs + - developer-guide +--- + +# Developer Guide β€” Building the Docs + +This page explains how to build and preview the SPARROW documentation site locally. + +## Prerequisites + +Install the documentation dependencies (separate from the ML/hardware requirements): + +```bash +pip install -r docs-requirements.txt +``` + +## Local Preview + +Start the live-reload dev server: + +```bash +mkdocs serve +``` + +Open [http://127.0.0.1:8000](http://127.0.0.1:8000) in your browser. The site rebuilds automatically when you save any file under `docs/` or `mkdocs.yml`. + +## Build (Static) + +To build the static site without serving it: + +```bash +mkdocs build +``` + +Output goes to `site/` (gitignored β€” never commit this directory). + +## Deploy to GitHub Pages + +Deployment happens automatically via GitHub Actions on every push to `main` that touches `docs/**`, `mkdocs.yml`, or `docs-requirements.txt`. The workflow in `.github/workflows/deploy-docs.yml` builds the site and force-pushes to the `gh-pages` branch. + +To deploy manually: + +```bash +mkdocs gh-deploy --force +``` + +## Adding a New Page + +1. Create `docs/.md` with the required SEO front matter: + +```yaml +--- +description: "One-sentence description for search engines and the site description meta tag." +tags: + - SPARROW + - relevant-tag +--- +``` + +2. Add the page to the `nav:` section of `mkdocs.yml`. diff --git a/docs/cite.md b/docs/cite.md new file mode 100644 index 0000000..409504f --- /dev/null +++ b/docs/cite.md @@ -0,0 +1,35 @@ +--- +description: "How to cite SPARROW β€” software citation and BibTeX entry for the SPARROW edge AI wildlife monitoring system by Microsoft AI for Good Lab." +tags: + - SPARROW + - citation + - research +--- + +# Cite Us + +If you use SPARROW in your research or deployments, please cite the software using the metadata below. + +## Software Citation + +```bibtex +@software{sparrow2026, + author = {Lavista Ferres, Juan M. and Chalmers, Carl and Demuro Segundo, Bruno and + Miao, Zhongqi and Hernandez Celis, Andres and Chacon Silva, Isai Daniel and + Kim, Allen and Marotti, Luana and Michaels, Amy and Ruiz Lopez, Daniela and + Dodhia, Rahul and Becker-Reshef, Inbal and Arbelaez Escalante, Pablo AndrΓ©s and + Alves Torres, Federico and Machado, Meygha and Cintron Roman, Anthony}, + title = {{SPARROW}: Solar-Powered Acoustic and Remote Recording Observation Watch}, + year = {2026}, + publisher = {Microsoft AI for Good Lab}, + url = {https://github.com/microsoft/SPARROW} +} +``` + +## Technical Paper + +We have published a technical paper on SPARROW. A preprint is available at [aka.ms/sparrowpaper](https://aka.ms/sparrowpaper). + +## CFF Citation + +A machine-readable `citation.cff` file is included in the [SPARROW repository](https://github.com/microsoft/SPARROW/blob/main/citation.cff) and is recognized automatically by GitHub's "Cite this repository" feature. diff --git a/docs/hardware.md b/docs/hardware.md new file mode 100644 index 0000000..a4a11d6 --- /dev/null +++ b/docs/hardware.md @@ -0,0 +1,45 @@ +--- +description: "SPARROW hardware assembly guide β€” bill of materials, wiring, and Jetson Orin Nano setup for remote wildlife monitoring field deployment." +tags: + - SPARROW + - hardware + - jetson + - bill-of-materials + - assembly +--- + +# Hardware Setup + +This page covers the hardware required to build and deploy a SPARROW unit. For detailed step-by-step assembly instructions, wiring diagrams, and the full bill of materials, see the [SPARROW Assembly and Setup Guide](https://github.com/microsoft/SPARROW/blob/main/documentation/SPARROW_Assembly_and_Setup_Guide.pdf) (PDF). + +## Bill of Materials + +The [SPARROW BOM PDF](https://github.com/microsoft/SPARROW/blob/main/documentation/SPARROW_Bill_of_Materials_-_BOM.pdf) contains the complete component list with part numbers, vendors, and approximate costs. Key components include: + +- **Compute:** NVIDIA Jetson Orin Nano (edge GPU for on-device AI inference) +- **Power:** Solar panel + LiPo battery with intelligent charge management +- **Sensing:** Camera trap module, acoustic sensor, environmental sensors (temperature, humidity) +- **Connectivity:** Starlink satellite dish and modem for remote uplink +- **Enclosure:** Weatherproof housing rated for field conditions + +## Assembly + +Refer to the [Assembly and Setup Guide PDF](https://github.com/microsoft/SPARROW/blob/main/documentation/SPARROW_Assembly_and_Setup_Guide.pdf) for full assembly instructions, including: + +1. Enclosure preparation and component mounting +2. Wiring: power distribution, sensor connections, GPIO mapping +3. Jetson Orin Nano initial boot and configuration +4. Starlink dish alignment and network setup +5. RTC seeding and system clock configuration + +## One-Click Jetson Setup + +Once hardware is assembled, the `setup script/` directory contains an automated setup script that: + +1. Flashes the Jetson with the required OS image +2. Installs system dependencies +3. Configures the Wi-Fi hotspot +4. Seeds the RTC +5. Builds and launches Docker containers + +See the [Software Setup](setup.md) page for full details. diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..2698146 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,41 @@ +--- +description: "SPARROW β€” Solar-Powered Acoustic and Remote Recording Observation Watch. AI-powered edge computing for wildlife monitoring by Microsoft AI for Good Lab." +tags: + - SPARROW + - edge-ai + - wildlife-monitoring + - conservation + - camera-traps + - jetson +--- + +# SPARROW + +**SPARROW** (Solar-Powered Acoustic and Remote Recording Observation Watch) is Microsoft AI for Good Lab's open-source edge AI solution for wildlife monitoring in the most remote regions of the world. + +Solar-powered and equipped with multi-modal sensors, SPARROW collects biodiversity data from camera traps, acoustic monitors, and environmental detectors. It processes that data on-device using [PyTorch-Wildlife](https://github.com/microsoft/Pytorch-Wildlife) models running on power-efficient edge GPUs (Jetson Orin Nano), then transmits results via low-Earth-orbit satellites for near-real-time insights β€” no matter how remote the deployment site. + +## Key capabilities + +- **On-device AI** β€” runs PyTorch-Wildlife detection and classification models locally, no cloud required for inference +- **Multi-modal sensing** β€” camera traps, acoustic monitoring, environmental sensors +- **Solar-powered** β€” autonomous operation with intelligent power management and battery health monitoring +- **Global connectivity** β€” Starlink satellite uplink for remote data transmission +- **Resilient** β€” records data offline, syncs automatically when connectivity is restored + +## Quick links + +- [Hardware Setup](hardware.md) β€” bill of materials, assembly, and Jetson Orin Nano setup +- [Software Setup](setup.md) β€” Docker installation, environment configuration, and one-click deploy +- [Cite Us](cite.md) β€” how to cite SPARROW in publications +- [GitHub Repository](https://github.com/microsoft/SPARROW) + +## Part of the Microsoft Biodiversity Ecosystem + +| Repository | Description | +|---|---| +| [microsoft/Biodiversity](https://github.com/microsoft/Biodiversity) | Umbrella hub β€” PyTorch-Wildlife, MegaDetector, ecosystem overview | +| [microsoft/MegaDetector](https://github.com/microsoft/MegaDetector) | Animal/human/vehicle detector for camera traps | +| [microsoft/Pytorch-Wildlife](https://github.com/microsoft/Pytorch-Wildlife) | Unified AI framework: detection + species classification | +| [microsoft/SPARROW](https://github.com/microsoft/SPARROW) | This repo β€” solar-powered edge AI for wildlife monitoring | +| [microsoft/SPARROW-Studio](https://github.com/microsoft/SPARROW-Studio) | Dashboard for SPARROW data visualization | diff --git a/docs/setup.md b/docs/setup.md new file mode 100644 index 0000000..0f1a9f2 --- /dev/null +++ b/docs/setup.md @@ -0,0 +1,73 @@ +--- +description: "SPARROW software setup β€” Docker installation, environment configuration, and one-click Jetson deploy script for edge wildlife monitoring." +tags: + - SPARROW + - software-setup + - docker + - jetson + - installation +--- + +# Software Setup + +SPARROW runs entirely in Docker containers. This page covers how to configure and launch the SPARROW software stack on a Jetson Orin Nano. + +## Prerequisites + +- Jetson Orin Nano with JetPack 6.x installed +- Docker and Docker Compose installed (included in the one-click setup script) +- Starlink modem connected and configured +- Hardware assembled per the [Hardware Setup](hardware.md) guide + +## Environment Configuration + +Copy the environment templates and fill in your deployment-specific values: + +```bash +cp sparrow.env .env.sparrow +cp starlink.env .env.starlink +``` + +Edit `.env.sparrow` and `.env.starlink` with your site-specific configuration (coordinates, upload endpoints, API keys, etc.). + +!!! warning + Never commit `.env` files containing real credentials. The `.gitignore` already excludes `.env` files. + +## Docker Compose Launch + +Start the full SPARROW stack: + +```bash +docker compose up -d +``` + +This launches two services defined in `docker-compose.yml`: + +- **sparrow** β€” camera trap capture, on-device AI inference (PyTorch-Wildlife), data management, power control, telemetry +- **starlink** β€” Starlink satellite connectivity monitoring and data uplink + +View logs: + +```bash +docker compose logs -f +``` + +## One-Click Jetson Setup + +For a fresh Jetson deployment, use the automated setup script in `setup script/`: + +```bash +cd "setup script" +./setup.sh +``` + +This script handles all steps from OS configuration through Docker launch. See the [Assembly and Setup Guide PDF](https://github.com/microsoft/SPARROW/blob/main/documentation/SPARROW_Assembly_and_Setup_Guide.pdf) for full details on each step. + +## Dependencies + +Python dependencies are organized per service: + +- `sparrow/requirements.txt` β€” AI/ML stack (torch, torchvision, librosa, etc.) +- `starlink/requirements.txt` β€” Starlink gRPC interface + +These are installed inside their respective Docker images β€” no manual `pip install` needed on the host. diff --git a/docs/tags.md b/docs/tags.md new file mode 100644 index 0000000..663e933 --- /dev/null +++ b/docs/tags.md @@ -0,0 +1,6 @@ +--- +description: "Tag index for the SPARROW documentation site." +tags: [] +--- + + diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..b17548e --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,104 @@ +site_name: SPARROW +site_url: https://microsoft.github.io/SPARROW/ +site_description: "SPARROW β€” Solar-Powered Acoustic and Remote Recording Observation Watch. AI-powered edge computing for wildlife monitoring by Microsoft AI for Good Lab." +docs_dir: docs +site_dir: site +repo_url: https://github.com/microsoft/SPARROW +repo_name: microsoft/SPARROW +copyright: Copyright (c) 2023 Microsoft Corporation + +theme: + name: material + favicon: https://zenodo.org/records/15376499/files/cat.png + logo: https://zenodo.org/records/15376499/files/cat.png + icon: + menu: material/menu + alternate: material/translate + search: material/magnify + share: material/share-variant + close: material/close + top: material/arrow-up + edit: material/pencil + view: material/eye + repo: fontawesome/brands/git-alt + admonition: + note: material/note + abstract: material/lightbulb + info: material/information + tip: material/lightbulb-on + success: material/check-circle + question: material/help-circle + warning: material/alert + failure: material/alert-circle + danger: material/alert-octagon + bug: material/bug + example: material/format-list-bulleted + quote: material/format-quote-open + tag: + default: material/tag + info: material/information + warning: material/alert + danger: material/alert-octagon + previous: material/arrow-left + next: material/arrow-right + palette: + - media: "(prefers-color-scheme: light)" + scheme: default + primary: green + accent: deep orange + toggle: + icon: material/paw-off + name: Switch to dark mode + + - media: "(prefers-color-scheme: dark)" + scheme: slate + primary: teal + accent: deep orange + toggle: + icon: material/paw + name: Switch to light mode + features: + - navigation.tracking + - navigation.tabs + - navigation.sections + - navigation.path + - toc.follow + - navigation.top + - search.suggest + - search.share + - navigation.footer + +nav: + - SPARROW: + - Overview: index.md + - Hardware Setup: hardware.md + - Software Setup: setup.md + - Tags: tags.md + - Cite Us: cite.md + - Developer Guide: build_mkdocs.md + +markdown_extensions: + - admonition + - pymdownx.details + - pymdownx.superfences + - md_in_html + - attr_list + - sane_lists + - pymdownx.tabbed: + alternate_style: true + - toc: + permalink: true + - pymdownx.emoji: + emoji_index: !!python/name:material.extensions.emoji.twemoji + emoji_generator: !!python/name:material.extensions.emoji.to_svg + - pymdownx.snippets: + check_paths: true + - pymdownx.highlight: + anchor_linenums: true + line_spans: __span + pygments_lang_class: true + +plugins: + - search + - meta + - tags From fb9042dc5ce641f635567683134816ac4b12cf94 Mon Sep 17 00:00:00 2001 From: rain-Brian Date: Thu, 14 May 2026 13:20:24 -0700 Subject: [PATCH 2/3] docs: enrich index, hardware, and setup pages with substantive content - index.md: add architecture diagram, capabilities table, use-case summary - hardware.md: full BOM component tables by category (Jetson, solar, Starlink, AudioMoth, camera) - setup.md: setup script step table, folder layout, AI models (Triton/ONNX), Docker services detail, dashboard links --- docs/hardware.md | 112 +++++++++++++++++++++++++++-------- docs/index.md | 87 ++++++++++++++++++++++----- docs/setup.md | 150 +++++++++++++++++++++++++++++++++++++---------- 3 files changed, 279 insertions(+), 70 deletions(-) diff --git a/docs/hardware.md b/docs/hardware.md index a4a11d6..65bf0c7 100644 --- a/docs/hardware.md +++ b/docs/hardware.md @@ -1,45 +1,107 @@ --- -description: "SPARROW hardware assembly guide β€” bill of materials, wiring, and Jetson Orin Nano setup for remote wildlife monitoring field deployment." +description: "SPARROW hardware assembly guide β€” bill of materials for NVIDIA Jetson Orin Nano, Starlink satellite, solar power, AudioMoth acoustic sensor, and Reolink camera trap edge AI system." tags: - SPARROW - hardware - - jetson + - jetson-orin-nano - bill-of-materials + - starlink + - solar-powered + - audiomoth + - camera-trap - assembly --- # Hardware Setup -This page covers the hardware required to build and deploy a SPARROW unit. For detailed step-by-step assembly instructions, wiring diagrams, and the full bill of materials, see the [SPARROW Assembly and Setup Guide](https://github.com/microsoft/SPARROW/blob/main/documentation/SPARROW_Assembly_and_Setup_Guide.pdf) (PDF). +SPARROW is a solar-powered edge AI computing unit built around the **NVIDIA Jetson Orin Nano**. It collects data from camera traps, acoustic sensors, and environmental monitors, processes it on-device using PyTorch-Wildlife models via the NVIDIA Triton Inference Server, and transmits results via Starlink satellite. -## Bill of Materials +This page summarizes the hardware components needed to build a SPARROW unit. For full step-by-step assembly instructions, wiring diagrams, and part numbers, download the official guides: -The [SPARROW BOM PDF](https://github.com/microsoft/SPARROW/blob/main/documentation/SPARROW_Bill_of_Materials_-_BOM.pdf) contains the complete component list with part numbers, vendors, and approximate costs. Key components include: +- πŸ“‹ **[SPARROW Bill of Materials](https://aka.ms/sparrowbom)** β€” full component list with recommended vendors and quantities +- πŸ—οΈ **[SPARROW Assembly and Setup Guide](https://aka.ms/sparrowassembly)** β€” step-by-step wiring and assembly instructions -- **Compute:** NVIDIA Jetson Orin Nano (edge GPU for on-device AI inference) -- **Power:** Solar panel + LiPo battery with intelligent charge management -- **Sensing:** Camera trap module, acoustic sensor, environmental sensors (temperature, humidity) -- **Connectivity:** Starlink satellite dish and modem for remote uplink -- **Enclosure:** Weatherproof housing rated for field conditions +--- + +## Hardware Components by Category + +### Brain β€” Compute + +| Component | Role | +|---|---| +| NVIDIA Jetson Orin Nano Super Developer Kit | Primary edge compute unit β€” runs AI models and all SPARROW services | +| 2TB PCIe Gen 4 NVMe SSD | Local image/audio storage for offline operation | +| DS3231M RTC (IΒ²C) | Real-time clock for accurate timestamps in remote deployments | +| BME688 Environmental Sensor (IΒ²C) | Temperature, humidity, pressure, and gas sensing | +| SHTC3 Temperature/Humidity Sensor (IΒ²C) | Redundant environmental measurement | +| IΒ²C Relay Board | Controlled power switching for peripheral components | +| Pi 3 Click Shield + mikroBUS Shuttles | Adapter to connect Mikroe Click boards to Jetson GPIO | + +!!! note "IΒ²C Board Compatibility" + The assembly guide is developed around **Mikroe MikroBUS** click boards. Generic IΒ²C boards may work but require custom address mapping and are recommended only for advanced users. + +--- + +### Power β€” Solar + Battery + +| Component | Role | +|---|---| +| MPPT Solar Charge Controller (24V/15A+) | Maximizes solar panel harvest; recommended: Victron SmartSolar MPPT 100/20 | +| 100W Monocrystalline Solar Panels (Γ—2) | Primary power source β€” wired in 24V series configuration | +| 24V 50–100Ah LiFePO4 Battery | Energy storage for overnight and cloudy-day operation | +| Solar Panel Mount Brackets (45") | Tiltable mounting for optimal sun angle | +| 10AWG Weatherproof Cabling | Solar panel β†’ charge controller β†’ battery wiring | + +--- + +### Network β€” Satellite Connectivity -## Assembly +| Component | Role | +|---|---| +| Starlink Mini Kit | Low-Earth-orbit satellite internet for remote data uplink | +| Starlink RJ45 Weatherproof Ethernet Adapter | Weatherproof wired connection from Jetson to Starlink dish | +| Cat 6 Outdoor Ethernet Cable | Direct-burial UV-rated cable between Jetson and Starlink | +| Dual-band WiFi Antenna (MHF4/IPEX to RP-SMA) | Internal WiFi for camera trap connectivity | +| 10dBi Long-Range Outdoor WiFi Antenna (optional) | Extended WiFi range for large camera trap deployments (up to 150 cameras) | -Refer to the [Assembly and Setup Guide PDF](https://github.com/microsoft/SPARROW/blob/main/documentation/SPARROW_Assembly_and_Setup_Guide.pdf) for full assembly instructions, including: +--- + +### Audio β€” Acoustic Monitoring + +| Component | Role | +|---|---| +| AudioMoth Dev Board + Case | Open-source acoustic sensor for bioacoustic monitoring (bird calls, bat echolocation, etc.) | + +--- + +### Camera -1. Enclosure preparation and component mounting -2. Wiring: power distribution, sensor connections, GPIO mapping -3. Jetson Orin Nano initial boot and configuration -4. Starlink dish alignment and network setup -5. RTC seeding and system clock configuration +| Component | Role | +|---|---| +| Solar WiFi Camera Trap (Γ—1+) | Camera traps for wildlife image capture β€” SPARROW supports **up to 150 cameras** per unit; recommended: Reolink Argus Eco+ | + +--- + +### Enclosure + +| Component | Role | +|---|---| +| IP65 Weatherproof Junction Box (17"Γ—13"Γ—7") | Houses all electronics; rated for outdoor/field deployment | +| Weatherproof Cable Gland Set (PG7–PG19) | Sealed cable routing in/out of enclosure | +| 18AWG Speaker Wire, Zip Ties, DC Barrel Plugs | Internal wiring and cable management | + +--- -## One-Click Jetson Setup +## Assembly Process Overview -Once hardware is assembled, the `setup script/` directory contains an automated setup script that: +1. **Enclosure preparation** β€” drill gland holes, mount DIN rail or panel +2. **Power wiring** β€” solar panels β†’ charge controller β†’ battery β†’ Jetson +3. **Sensor installation** β€” connect IΒ²C boards (RTC, BME688, SHTC3, relay) to Jetson GPIO via Click Shield +4. **Camera network** β€” mount outdoor WiFi antenna(s); configure camera trap SSIDs +5. **Starlink setup** β€” weatherproof cable routing and dish alignment +6. **AudioMoth** β€” connect via USB; configure recording schedule +7. **Final check** β€” verify all connections before first power-up -1. Flashes the Jetson with the required OS image -2. Installs system dependencies -3. Configures the Wi-Fi hotspot -4. Seeds the RTC -5. Builds and launches Docker containers +For detailed instructions with photos and wiring diagrams, see the [SPARROW Assembly and Setup Guide](https://aka.ms/sparrowassembly). -See the [Software Setup](setup.md) page for full details. +Once hardware is assembled, proceed to [Software Setup](setup.md). diff --git a/docs/index.md b/docs/index.md index 2698146..ad464d1 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,34 +1,91 @@ --- -description: "SPARROW β€” Solar-Powered Acoustic and Remote Recording Observation Watch. AI-powered edge computing for wildlife monitoring by Microsoft AI for Good Lab." +description: "SPARROW β€” Solar-Powered Acoustic and Remote Recording Observation Watch. Microsoft AI for Good Lab's open-source edge AI system for wildlife monitoring with NVIDIA Jetson, Starlink, and PyTorch-Wildlife." tags: - SPARROW - edge-ai - wildlife-monitoring - conservation - camera-traps - - jetson + - jetson-orin-nano + - starlink + - pytorch-wildlife + - bioacoustics + - solar-powered --- # SPARROW -**SPARROW** (Solar-Powered Acoustic and Remote Recording Observation Watch) is Microsoft AI for Good Lab's open-source edge AI solution for wildlife monitoring in the most remote regions of the world. +**SPARROW** (Solar-Powered Acoustic and Remote Recording Observation Watch) is Microsoft AI for Good Lab's open-source edge AI system for wildlife monitoring in the most remote regions of the world. -Solar-powered and equipped with multi-modal sensors, SPARROW collects biodiversity data from camera traps, acoustic monitors, and environmental detectors. It processes that data on-device using [PyTorch-Wildlife](https://github.com/microsoft/Pytorch-Wildlife) models running on power-efficient edge GPUs (Jetson Orin Nano), then transmits results via low-Earth-orbit satellites for near-real-time insights β€” no matter how remote the deployment site. +Solar-powered and equipped with multi-modal sensors, SPARROW collects biodiversity data from camera traps, acoustic monitors, and environmental sensors. It processes that data **on-device** using [PyTorch-Wildlife](https://github.com/microsoft/Pytorch-Wildlife) models running on the NVIDIA Jetson Orin Nano β€” no cloud required for inference β€” then transmits results via Starlink low-Earth-orbit satellites for near-real-time insights anywhere on the planet. -## Key capabilities +--- + +## What SPARROW Does + +A single SPARROW unit autonomously: -- **On-device AI** β€” runs PyTorch-Wildlife detection and classification models locally, no cloud required for inference -- **Multi-modal sensing** β€” camera traps, acoustic monitoring, environmental sensors -- **Solar-powered** β€” autonomous operation with intelligent power management and battery health monitoring -- **Global connectivity** β€” Starlink satellite uplink for remote data transmission -- **Resilient** β€” records data offline, syncs automatically when connectivity is restored +1. **Collects data** from up to 150 solar WiFi camera traps, an AudioMoth acoustic sensor, and IΒ²C environmental sensors (temperature, humidity, pressure) +2. **Runs AI models on-device** via NVIDIA Triton Inference Server β€” MegaDetector v6 for animal/human/vehicle detection, species classifiers for identification, and bird-specific detectors +3. **Manages power** intelligently using MPPT solar charging, LiFePO4 batteries, and dynamic component scheduling for continuous off-grid operation +4. **Transmits data** via Starlink satellite when connectivity is available; stores data locally when offline and syncs automatically on reconnect +5. **Scrubs privacy data** β€” automatically detects and removes human-related images before upload -## Quick links +All services run in Docker containers on the Jetson, orchestrated by Docker Compose. + +--- -- [Hardware Setup](hardware.md) β€” bill of materials, assembly, and Jetson Orin Nano setup -- [Software Setup](setup.md) β€” Docker installation, environment configuration, and one-click deploy -- [Cite Us](cite.md) β€” how to cite SPARROW in publications -- [GitHub Repository](https://github.com/microsoft/SPARROW) +## Key Capabilities + +| Capability | Details | +|---|---| +| **On-device AI inference** | MegaDetector v6, Amazon species classifier, bird detector β€” all as ONNX models on NVIDIA Triton | +| **Camera trap support** | Up to 150 solar WiFi cameras per unit (e.g., Reolink Argus Eco+) | +| **Acoustic monitoring** | AudioMoth integration for bioacoustics (birds, bats, insects) | +| **Global connectivity** | Starlink Mini satellite uplink β€” works in locations with no cellular or WiFi | +| **Solar autonomous** | 24V LiFePO4 battery + MPPT solar controller; designed for months of unattended deployment | +| **Environmental sensing** | Temperature, humidity, pressure, gas (BME688 + SHTC3 IΒ²C sensors) | +| **Privacy by design** | On-device human image scrubbing before any data leaves the device | + +--- + +## Architecture + +``` +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ SPARROW Unit (Weatherproof IP65 Box) β”‚ +β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ NVIDIA Jetson Orin Nano β”‚ β”‚ +β”‚ β”‚ β”œβ”€β”€ sparrow (Docker) β”‚ β”‚ +β”‚ β”‚ β”‚ β”œβ”€β”€ Camera polling/ingest β”‚ β”‚ +β”‚ β”‚ β”‚ β”œβ”€β”€ Triton inference β”‚ β”‚ +β”‚ β”‚ β”‚ β”œβ”€β”€ Power mgmt (solar) β”‚ β”‚ +β”‚ β”‚ β”‚ └── Data sync + FTP upload β”‚ β”‚ +β”‚ β”‚ └── starlink (Docker) β”‚ β”‚ +β”‚ β”‚ └── Satellite link monitor β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ +β”‚ Power: Solar panels β†’ MPPT β†’ LiFePO4 β”‚ +β”‚ Network: Starlink Mini satellite dish β”‚ +β”‚ Sensors: AudioMoth, IΒ²C env sensors β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ Data upload (Starlink) + β–Ό + SPARROW Dashboard (cloud) + sparrow-earth.com +``` + +--- + +## Getting Started + +1. **[Hardware Setup](hardware.md)** β€” Bill of materials, component overview, and assembly guide +2. **[Software Setup](setup.md)** β€” One-click Jetson setup script, Docker architecture, AI models +3. **[Cite Us](cite.md)** β€” How to cite SPARROW in publications +4. **[GitHub Repository](https://github.com/microsoft/SPARROW)** β€” Source code, issues, and contributions + +--- ## Part of the Microsoft Biodiversity Ecosystem diff --git a/docs/setup.md b/docs/setup.md index 0f1a9f2..8c465fa 100644 --- a/docs/setup.md +++ b/docs/setup.md @@ -1,73 +1,163 @@ --- -description: "SPARROW software setup β€” Docker installation, environment configuration, and one-click Jetson deploy script for edge wildlife monitoring." +description: "SPARROW software setup β€” one-click Jetson setup script, Docker Compose architecture, NVIDIA Triton inference server, MegaDetector ONNX models, and SPARROW dashboard configuration." tags: - SPARROW - software-setup - docker - jetson + - triton-inference-server + - megadetector + - onnx - installation --- # Software Setup -SPARROW runs entirely in Docker containers. This page covers how to configure and launch the SPARROW software stack on a Jetson Orin Nano. +SPARROW runs entirely in Docker containers orchestrated by Docker Compose. This page covers how to configure and launch the SPARROW software stack on a Jetson Orin Nano. + +--- ## Prerequisites -- Jetson Orin Nano with JetPack 6.x installed -- Docker and Docker Compose installed (included in the one-click setup script) -- Starlink modem connected and configured +- Jetson Orin Nano with **JetPack 6.x** installed and flashed - Hardware assembled per the [Hardware Setup](hardware.md) guide +- SPARROW dashboard account and access key β€” register at [dashboard.sparrow-earth.com](https://dashboard.sparrow-earth.com/) -## Environment Configuration +--- + +## One-Click Setup (Recommended) -Copy the environment templates and fill in your deployment-specific values: +The `sparrow_setup.sh` script in the `setup script/` directory automates the entire Jetson configuration in a single command. + +**Run from `~/Desktop`:** ```bash -cp sparrow.env .env.sparrow -cp starlink.env .env.starlink +cd ~/Desktop +sudo chmod +x sparrow_setup.sh +sudo ./sparrow_setup.sh ``` -Edit `.env.sparrow` and `.env.starlink` with your site-specific configuration (coordinates, upload endpoints, API keys, etc.). +### What the script does + +| Step | Action | +|---|---| +| **1. Prerequisites** | Installs `docker`, `docker-compose`, `git`, `curl`, `wget`, `uuidgen`, `smbus2` | +| **2. Device identity** | Generates `/etc/unique_id` (UUID) if missing | +| **3. Folder layout** | Creates `~/Desktop/system/` with all required directories (see below) | +| **4. Models** | Downloads three default ONNX models from Zenodo; writes Triton `config.pbtxt` | +| **5. Access key** | Prompts for your SPARROW dashboard access key; writes to `sparrow/config/access_key.txt` and `starlink/config/access_key.txt` | +| **6. RTC seeding** | Gets UTC from WorldClock API (fallback: NTP) and writes to DS3231 RTC over IΒ²C bus 7 | +| **7. Wi-Fi hotspot** | Configures a persistent `NetworkManager` hotspot on the Jetson for camera trap connectivity | +| **8. Docker build + launch** | Builds images with BuildKit (no cache), runs `docker-compose up -d`, tails logs | + +### Deployed folder structure + +``` +~/Desktop/system/ +β”œβ”€β”€ docker-compose.yml +β”œβ”€β”€ sparrow_setup.sh +β”œβ”€β”€ Models/ +β”‚ └── tritonserver/ +β”‚ └── model_repository/ +β”‚ β”œβ”€β”€ megadetectorv6/ ← MegaDetector v6 ONNX +β”‚ β”‚ β”œβ”€β”€ 1/model.onnx +β”‚ β”‚ └── config.pbtxt +β”‚ β”œβ”€β”€ AI4GAmazonClassification/ ← Amazon species classifier ONNX +β”‚ β”‚ β”œβ”€β”€ 1/model.onnx +β”‚ β”‚ └── config.pbtxt +β”‚ └── megadetector_birds_v1/ ← Bird detector ONNX +β”‚ β”œβ”€β”€ 1/model.onnx +β”‚ └── config.pbtxt +β”œβ”€β”€ sparrow/ +β”‚ β”œβ”€β”€ Dockerfile +β”‚ β”œβ”€β”€ config/access_key.txt +β”‚ β”œβ”€β”€ images/ +β”‚ β”œβ”€β”€ recordings/ +β”‚ β”œβ”€β”€ logs/ +β”‚ └── static/data/ static/gallery/ +└── starlink/ + β”œβ”€β”€ Dockerfile.starlink + β”œβ”€β”€ config/access_key.txt + └── logs/ +``` + +--- + +## AI Models + +SPARROW uses NVIDIA Triton Inference Server to run ONNX models on the Jetson's GPU. Three models are deployed by default: + +| Model | Purpose | +|---|---| +| `megadetectorv6` | Detects animals, people, and vehicles in camera trap images ([MegaDetector](https://github.com/microsoft/MegaDetector)) | +| `AI4GAmazonClassification` | Species classification for Amazon Basin wildlife | +| `megadetector_birds_v1` | Bird-specific detector optimized for acoustic + visual monitoring | + +All models are downloaded as ONNX format and served via Triton's gRPC/HTTP endpoints on ports 8000–8002. + +--- + +## Docker Services + +Two containers run on the Jetson: + +### `sparrow` + +The main SPARROW service β€” handles: +- **Camera trap management** β€” WiFi camera polling, image download, deduplication +- **On-device inference** β€” submits images to Triton for MegaDetector detection + species classification +- **Power management** β€” monitors solar charge controller, battery state, dynamic component scheduling +- **Telemetry** β€” environmental sensor readings (BME688, SHTC3), system health metrics +- **Data sync** β€” FTP/HTTP upload to SPARROW dashboard when connectivity is available +- **Privacy scrubbing** β€” removes human-related images before upload + +### `starlink` + +Monitors Starlink satellite connectivity via gRPC, logs signal metrics, and triggers data sync when uplink is available. + +--- + +## Environment Configuration + +The `sparrow.env` and `starlink.env` files in the repo root are **configuration templates**. The setup script fills in deployment-specific values (access key, FTP password). Key variables: + +| Variable | Purpose | +|---|---| +| `SERVER_BASE_URL` | SPARROW dashboard API endpoint | +| `FTP_PASS` | FTP upload credential (prompted during setup) | +| `UNIQUE_ID_PATH` | Path to device UUID (`/host/etc/unique_id`) | !!! warning - Never commit `.env` files containing real credentials. The `.gitignore` already excludes `.env` files. + Never commit `.env` files containing real credentials. The `.gitignore` already excludes all `.env` files. -## Docker Compose Launch +--- -Start the full SPARROW stack: +## Manual Launch (Advanced) + +To launch without the setup script (assumes folder structure already exists): ```bash +cd ~/Desktop/system docker compose up -d ``` -This launches two services defined in `docker-compose.yml`: - -- **sparrow** β€” camera trap capture, on-device AI inference (PyTorch-Wildlife), data management, power control, telemetry -- **starlink** β€” Starlink satellite connectivity monitoring and data uplink - View logs: ```bash docker compose logs -f ``` -## One-Click Jetson Setup - -For a fresh Jetson deployment, use the automated setup script in `setup script/`: +Restart a specific service: ```bash -cd "setup script" -./setup.sh +docker compose restart sparrow ``` -This script handles all steps from OS configuration through Docker launch. See the [Assembly and Setup Guide PDF](https://github.com/microsoft/SPARROW/blob/main/documentation/SPARROW_Assembly_and_Setup_Guide.pdf) for full details on each step. - -## Dependencies +--- -Python dependencies are organized per service: +## SPARROW Dashboard -- `sparrow/requirements.txt` β€” AI/ML stack (torch, torchvision, librosa, etc.) -- `starlink/requirements.txt` β€” Starlink gRPC interface +Data collected and processed by SPARROW is uploaded to the [SPARROW Dashboard](https://dashboard.sparrow-earth.com/) for visualization, filtering, and export. -These are installed inside their respective Docker images β€” no manual `pip install` needed on the host. +- Register for an account and obtain your access key at [dashboard.sparrow-earth.com](https://dashboard.sparrow-earth.com/) +- Dashboard Terms & Conditions: [sparrow-earth.com/agreement](https://dev.sparrow-earth.com/agreement) From 3986e4200dd365924b72525ca3208cb91f408981 Mon Sep 17 00:00:00 2001 From: rain-Brian Date: Thu, 14 May 2026 13:21:51 -0700 Subject: [PATCH 3/3] chore: remove empty legacy Azure pipeline placeholder File contained only a blank line and had a typo in the filename (piplines). --- .azure/azure-piplines.yml | 0 1 file changed, 0 insertions(+), 0 deletions(-) delete mode 100644 .azure/azure-piplines.yml diff --git a/.azure/azure-piplines.yml b/.azure/azure-piplines.yml deleted file mode 100644 index e69de29..0000000