Allsky Server API

The Allsky Server is a separate process that runs alongside Allsky its primary job is to handle longer running processes and to manage GPIO Coontrol. Its core functions are:

• The Allsky dashboard whcich displays information about Allsky - currently under development.
• The Allsky focuser which allows a camera with a focus motor to be focused - currently under development.
• The Pi's GPIO pins, both digital and PWM.

Authentication

The API requires authentication under the following circumstances.

• You are unsing the inbuilt Dashboard, in this case the authentication will be via a login screen using the same login and password as Allaky.
• You are using the api from an external machine. In this case you will need to request a JWT token from the API.

If you are using the API from the local machine then no authentication is required for any API.

Requesting a JWT token

To get a JWT token use the following API endpoint.

POST /login

This expects a username and password and returns a JWT token.

TODO: Add Hoppscotch examples TODO: Creating users

The Available API's

allsky

allsky_status()

GET /allsky/status

Retrieve the current Allsky system status.

This endpoint queries backend logic (get_allsky_status) and returns a full status dictionary, plus a rendered HTML fragment used by the web frontend.

Authentication

Requires: api_auth_required("allsky", "read")

Returns:

Name	Type	Description
dict		A JSON object containing: - All fields provided by get_allsky_status() - status_html: Rendered HTML snippet for UI display

Source code in modules/allsky/__init__.py

@allsky_bp.route('/status', methods=['GET'])
@api_auth_required("allsky", "read")
def allsky_status():
    """
    GET /allsky/status

    Retrieve the current Allsky system status.

    This endpoint queries backend logic (get_allsky_status) and returns a full
    status dictionary, plus a rendered HTML fragment used by the web frontend.

    Authentication:
        Requires: ``api_auth_required("allsky", "read")``

    Returns:
        dict: A JSON object containing:
            - All fields provided by ``get_allsky_status()``
            - ``status_html``: Rendered HTML snippet for UI display
    """
    status = get_allsky_status()
    status_html = render_template("_partials/_allskyStatus.html", status=status)
    status['status_html'] = status_html
    return status

restart_allsky()

GET /allsky/restart

Restart the Allsky service.

Authentication

Requires: api_auth_required("allsky", "update")

Returns:

Name	Type	Description
JSON		{"status": "Allsky started"}

Source code in modules/allsky/__init__.py

@allsky_bp.route('/restart', methods=['GET'])
@api_auth_required("allsky", "update")
def restart_allsky():
    """
    GET /allsky/restart

    Restart the Allsky service.

    Authentication:
        Requires: ``api_auth_required("allsky", "update")``

    Returns:
        JSON: ``{"status": "Allsky started"}``
    """
    subprocess.run(['sudo', 'systemctl', 'restart', 'allsky'])
    return jsonify({'status': 'Allsky started'})

start_allsky()

GET /allsky/start

Start the Allsky service.

Authentication

Requires: api_auth_required("allsky", "update")

Returns:

Name	Type	Description
JSON		{"status": "Allsky started"}

Source code in modules/allsky/__init__.py

@allsky_bp.route('/start', methods=['GET'])
@api_auth_required("allsky", "update")
def start_allsky():
    """
    GET /allsky/start

    Start the Allsky service.

    Authentication:
        Requires: ``api_auth_required("allsky", "update")``

    Returns:
        JSON: ``{"status": "Allsky started"}``
    """
    subprocess.run(['sudo', 'systemctl', 'start', 'allsky'])
    return jsonify({'status': 'Allsky started'})

stop_allsky()

GET /allsky/stopallsky

Stop the Allsky service and immediately start the AllskyServer service.

This is commonly used during debugging or maintenance when the capture component needs to be restarted but the web interface should remain active.

Authentication

Requires: api_auth_required("allsky", "update")

Returns:

Name	Type	Description
JSON		{"status": "Allsky stopped"}

Source code in modules/allsky/__init__.py

@allsky_bp.route('/stopallsky', methods=['GET'])
@api_auth_required("allsky", "update")
def stop_allsky():
    """
    GET /allsky/stopallsky

    Stop the Allsky service and immediately start the AllskyServer service.

    This is commonly used during debugging or maintenance when the capture
    component needs to be restarted but the web interface should remain active.

    Authentication:
        Requires: ``api_auth_required("allsky", "update")``

    Returns:
        JSON: ``{"status": "Allsky stopped"}``
    """
    subprocess.run(['sudo', 'systemctl', 'stop', 'allsky'])
    subprocess.run(['sudo', 'systemctl', 'start', 'allskyserver'])
    return jsonify({'status': 'Allsky stopped'})

stop_allsky_all()

GET /allsky/stopall

Stop the Allsky service.

This fully stops the "allsky" systemd service.

Authentication

Requires: api_auth_required("allsky", "update")

Returns:

Name	Type	Description
JSON		{"status": "Allsky stopped"}

Source code in modules/allsky/__init__.py

@allsky_bp.route('/stopall', methods=['GET'])
@api_auth_required("allsky", "update")
def stop_allsky_all():
    """
    GET /allsky/stopall

    Stop the Allsky service.

    This fully stops the "allsky" systemd service.

    Authentication:
        Requires: ``api_auth_required("allsky", "update")``

    Returns:
        JSON: ``{"status": "Allsky stopped"}``
    """
    subprocess.run(['sudo', 'systemctl', 'stop', 'allsky'])
    return jsonify({'status': 'Allsky stopped'})

gpio

get_gpio_backend()

Lazily select a GPIO backend.

Source code in modules/gpio/__init__.py

def get_gpio_backend():
    """
    Lazily select a GPIO backend.
    """
    global gpio_backend, gpio_backend_error

    if gpio_backend is not None:
        return gpio_backend

    try:
        gpio_backend = select_gpio_backend()
        return gpio_backend
    except GPIOBackendUnavailable as exc:
        gpio_backend_error = str(exc)
        raise

get_gpio_count()

Return the number of GPIO lines exposed by the active backend.

Source code in modules/gpio/__init__.py

def get_gpio_count():
    """
    Return the number of GPIO lines exposed by the active backend.
    """
    return get_gpio_backend().get_gpio_count()

get_gpio_status()

Inspect all available GPIO lines and return their current usage.

Returns:

Name	Type	Description
dict	dict	Status for each Dxx pin on the board.

Source code in modules/gpio/__init__.py

def get_gpio_status() -> dict:
    """
    Inspect all available GPIO lines and return their current usage.

    Returns:
        dict: Status for each Dxx pin on the board.
    """
    all_status = {}
    gpio_count = get_gpio_count()

    for pin_num in range(gpio_count):
        pin = str(pin_num)
        status = {"mode": "unused"}

        if pin in digital_pins:
            info = digital_pins[pin]
            direction = info["direction"]
            status["mode"] = f"digital-{direction}"
            status["value"] = "on" if _read_pin_value(pin_num) else "off"
        elif pin in pwm_pins:
            pwm = pwm_pins[pin]
            status["mode"] = "pwm"
            status["frequency"] = pwm["frequency"]
            status["duty"] = pwm["duty"]

        all_status[f"D{pin_num}"] = status

    return all_status

normalise_pin(gpio_str)

Validate and normalise a GPIO pin number.

Parameters:

Name	Type	Description	Default
gpio_str	str | int	Pin number, e.g. "18".	required

Returns:

Type	Description
	tuple[str, int]: String form and integer form of the GPIO number.

Source code in modules/gpio/__init__.py

def normalise_pin(gpio_str):
    """
    Validate and normalise a GPIO pin number.

    Args:
        gpio_str (str | int): Pin number, e.g. "18".

    Returns:
        tuple[str, int]: String form and integer form of the GPIO number.
    """
    pin = str(gpio_str).strip()

    try:
        pin_num = int(pin)
    except (TypeError, ValueError):
        raise ValueError(f"Invalid GPIO pin {gpio_str}")

    if pin_num < 0 or pin_num >= get_gpio_count():
        raise ValueError(f"Invalid GPIO pin {gpio_str}")

    return pin, pin_num