CitraSense

Documentation | Citra.space | PyPI | CitraSense-Pi

Photograph satellites from your backyard telescope.

CitraSense turns your astrophotography rig into an autonomous satellite observation station. It connects to Citra.space, picks up tasks for specific satellites, slews your telescope, captures images, and processes everything on the edge — plate solving, source extraction, photometry, and satellite matching — before delivering calibrated results back to the platform.

Use Citra.space to search for satellites, schedule observation windows, and task your telescope — CitraSense handles the rest. If you already have a mount, a camera, and software like N.I.N.A. or KStars/Ekos, CitraSense plugs right in. Install it, select your hardware adapter, and you're one click away from photographing the ISS.

Supported Hardware

Quick Start

Requires Python 3.10+. We recommend uv for installation.

# Install and run
uv tool install citrasense
citrasense

Or with pip:

pip install citrasense
citrasense

Open http://localhost:24872 in your browser to configure your hardware adapter, connect to Citra.space, and start accepting tasks.

Raspberry Pi? Check out citrasense-pi for a ready-to-flash SD card image with CitraSense pre-installed.

Optional Extras

uv tool install citrasense --with citrasense[indi]        # INDI protocol support
uv tool install citrasense --with citrasense[kstars]      # KStars/Ekos via D-Bus
uv tool install citrasense --with citrasense[usb-camera]  # USB cameras via OpenCV
uv tool install citrasense --with citrasense[rpi]         # Raspberry Pi Camera Module
uv tool install citrasense --with citrasense[all]         # INDI + KStars

pip install citrasense[indi]
pip install citrasense[kstars]
pip install citrasense[usb-camera]
pip install citrasense[rpi]
pip install citrasense[all]

CLI Options

citrasense --help
citrasense --web-port 8080    # Custom web UI port (default: 24872)

Documentation

Full documentation is available at docs.citra.space/citrasense. Documentation source is maintained in the citra-space/docs repository.

Developer Setup

uv sync --extra dev
uv run pre-commit install

Dev Container (INDI on macOS/Windows)

If you need to work with the INDI adapter on a non-Linux host, the project includes a VS Code Dev Container that provides a Linux environment with pyindi-client and its system dependencies pre-installed. Open the project in VS Code and choose Reopen in Container.

Running Tests

uv run pytest                          # Unit tests (fast, skips slow tests)
uv run pytest -m "not integration"     # Same as above, explicit
uv run pytest --override-ini="addopts=" -m "not integration"  # Include slow tests locally

Tests use pytest markers to separate fast unit tests from expensive ones:

Pre-commit Hooks

The project uses pre-commit with Ruff (linting + import sorting), Black (formatting), and Pyright (type checking).

uv run pre-commit run --all-files    # Run all checks manually

VS Code Launch Configs

The .vscode/launch.json includes pre-configured debug configurations:

• Python: citrasense — Runs the daemon with default settings
• Python: citrasense (custom port) — Runs with web interface on port 8080

Releasing

bump-my-version bump patch    # 0.1.3 → 0.1.4
bump-my-version bump minor    # 0.1.3 → 0.2.0
bump-my-version bump major    # 0.1.3 → 1.0.0
git push && git push --tags

Tagging triggers create-release.yml which creates a GitHub release, which in turn triggers pypi-publish.yml.

License

MIT