API Reference

Version: 0.7.0

foxglove

This module provides interfaces for logging messages to Foxglove.

See foxglove.schemas and foxglove.channels for working with well-known Foxglove schemas.

class foxglove.Channel(topic, *, schema=None, message_encoding=None)

A channel that can be used to log binary messages or JSON messages.

close()

Close the channel.

You can use this to explicitly unadvertise the channel to sinks that subscribe to channels dynamically, such as the foxglove.websocket.WebSocketServer.

Attempts to log on a closed channel will elicit a throttled warning message.

Return type:

None

id()

The unique ID of the channel

Return type:

int

log(msg, *, log_time=None)

Log a message on the channel.

Parameters:

  • msg (Union[Dict[str, Any], list[Any], bytes, str]) – the message to log. If the channel uses JSON encoding, you may pass a dictionary or list. Otherwise, you are responsible for serializing the message.

  • log_time (Optional[int] (default: None)) – The optional time the message was logged.

Return type:

None

schema_name()

The name of the schema for the channel

Return type:

Optional[str]

topic()

The topic name of the channel

Return type:

str

class foxglove.Schema(*, name, encoding, data)

A Schema is a description of the data format of messages or service calls.

Parameters:

  • name (str) – The name of the schema.

  • encoding (str) – The encoding of the schema.

  • data (bytes) – Schema data.

data

Schema data.

encoding

The encoding of the schema.

name

The name of the schema.

foxglove.log(topic, message, *, log_time=None)

Log a message on a topic.

Creates a new channel the first time called for a given topic. For Foxglove types in the schemas module, this creates a typed channel (see foxglove.channels for supported types). For bytes and str, this creates a simple schemaless channel and logs the bytes as-is. For dict and list, this creates a schemaless json channel.

The type of the message must be kept consistent for each topic or an error will be raised. This can be avoided by creating and using the channels directly instead of using this function.

Note: this raises an error if a channel with the same topic was created by other means. This limitation may be lifted in the future.

Parameters:
Return type:

None

foxglove.open_mcap(path, *, allow_overwrite=False, writer_options=None)

Open a new mcap file for recording.

Parameters:

  • path (str | Path) – The path to the MCAP file. This file will be created and must not already exist.

  • allow_overwrite (Optional[bool]) – Set this flag in order to overwrite an existing file at this path.

  • writer_options (mcap.MCAPWriteOptions) – Options for the MCAP writer.

Return type:

mcap.MCAPWriter

foxglove.set_log_level(level='INFO')

Enable SDK logging.

This function will call logging.basicConfig() for convenience in scripts, but in general you should configure logging yourself before calling this function: https://docs.python.org/3/library/logging.html

Parameters:

level (Union[int, str] (default: 'INFO')) – The logging level to set. This accepts the same values as logging.setLevel and defaults to “INFO”. The SDK will not log at levels “CRITICAL” or higher.

Return type:

None

foxglove.start_server(*, name=None, host='127.0.0.1', port=8765, capabilities=None, server_listener=None, supported_encodings=None, services=None, asset_handler=None)

Start a websocket server for live visualization.

Parameters:

  • name (Optional[str] (default: None)) – The name of the server.

  • host (Optional[str] (default: '127.0.0.1')) – The host to bind to.

  • port (Optional[int] (default: 8765)) – The port to bind to.

  • capabilities (Optional[List[Capability]] (default: None)) – A list of capabilities to advertise to clients.

  • server_listener (Optional[ServerListener] (default: None)) – A Python object that implements the websocket.ServerListener protocol.

  • supported_encodings (Optional[List[str]] (default: None)) – A list of encodings to advertise to clients.

  • services (Optional[List[Service]] (default: None)) – A list of services to advertise to clients.

  • asset_handler (Optional[Callable[[str], Optional[bytes]]] (default: None)) – A callback function that returns the asset for a given URI, or None if it doesn’t exist.

Return type:

WebSocketServer

Schemas

Channels

Parameters

Used with the parameter service during live visualization. Requires the websocket.Capability.Parameters capability.

class foxglove.websocket.ParameterType

A parameter type.

ByteArray

A byte array.

Float64

A decimal or integer value that can be represented as a 64-bit floating point number.

Float64Array

An array of decimal or integer values that can be represented as 64-bit floating point numbers.

class foxglove.websocket.ParameterValue

A parameter value.

class Number(value: float)

A decimal or integer value.

class Bool(value: bool)

A boolean value.

class String(value: str)

A string value.

For parameters of type ParameterType.ByteArray, this is a base64 encoding of the byte array.

class Array(value: list[ParameterValue])

An array of parameter values.

class Dict(value: dict[str, ParameterValue])

An associative map of parameter values.

Asset handling

You can provide an optional AssetHandler to start_server() to serve assets such as URDFs for live visualization. The asset handler is a Callable that returns the asset for a given URI, or None if it doesn’t exist.

Foxglove assets will be requested with the package:// scheme. See https://docs.foxglove.dev/docs/visualization/panels/3d#resolution-of-urdf-assets-with-package-urls

This handler will be run on a separate thread; a typical implementation will load the asset from disk and return its contents.

See the Asset Server example for more information.

foxglove.AssetHandler

alias of Callable[[str], bytes | None]

class foxglove.MCAPCompression

Deprecated. Use mcap.MCAPCompression instead.

foxglove.mcap

class foxglove.mcap.MCAPWriteOptions(*, compression=None, profile=None, chunk_size=None, use_chunks=False, emit_statistics=True, emit_summary_offsets=True, emit_message_indexes=True, emit_chunk_indexes=True, repeat_channels=True, repeat_schemas=True, calculate_chunk_crcs=True, calculate_data_section_crc=True, calculate_summary_section_crc=True)

Options for the MCAP writer.

All parameters are optional.

Parameters:

  • compression (MCAPCompression) – Specifies the compression that should be used on chunks. Defaults to Zstd. Pass None to disable compression.

  • profile (str) – Specifies the profile that should be written to the MCAP Header record.

  • chunk_size (int) – Specifies the target uncompressed size of each chunk.

  • use_chunks (bool) – Specifies whether to use chunks for storing messages.

  • emit_statistics (bool) – Specifies whether to write a statistics record in the summary section.

  • emit_summary_offsets (bool) – Specifies whether to write summary offset records.

  • emit_message_indexes (bool) – Specifies whether to write message index records after each chunk.

  • emit_chunk_indexes (bool) – Specifies whether to write chunk index records in the summary section.

  • repeat_channels (bool) – Specifies whether to repeat each channel record from the data section in the summary section.

  • repeat_schemas (bool) – Specifies whether to repeat each schema record from the data section in the summary section.

  • calculate_chunk_crcs (bool) – Specifies whether to calculate and write CRCs for chunk records.

  • calculate_data_section_crc (bool) – Specifies whether to calculate and write a data section CRC into the DataEnd record.

  • calculate_summary_section_crc (bool) – Specifies whether to calculate and write a summary section CRC into the Footer record.

class foxglove.mcap.MCAPWriter

A writer for logging messages to an MCAP file.

Obtain an instance by calling foxglove.open_mcap().

This class may be used as a context manager, in which case the writer will be closed when you exit the context.

If the writer is not closed by the time it is garbage collected, it will be closed automatically, and any errors will be logged.

close()

Close the MCAP writer.

You may call this to explicitly close the writer. Note that the writer will be automatically closed for you when it is garbage collected, or when exiting the context manager.

enum foxglove.mcap.MCAPCompression
Zstd
Lz4

foxglove.websocket

class foxglove.websocket.ChannelView

Information about a channel.

class foxglove.websocket.Client

A client connected to a running websocket server.

id

A client identifier that is unique within the scope of this server.

class foxglove.websocket.ClientChannel

Information about a client channel.

class foxglove.websocket.ConnectionGraph

A connection graph.

set_advertised_service(service, provider_ids)

Set an advertised service and its associated provider ids. Overwrites any existing service with the same name.

Parameters:

  • service – The service name.

  • provider_ids – The set of provider ids.

set_published_topic(topic, publisher_ids)

Set a published topic and its associated publisher ids. Overwrites any existing topic with the same name.

Parameters:

  • topic – The topic name.

  • publisher_ids – The set of publisher ids.

set_subscribed_topic(topic, subscriber_ids)

Set a subscribed topic and its associated subscriber ids. Overwrites any existing topic with the same name.

Parameters:

  • topic – The topic name.

  • subscriber_ids – The set of subscriber ids.

class foxglove.websocket.MessageSchema(*, encoding, schema)

A service request or response schema.

Parameters:

  • encoding (str) – The encoding of the message.

  • schema (foxglove.Schema) – The message schema.

encoding

The encoding of the message.

schema

The message schema.

class foxglove.websocket.Parameter(name, *, value=None, **kwargs)

A parameter which can be sent to a client.

Parameters:

  • name (str) – The parameter name.

  • value (None|bool|float|str|bytes|list|dict|ParameterValue) – Optional value, represented as a native python object, or a ParameterValue.

  • type (ParameterType|None) – Optional parameter type. This is automatically derived when passing a native python object as the value.

get_value()

Returns the parameter value as a native python object.

Return type:

None|bool|float|str|bytes|list|dict

name

The name of the parameter.

type

The parameter type.

value

The parameter value.

class foxglove.websocket.ServerListener(*args, **kwargs)

A mechanism to register callbacks for handling client message events.

on_client_advertise(client, channel)

Called by the server when a client advertises a channel.

Parameters:

  • client (Client) – The client (id) that sent the message.

  • channel (ClientChannel) – The client channel that is being advertised.

Return type:

None

on_client_unadvertise(client, client_channel_id)

Called by the server when a client unadvertises a channel.

Parameters:

  • client (Client) – The client (id) that is unadvertising the channel.

  • client_channel_id (int) – The client channel id that is being unadvertised.

Return type:

None

on_connection_graph_subscribe()

Called by the server when the first client subscribes to the connection graph.

Return type:

None

on_connection_graph_unsubscribe()

Called by the server when the last client unsubscribes from the connection graph.

Return type:

None

on_get_parameters(client, param_names, request_id=None)

Called by the server when a client requests parameters.

Requires Capability.Parameters.

Parameters:

  • client (Client) – The client (id) that sent the message.

  • param_names (List[str]) – The names of the parameters to get.

  • request_id (Optional[str] (default: None)) – An optional request id.

Return type:

List[Parameter]

on_message_data(client, client_channel_id, data)

Called by the server when a message is received from a client.

Parameters:

  • client (Client) – The client (id) that sent the message.

  • client_channel_id (int) – The client channel id that the message was sent on.

  • data (bytes) – The message data.

Return type:

None

on_parameters_subscribe(param_names)

Called by the server when a client subscribes to one or more parameters for the first time.

Requires Capability.Parameters.

Parameters:

param_names (List[str]) – The names of the parameters to subscribe to.

Return type:

None

on_parameters_unsubscribe(param_names)

Called by the server when the last client subscription to one or more parameters has been removed.

Requires Capability.Parameters.

Parameters:

param_names (List[str]) – The names of the parameters to unsubscribe from.

Return type:

None

on_set_parameters(client, parameters, request_id=None)

Called by the server when a client sets parameters. Note that only parameters which have changed are included in the callback, but the return value must include all parameters.

Requires Capability.Parameters.

Parameters:

  • client (Client) – The client (id) that sent the message.

  • parameters (List[Parameter]) – The parameters to set.

  • request_id (Optional[str] (default: None)) – An optional request id.

Return type:

List[Parameter]

on_subscribe(client, channel)

Called by the server when a client subscribes to a channel.

Parameters:

  • client (Client) – The client (id) that sent the message.

  • channel (ChannelView) – The channel (id, topic) that the message was sent on.

Return type:

None

on_unsubscribe(client, channel)

Called by the server when a client unsubscribes from a channel or disconnects.

Parameters:

  • client (Client) – The client (id) that sent the message.

  • channel (ChannelView) – The channel (id, topic) that the message was sent on.

Return type:

None

class foxglove.websocket.Service(name, *, schema, handler)

A websocket service.

The handler must be a callback function which takes the ServiceRequest as its argument, and returns bytes as a response. If the handler raises an exception, the stringified exception message will be returned to the client as an error.

class foxglove.websocket.ServiceRequest

A websocket service request.

call_id

The call ID that uniquely identifies this request for this client.

client_id

The client ID.

encoding

The request encoding.

payload

The request payload.

service_name

The service name.

class foxglove.websocket.ServiceSchema(name, *, request=None, response=None)

A service schema.

Parameters:

  • name (str) – The name of the service.

  • request (MessageSchema | None) – The request schema.

  • response (MessageSchema | None) – The response schema.

name

The name of the service.

request

The request schema.

response

The response schema.

class foxglove.websocket.WebSocketServer

A live visualization server. Obtain an instance by calling foxglove.start_server().

add_services(services)

Advertises support for the provided services.

These services will be available for clients to use until they are removed with remove_services().

This method will fail if the server was not configured with Capability.Services.

Parameters:

services – Services to add.

broadcast_time(timestamp_nanos)

Publishes the current server timestamp to all clients. If the server has been stopped, this has no effect.

Parameters:

timestamp_nanos – The timestamp to broadcast, in nanoseconds.

clear_session(session_id=None)

Sets a new session ID and notifies all clients, causing them to reset their state. If no session ID is provided, generates a new one based on the current timestamp. If the server has been stopped, this has no effect.

Parameters:

session_id (default: None) – An optional session ID.

port

Get the port on which the server is listening.

publish_connection_graph(graph)

Publishes a connection graph update to all subscribed clients. An update is published to clients as a difference from the current graph to the replacement graph. When a client first subscribes to connection graph updates, it receives the current graph.

Parameters:

graph – The connection graph to publish.

publish_parameter_values(parameters)

Publishes parameter values to all subscribed clients.

Parameters:

parameters (list[Parameter]) – The parameters to publish.

publish_status(message, level, id=None)

Send a status message to all clients. If the server has been stopped, this has no effect.

Parameters:

  • message – The message to send.

  • level – The level of the status message.

  • id (default: None) – An optional id for the status message.

remove_services(names)

Removes services that were previously advertised.

Parameters:

names – Names of services to remove.

remove_status(status_ids)

Remove status messages by id from all clients. If the server has been stopped, this has no effect.

Parameters:

status_ids (list[str]) – The ids of the status messages to remove.

stop()

Explicitly stop the server.

Enums

enum foxglove.websocket.Capability

An enumeration of capabilities that you may choose to support for live visualization.

Specify the capabilities you support when calling foxglove.start_server(). These will be advertised to the Foxglove app when connected as a WebSocket client.

ClientPublish

Allow clients to advertise channels to send data messages to the server.

Parameters

Allow clients to get & set parameters.

Services

Allow clients to call services.

Time

Inform clients about the latest server time.

This allows accelerated, slowed, or stepped control over the progress of time. If the server publishes time data, then timestamps of published messages must originate from the same time source.

enum foxglove.websocket.StatusLevel

A level for WebSocketServer.publish_status().

Info
Warning
Error