Harbor Python

Async Python client for connecting locally to Harbor Sleep Cameras.

harbor-python speaks directly to Harbor devices on your local network over MQTT, using the camera certificate material issued for your setup. It provides typed event parsing, device state tracking, command publishing, and helpers for configuring local WHIP streaming targets.

Installation

pip install harbor-python

Python 3.11 or newer is required.

Quick Start

import asyncio

from harbor import Harbor, HarborCamera, HarborCameraConfig, HeartbeatUpdate


async def main() -> None:
    config = HarborCameraConfig(
        serial="CAMERA_SERIAL",
        ip_address="192.168.1.50",
        cert_path="/path/to/cert.pem",
        key_path="/path/to/key.pem",
    )

    harbor = Harbor()
    camera = HarborCamera(config)

    camera.subscribe_updates(
        lambda state: print(f"{state.serial} values: {state.values}")
    )
    camera.subscribe(
        HeartbeatUpdate,
        lambda event: print(f"temperature: {event.payload.temperature}"),
    )

    harbor.add_device(camera)
    harbor.add_camera_connection(config)

    try:
        await harbor.start()
        await asyncio.Event().wait()
    finally:
        await harbor.stop()


asyncio.run(main())

On Windows, aiomqtt works best with the selector event loop policy:

import asyncio
import sys

if sys.platform == "win32":
    asyncio.set_event_loop_policy(asyncio.WindowsSelectorEventLoopPolicy())

Certificate Configuration

HarborCameraConfig accepts certificate material in either form:

HarborCameraConfig(
    serial="CAMERA_SERIAL",
    ip_address="192.168.1.50",
    cert_pem="<certificate PEM contents>",
    key_pem="<private key PEM contents>",
)

or:

HarborCameraConfig(
    serial="CAMERA_SERIAL",
    ip_address="192.168.1.50",
    cert_path="/path/to/cert.pem",
    key_path="/path/to/key.pem",
    cert_dir="/path/to/ca-directory",
)

When both PEM strings and file paths are provided, the in-memory PEM values are used.

Commands

Camera commands can be published directly:

await harbor.publish_camera_command("CAMERA_SERIAL", "some-command", {"value": True})

For request/response commands, use request_camera_command or the settings helper:

settings = await harbor.get_camera_settings("CAMERA_SERIAL")
print(settings.settings)

Camera controls

await harbor.set_camera_on("CAMERA_SERIAL", False)      # privacy: pause the stream
await harbor.set_night_mode("CAMERA_SERIAL", "auto")    # "auto" | "on" | "off"
await harbor.set_video_flip("CAMERA_SERIAL", True)      # rotate the image 180°
await harbor.set_clock_display("CAMERA_SERIAL", False)  # clock overlay on the video
await harbor.set_temperature_scale("CAMERA_SERIAL", "C")  # "F" | "C"
await harbor.update_camera_settings(
    "CAMERA_SERIAL", {"preference_video_ir_brightness": 40}
)

Each control writes one preference and refreshes device state, so camera.state.values reflects the change once the call returns:

camera.state.values[...]	Type	Setting
camera_on	bool	preference_stream_paused (inverted)
night_mode_preference	"auto" | "on" | "off"	preference_video_night_mode
night_mode	bool	runtime IR state (read-only, see below)
video_flip	bool	preference_video_flip
clock_display	bool	preference_video_has_clock_display
temperature_scale	"F" | "C"	preference_temperature_scale

set_video_flip and set_clock_display take real booleans — 1/0 and "true" raise ValueError rather than being sent as a number or string, which the firmware would reject.

The enum setters validate against the firmware's own option list, exported as NIGHT_MODE_MODES and TEMPERATURE_SCALES. Matching is exact: "f" raises ValueError, because the device compares the string verbatim. State values preserve case for the same reason — what you read back is always something you can write.

Night mode

Night mode is a three-way preference, not a boolean — "auto", "on" or "off" (default "auto"). Passing a bool raises ValueError rather than guessing at a mode. A camera exposes two separate night-mode values:

camera.state.values[...]	Type	Meaning
night_mode_preference	"auto" | "on" | "off"	The setting. This is what set_night_mode writes and what reads back.
night_mode	bool	Whether IR is engaged right now. Read-only and device-driven — under "auto" it flips on its own as light levels change.

Consumers building a UI entity should bind it to night_mode_preference, since night_mode moves independently of any command.

Command errors

A rejected command raises HarborCommandError, which carries the parsed status and the firmware's per-field errors list:

from harbor import HarborCommandError, HarborUnsupportedCommandError

try:
    await harbor.set_night_mode("CAMERA_SERIAL", "on")
except HarborUnsupportedCommandError:
    ...  # firmware has no such command; permanent, so stop offering the feature
except HarborCommandError as err:
    print(err.status, err.errors)  # e.g. "REQUEST_MALFORMED", [{"error_code": "INVALID_VALUE", ...}]

HarborUnsupportedCommandError is a subclass of HarborCommandError, raised only on a RESOURCE_NOT_FOUND status. That means the firmware has no handler for the command at all, so retrying can never succeed.

Firmware compatibility

Commands are verified against real hardware, most recently a camera running os_version 2.8.0 / app_version 2.8.0-rc1+c1b0a32: ping, get-settings, update-settings, pause-stream, unpause-stream, set-night-mode-ir-brightness, update-operating-mode, set-scheduled-reboot and list-viewers all respond OK. See mqtt_home_assistant.md for the full audit and payload shapes.

WHIP Endpoint

Harbor cameras allow custom WHIP endpoints. This tells the camera where to stream and works with tools that support WHIP, including go2rtc and Frigate.

Setting up WHIP Ingestion (go2rtc)

You can self-host go2rtc in many ways; see the go2rtc installation guide. If you use Home Assistant, the easiest option is the go2rtc add-on.

Once go2rtc is running, add a stream keyed by your camera serial number:

api:
  listen: ":1984" # Change this if you use a non-default port.

streams:
  "CAMERA_SERIAL":

Setting up WHIP Ingestion (Frigate)

Frigate runs an instance of go2rtc under the hood. Add the following to your Frigate config:

go2rtc:
  api:
    listen: ":1984"
  streams:
    "CAMERA_SERIAL":

Setting the Endpoint

1. Open your Harbor app
2. Go to Live
3. Open Camera Settings
4. Scroll down and click on Advanced Settings
5. Enter the WHIP endpoint, for example: http://192.168.1.10:1984/api/webrtc?dst=CAMERA_SERIAL

Replace CAMERA_SERIAL with your camera serial number and 192.168.1.10 with the IP address of your go2rtc or Frigate server.

Repairing packet loss

WHIP media runs over UDP by default, and go2rtc does not negotiate retransmission. RegisterDefaultCodecs in pkg/webrtc/api.go registers no RTX (RFC 4588) codec, so go2rtc strips rtx/90000 out of its SDP answer while still advertising a=rtcp-fb:96 nack. Harbor cameras offer RTX correctly, but the answer deletes the channel those retransmissions would travel on — go2rtc asks the camera to retransmit over something it just removed, so nothing is ever repaired. This is true as of go2rtc 1.9.10 and current master.

The symptom is occasional blocky or smeared frames that clear on the next keyframe. Each lost packet damages the frame it belonged to, so even a very low loss rate is visible — 0.03% loss on a 20 fps stream is a handful of damaged frames every few minutes.

Running the WHIP session over ICE-TCP sidesteps this. The kernel retransmits lost segments and delivers them in order, with no SDP negotiation involved:

webrtc:
  listen: ":8555/tcp"
  candidates:
    - 192.168.1.10:8555
  filters:
    networks: [tcp4]

Nest that block under go2rtc: if you are configuring Frigate.

Both settings are required. filters on its own is not enough: with a bare listen: ":8555", go2rtc registers every entry in candidates as both a TCP and a UDP candidate, so it would keep advertising a UDP candidate that the filter had stopped anything from listening on.

Confirm it took effect by checking the producer's transport, which should read http+tcp:

curl -s "http://192.168.1.10:1984/api/streams?src=CAMERA_SERIAL" | grep protocol

Frigate does not expose port 1984 by default — use http://FRIGATE_HOST:5000/api/go2rtc/api/streams?src=CAMERA_SERIAL instead.

What this costs:

• Loss becomes latency instead of corruption. A sustained wifi dropout shows up as a stall rather than a glitch.
• filters applies to all inbound WebRTC, so browser live view moves to TCP as well. If you watch streams from outside your network, forward 8555/tcp, not only UDP.
• The camera's congestion control stops having an effect, since TCP handles pacing. That is not a concern at the camera's bitrate on a local network, but it does mean the camera will not lower quality if the link saturates.

Measured on one Harbor camera pushing 1728x1080 HEVC over wifi, video packet loss over a 3 minute sample went from 0.039% to 0.000%.

Development

uv sync
uv run pytest

License

Licensed under the Apache License 2.0.