Welcome to POCS documentation!

Project PANOPTES

PANOPTES is an open source citizen science project designed to find transiting exoplanets with digital cameras. The goal of PANOPTES is to establish a global network of of robotic cameras run by amateur astronomers and schools (or anyone!) in order to monitor, as continuously as possible, a very large number of stars. For more general information about the project, including the science case and resources for interested individuals, see the project overview.

POCS

POCS (PANOPTES Observatory Control System) is the main software driver for a PANOPTES unit, responsible for high-level control of the unit.

For more information, see the full documentation at: https://pocs.readthedocs.io.

Install

POCS Environment

If you are running a PANOPTES unit then you will most likely want an entire PANOPTES environment, which includes the necessary tools for operation of a complete unit.

There is a bash shell script that will install an entire working POCS system on your computer. Some folks even report that it works on a Mac.

To install POCS via the script, open a terminal and enter (you may be prompted for your sudo password):

curl -fsSL https://install.projectpanoptes.org > install.sh
bash install.sh

Or using wget:

wget -qO- https://install.projectpanoptes.org > install.sh
bash install.sh

The install script will ask a few questions at the beginning of the process. If you are unsure of the answer the default is probably okay.

In addition to installing POCS, the install script will create the Config Server and Power Monitor services, which will automatically be restarted upon reboot of the computer.

POCS Module

If you want just the POCS module, for instance if you want to override it in your own OCS (see Huntsman-POCS for an example), then install via pip:

pip install panoptes-pocs

If you want the extra features, such as Google Cloud Platform connectivity, then use the extras options:

pip install "panoptes-pocs[google,focuser,testing]"

Running POCS

POCS requires a few things to properly run:

1. A panoptes-utils config-server running to provide dynamic configuration.
2. An Observatory instance that has details about the location of a POCS unit (real or simulated), which hardware is available, etc.

A minimal working example with a simulated Observatory would be:

import os
from panoptes.utils.config.server import config_server
from panoptes.pocs.core import POCS

os.environ['PANDIR'] = '/var/panoptes'
conf_server = config_server('conf_files/pocs.yaml')
I 01-20 01:01:10.886 Starting panoptes-config-server with  config_file='conf_files/pocs.yaml'
S 01-20 01:01:10.926 Config server Loaded 17 top-level items
I 01-20 01:01:10.928 Config items saved to flask config-server
I 01-20 01:01:10.934 Starting panoptes config server with localhost:6563

pocs = POCS.from_config(simulators=['all'])
I 01-20 01:01:20.408 Initializing PANOPTES unit - Generic PANOPTES Unit - Mauna Loa Observatory
I 01-20 01:01:20.419 Making a POCS state machine from panoptes
I 01-20 01:01:20.420 Loading state table: panoptes
S 01-20 01:01:20.485 Unit says: Hi there!
W 01-20 01:01:20.494 Scheduler not present
W 01-20 01:01:20.495 Cameras not present
W 01-20 01:01:20.496 Mount not present
I 01-20 01:01:20.497 Scheduler not present, cannot get current observation.

pocs.initialize()
W 01-20 01:01:28.386 Scheduler not present
W 01-20 01:01:28.388 Cameras not present
W 01-20 01:01:28.389 Mount not present
S 01-20 01:01:28.390 Unit says: Looks like we're missing some required hardware.
Out[10]: False

For a more realistic usage, see the full documentation at: https://pocs.readthedocs.io.

For actually deploying a PANOPTES unit, refer to the Operating Guider.

Developing POCS

See Coding in PANOPTES

Development with Hatch

This project uses the Hatch build system and environment management.

Prerequisites:

• Python 3.12+
• Hatch: https://hatch.pypa.io (install via pipx install hatch or pip install --user hatch).

Basic workflow:

• Create and enter a dev environment with all testing tools:

  hatch env create
  hatch shell
  # or run commands without activating the shell using `hatch run ...`

• Install optional extras as needed (choose any):

  # Examples: google, focuser, sensors, weather
  hatch run pip install -e ".[google,focuser,sensors,weather,testing]"

• Run tests:

  # All tests with coverage, using pytest options from pyproject.toml
  hatch run pytest
  
  # Single test file
  hatch run pytest tests/test_mount.py

• Lint / style checks:

  # Lint (Ruff)
  hatch run lint
  # Format (Ruff)
  hatch run fmt
  # Check formatting without changes
  hatch run fmt-check

• Build the package (wheel and sdist):

  hatch build

• Run the CLI locally (Typer app):

  hatch run pocs --help

• Versioning: Version is derived from git tags via hatch-vcs. To produce a new version, create and push a tag (e.g., v0.1.0).

Testing

To test the software, prefer running via Hatch so the right environment and options are used:

hatch run pytest

By default all tests will be run. If you want to run one specific test, give the specific filename as an argument to pytest:

hatch run pytest tests/test_mount.py

Links

• PANOPTES Homepage: https://www.projectpanoptes.org
• Forum: https://forum.projectpanoptes.org
• Documentation: https://pocs.readthedocs.io
• Source Code: https://github.com/panoptes/POCS