Foxglove SDK documentation¶

Version: 0.9.1

The official Foxglove SDK for Python.

This package provides support for integrating with the Foxglove platform. It can be used to log events to local MCAP files or a local visualization server that communicates with the Foxglove app.

Getting started¶

Install the foxglove-sdk package from PyPI.

This will depend on your package manager. Our examples use poetry.

To record messages, you need to initialize either an MCAP file writer or a WebSocket server for live visualization.

For a hands-on walk-through, see https://docs.foxglove.dev/docs/sdk/example?lang=python.

Concepts¶

Context¶

A Context is the binding between channels and sinks. Each channel and sink belongs to exactly one context. Sinks receive advertisements about channels on the context, and can optionally subscribe to receive logged messages on those channels.

When the context goes out of scope, its corresponding channels and sinks will be disconnected from one another, and logging will stop. Attempts to log further messages on the channels will elicit throttled warning messages.

Since many applications only need a single context, the SDK provides a static default context for convenience.

Channels¶

A Channel gives a way to log related messages which have the same type, or Schema. Each channel is instantiated with a unique “topic”, or name, which is typically prefixed by a /. If you’re familiar with MCAP, it’s the same concept as an [MCAP channel](https://mcap.dev/guides/concepts#channel).

A channel is always associated with exactly one Context throughout its lifecycle. The channel remains attached to the context until it is either explicitly closed with Channel.close, or the context is dropped. Attempting to log a message on a closed channel will elicit a throttled warning.

Schemas¶

The SDK provides classes for well-known schemas. These can be used in conjunction with associated channel classes for type-safe logging, which ensures at compile time that messages logged to a channel all share a common schema. For example, you may create a channels.SceneUpdateChannel on which you will log schemas.SceneUpdate messages. Note that the schema classes are currently immutable and do not expose getters and setters for their fields. This is a limitation we plan to address in the future.

You can also log messages with arbitrary schemas and provide your own encoding, by instantiating a Channel class.

Sinks¶

A “sink” is a destination for logged messages. If you do not configure a sink, log messages will simply be dropped without being recorded. You can configure multiple sinks, and you can create or destroy them dynamically at runtime.

A sink is typically associated with exactly one Context throughout its lifecycle. Details about how the sink is registered and unregistered from the context are sink-specific.

To create an MCAP file sink, use open_mcap() and keep a reference to the returned handle. As long as the handle remains in scope, events will be logged to the MCAP file. When the handle is closed or dropped, the sink will be unregistered from the Context, and the file will be finalized and flushed.

To create a live visualization server sink, use start_server(). By default, the server listens on 127.0.0.1:8765. Each client that connects to the websocket server is its own independent sink. The sink is dynamically added to the Context associated with the server when the client connects, and removed from the context when the client disconnects.