NetworkTableInstance

class ntcore.NetworkTableInstance

Bases: pybind11_object

NetworkTables Instance.

Instances are completely independent from each other. Table operations on one instance will not be visible to other instances unless the instances are connected via the network. The main limitation on instances is that you cannot have two servers on the same network port. The main utility of instances is for unit testing, but they can also enable one program to connect to two different NetworkTables networks.

The global “default” instance (as returned by GetDefault()) is always available, and is intended for the common case when there is only a single NetworkTables instance being used in the program. The default instance cannot be destroyed.

Additional instances can be created with the Create() function. Instances are not reference counted or RAII. Instead, they must be explicitly destroyed (with Destroy()).

@ingroup ntcore_cpp_api

DEFAULT_PORT = 5810

class LogLevel(value: SupportsInt | SupportsIndex)

Bases: pybind11_object

Logging levels (as used by SetLogger()).

Members:

CRITICAL

ERROR

WARNING

INFO

DEBUG

DEBUG_1

DEBUG_2

DEBUG_3

DEBUG_4

CRITICAL = <LogLevel.CRITICAL: 50>

DEBUG = <LogLevel.DEBUG: 10>

DEBUG_1 = <LogLevel.DEBUG_1: 9>

DEBUG_2 = <LogLevel.DEBUG_2: 8>

DEBUG_3 = <LogLevel.DEBUG_3: 7>

DEBUG_4 = <LogLevel.DEBUG_4: 6>

ERROR = <LogLevel.ERROR: 40>

INFO = <LogLevel.INFO: 20>

WARNING = <LogLevel.WARNING: 30>

NetworkTableInstance.LogLevel.name -> str

property value

class NetworkMode(value: SupportsInt | SupportsIndex)

Bases: pybind11_object

Client/server mode flag values (as returned by GetNetworkMode()). This is a bitmask.

Members:

NONE

SERVER

CLIENT

LOCAL

STARTING

CLIENT = <NetworkMode.CLIENT: 4>

LOCAL = <NetworkMode.LOCAL: 16>

NONE = <NetworkMode.NONE: 0>

SERVER = <NetworkMode.SERVER: 1>

STARTING = <NetworkMode.STARTING: 8>

NetworkTableInstance.NetworkMode.name -> str

property value

add_connection_listener(immediate_notify: bool, callback: collections.abc.Callable[[ntcore._ntcore.Event], None]) → int

Add a connection listener. The callback function is called asynchronously on a separate thread, so it’s important to use synchronization or atomics when accessing any shared state from the callback function.

Parameters:

immediate_notify – notify listener of all existing connections
callback – listener to add

Returns:

Listener handle

add_listener(*args, **kwargs)

Overloaded function.

add_listener(self: ntcore._ntcore.NetworkTableInstance, topic: ntcore._ntcore.Topic, event_mask: typing.SupportsInt | typing.SupportsIndex, listener: collections.abc.Callable[[ntcore._ntcore.Event], None]) -> int

Add a listener for changes on a particular topic. The callback function is called asynchronously on a separate thread, so it’s important to use synchronization or atomics when accessing any shared state from the callback function.

This creates a corresponding internal subscriber with the lifetime of the listener.

Parameters:

topic – Topic
event_mask – Bitmask of EventFlags values
listener – Listener function

Returns:

Listener handle

add_listener(self: ntcore._ntcore.NetworkTableInstance, subscriber: ntcore._ntcore.Subscriber, event_mask: typing.SupportsInt | typing.SupportsIndex, listener: collections.abc.Callable[[ntcore._ntcore.Event], None]) -> int

Add a listener for changes on a subscriber. The callback function is called asynchronously on a separate thread, so it’s important to use synchronization or atomics when accessing any shared state from the callback function. This does NOT keep the subscriber active.

Parameters:

subscriber – Subscriber
event_mask – Bitmask of EventFlags values
listener – Listener function

Returns:

Listener handle

add_listener(self: ntcore._ntcore.NetworkTableInstance, subscriber: ntcore._ntcore.MultiSubscriber, event_mask: typing.SupportsInt | typing.SupportsIndex, listener: collections.abc.Callable[[ntcore._ntcore.Event], None]) -> int

Add a listener for changes on a subscriber. The callback function is called asynchronously on a separate thread, so it’s important to use synchronization or atomics when accessing any shared state from the callback function. This does NOT keep the subscriber active.

Parameters:

subscriber – Subscriber
event_mask – Bitmask of EventFlags values
listener – Listener function

Returns:

Listener handle

add_listener(self: ntcore._ntcore.NetworkTableInstance, entry: ntcore._ntcore.NetworkTableEntry, event_mask: typing.SupportsInt | typing.SupportsIndex, listener: collections.abc.Callable[[ntcore._ntcore.Event], None]) -> int

Add a listener for changes on an entry. The callback function is called asynchronously on a separate thread, so it’s important to use synchronization or atomics when accessing any shared state from the callback function.

Parameters:

entry – Entry
event_mask – Bitmask of EventFlags values
listener – Listener function

Returns:

Listener handle

add_listener(self: ntcore._ntcore.NetworkTableInstance, prefixes: List[str], event_mask: typing.SupportsInt | typing.SupportsIndex, listener: collections.abc.Callable[[ntcore._ntcore.Event], None]) -> int

Add a listener for changes to topics with names that start with any of the given prefixes. The callback function is called asynchronously on a separate thread, so it’s important to use synchronization or atomics when accessing any shared state from the callback function.

This creates a corresponding internal subscriber with the lifetime of the listener.

Parameters:

prefixes – Topic name string prefixes
event_mask – Bitmask of EventFlags values
listener – Listener function

Returns:

Listener handle

add_logger(min_level: SupportsInt | SupportsIndex, max_level: SupportsInt | SupportsIndex, func: collections.abc.Callable[[ntcore._ntcore.Event], None]) → int

Add logger callback function. By default, log messages are sent to stderr; this function sends log messages with the specified levels to the provided callback function instead. The callback function will only be called for log messages with level greater than or equal to minLevel and less than or equal to maxLevel; messages outside this range will be silently ignored.

Parameters:

min_level – minimum log level
max_level – maximum log level
func – callback function

Returns:

Listener handle

add_schema(*args, **kwargs)

Overloaded function.

add_schema(self: ntcore._ntcore.NetworkTableInstance, name: str, type: str, schema: Buffer) -> None

Registers a data schema. Data schemas provide information for how a certain data type string can be decoded. The type string of a data schema indicates the type of the schema itself (e.g. “protobuf” for protobuf schemas, “struct” for struct schemas, etc). In NetworkTables, schemas are published just like normal topics, with the name being generated from the provided name: “/.schema/<name>”. Duplicate calls to this function with the same name are silently ignored.

Parameters:

name – Name (the string passed as the data type for topics using this schema)
type – Type of schema (e.g. “protobuf”, “struct”, etc)
schema – Schema data

add_schema(self: ntcore._ntcore.NetworkTableInstance, name: str, type: str, schema: str) -> None

Registers a data schema. Data schemas provide information for how a certain data type string can be decoded. The type string of a data schema indicates the type of the schema itself (e.g. “protobuf” for protobuf schemas, “struct” for struct schemas, etc). In NetworkTables, schemas are published just like normal topics, with the name being generated from the provided name: “/.schema/<name>”. Duplicate calls to this function with the same name are silently ignored.

Parameters:

name – Name (the string passed as the data type for topics using this schema)
type – Type of schema (e.g. “protobuf”, “struct”, etc)
schema – Schema data

add_time_sync_listener(immediate_notify: bool, callback: collections.abc.Callable[[ntcore._ntcore.Event], None]) → int

Add a time synchronization listener. The callback function is called asynchronously on a separate thread, so it’s important to use synchronization or atomics when accessing any shared state from the callback function.

Parameters:

immediate_notify – notify listener of current time synchronization value
callback – listener to add

Returns:

Listener handle

config_python_logging(*, min: ntcore._ntcore.NetworkTableInstance.LogLevel = <LogLevel.INFO: 20>, max: ntcore._ntcore.NetworkTableInstance.LogLevel = <LogLevel.CRITICAL: 50>, name: str = 'nt') → None

Configure python logging for this instance.

Parameters:

min – Minimum NT level to log
max – Maximum NT level to log
name – Name of python logger

Note

This must be called before the instance is started

static create() → ntcore._ntcore.NetworkTableInstance

Create an instance.

Returns:: Newly created instance

static destroy(inst: ntcore._ntcore.NetworkTableInstance) → None

Destroys an instance (note: this has global effect).

Parameters:: inst – Instance

disconnect() → None: Disconnects the client if it’s running and connected. This will automatically start reconnection attempts to the current server list.

flush() → None: Flushes all updated values immediately to the network. .. note:: This is rate-limited to protect the network from flooding.

This is primarily useful for synchronizing network updates with user code.

flush_local() → None: Flushes all updated values immediately to the local client/server. This does not flush to the network.

get_boolean_array_topic(name: str) → ntcore._ntcore.BooleanArrayTopic

Gets a boolean array topic.

Parameters:: name – topic name
Returns:: Topic

get_boolean_topic(name: str) → ntcore._ntcore.BooleanTopic

Gets a boolean topic.

Parameters:: name – topic name
Returns:: Topic

get_connections() → list[ntcore._ntcore.ConnectionInfo]

Get information on the currently established network connections. If operating as a client, this will return either zero or one values.

Returns:: array of connection information

static get_default() → ntcore._ntcore.NetworkTableInstance

Get global default instance.

Returns:: Global default instance

get_double_array_topic(name: str) → ntcore._ntcore.DoubleArrayTopic

Gets a double array topic.

Parameters:: name – topic name
Returns:: Topic

get_double_topic(name: str) → ntcore._ntcore.DoubleTopic

Gets a double topic.

Parameters:: name – topic name
Returns:: Topic

get_entry(name: str) → ntcore._ntcore.NetworkTableEntry

Gets the entry for a key.

Parameters:: name – Key
Returns:: Network table entry.

get_float_array_topic(name: str) → ntcore._ntcore.FloatArrayTopic

Gets a float array topic.

Parameters:: name – topic name
Returns:: Topic

get_float_topic(name: str) → ntcore._ntcore.FloatTopic

Gets a float topic.

Parameters:: name – topic name
Returns:: Topic

get_integer_array_topic(name: str) → ntcore._ntcore.IntegerArrayTopic

Gets an integer array topic.

Parameters:: name – topic name
Returns:: Topic

get_integer_topic(name: str) → ntcore._ntcore.IntegerTopic

Gets an integer topic.

Parameters:: name – topic name
Returns:: Topic

get_network_mode() → int

Get the current network mode.

Returns:: Bitmask of NetworkMode.

get_raw_topic(name: str) → ntcore._ntcore.RawTopic

Gets a raw topic.

Parameters:: name – topic name
Returns:: Topic

get_server_time_offset() → int | None

Get the time offset between server time and local time. Add this value to local time to get the estimated equivalent server time. In server mode, this always returns 0. In client mode, this returns the time offset only if the client and server are connected and have exchanged synchronization messages. Note the time offset may change over time as it is periodically updated; to receive updates as events, add a listener to the “time sync” event.

Returns:: Time offset in microseconds (optional)

get_string_array_topic(name: str) → ntcore._ntcore.StringArrayTopic

Gets a string array topic.

Parameters:: name – topic name
Returns:: Topic

get_string_topic(name: str) → ntcore._ntcore.StringTopic

Gets a string topic.

Parameters:: name – topic name
Returns:: Topic

get_struct_array_topic(name: str, type: type) → ntcore._ntcore.StructArrayTopic

Gets a raw struct serialized array topic.

Parameters:

name – topic name
type – optional struct type info

Returns:

Topic

get_struct_topic(name: str, type: type) → ntcore._ntcore.StructTopic

Gets a raw struct serialized value topic.

Parameters:

name – topic name
type – optional struct type info

Returns:

Topic

get_table(key: str) → ntcore._ntcore.NetworkTable

Gets the table with the specified key.

Parameters:: key – the key name
Returns:: The network table

get_topic(name: str) → ntcore._ntcore.Topic

Gets a “generic” (untyped) topic.

Parameters:: name – topic name
Returns:: Topic

get_topic_info(*args, **kwargs)

Overloaded function.

get_topic_info(self: ntcore._ntcore.NetworkTableInstance) -> list[ntcore._ntcore.TopicInfo]

Get Topic Information about multiple topics.

Returns an array of topic information (handle, name, type, and properties).

Returns:: Array of topic information.

get_topic_info(self: ntcore._ntcore.NetworkTableInstance, prefix: str) -> list[ntcore._ntcore.TopicInfo]

Get Topic Information about multiple topics.

Returns an array of topic information (handle, name, type, and properties). The results are filtered by string prefix to only return a subset of all topics.

Parameters:: prefix – name required prefix; only topics whose name starts with this string are returned
Returns:: Array of topic information.

get_topic_info(self: ntcore._ntcore.NetworkTableInstance, prefix: str, types: typing.SupportsInt | typing.SupportsIndex) -> list[ntcore._ntcore.TopicInfo]

Get Topic Information about multiple topics.

Returns an array of topic information (handle, name, type, and properties). The results are filtered by string prefix and type to only return a subset of all topics.

Parameters:

prefix – name required prefix; only topics whose name starts with this string are returned
types – bitmask of NT_Type values; 0 is treated specially as a “don’t care”

Returns:

Array of topic information.

get_topic_info(self: ntcore._ntcore.NetworkTableInstance, prefix: str, types: List[str]) -> list[ntcore._ntcore.TopicInfo]

Get Topic Information about multiple topics.

Returns an array of topic information (handle, name, type, and properties). The results are filtered by string prefix and type to only return a subset of all topics.

Parameters:

prefix – name required prefix; only topics whose name starts with this string are returned
types – array of type strings

Returns:

Array of topic information.

get_topics(*args, **kwargs)

Overloaded function.

get_topics(self: ntcore._ntcore.NetworkTableInstance) -> list[ntcore._ntcore.Topic]

Get Published Topics.

Returns an array of topics.

Returns:: Array of topics.

get_topics(self: ntcore._ntcore.NetworkTableInstance, prefix: str) -> list[ntcore._ntcore.Topic]

Get Published Topics.

Returns an array of topics. The results are filtered by string prefix to only return a subset of all topics.

Parameters:: prefix – name required prefix; only topics whose name starts with this string are returned
Returns:: Array of topics.

get_topics(self: ntcore._ntcore.NetworkTableInstance, prefix: str, types: typing.SupportsInt | typing.SupportsIndex) -> list[ntcore._ntcore.Topic]

Get Published Topics.

Returns an array of topics. The results are filtered by string prefix and type to only return a subset of all topics.

Parameters:

prefix – name required prefix; only topics whose name starts with this string are returned
types – bitmask of NT_Type values; 0 is treated specially as a “don’t care”

Returns:

Array of topics.

get_topics(self: ntcore._ntcore.NetworkTableInstance, prefix: str, types: List[str]) -> list[ntcore._ntcore.Topic]

Get Published Topics.

Returns an array of topics. The results are filtered by string prefix and type to only return a subset of all topics.

Parameters:

prefix – name required prefix; only topics whose name starts with this string are returned
types – array of type strings

Returns:

Array of topic handles.

has_schema(name: str) → bool

Returns whether there is a data schema already registered with the given name. This does NOT perform a check as to whether the schema has already been published by another node on the network.

Parameters:: name – Name (the string passed as the data type for topics using this schema)
Returns:: True if schema already registered

is_connected() → bool

Return whether or not the instance is connected to another node.

Returns:: True if connected.

static remove_listener(listener: SupportsInt | SupportsIndex) → None

Remove a listener.

Parameters:: listener – Listener handle to remove

set_server(*args, **kwargs)

Overloaded function.

set_server(self: ntcore._ntcore.NetworkTableInstance, server_name: str, port: typing.SupportsInt | typing.SupportsIndex = 0) -> None

Sets server address and port for client (without restarting client).

Parameters:

server_name – server name (UTF-8 string)
port – port to communicate over (0 = default)

set_server(self: ntcore._ntcore.NetworkTableInstance, servers: List[tuple[str, typing.SupportsInt | typing.SupportsIndex]]) -> None

Sets server addresses and ports for client (without restarting client). The client will attempt to connect to each server in round robin fashion.

Parameters:: servers – array of server address and port pairs

set_server(self: ntcore._ntcore.NetworkTableInstance, servers: List[str], port: typing.SupportsInt | typing.SupportsIndex = 0) -> None

Sets server addresses and port for client (without restarting client). The client will attempt to connect to each server in round robin fashion.

Parameters:

servers – array of server names
port – port to communicate over (0 = default)

set_server_team(team: SupportsInt | SupportsIndex, port: SupportsInt | SupportsIndex = 0) → None

Sets server addresses and port for client (without restarting client). Connects using commonly known robot addresses for the specified team.

Parameters:

team – team number
port – port to communicate over (0 = default)

start_client(identity: str) → None

Starts a client. Use SetServer or SetServerTeam to set the server name and port.

Parameters:: identity – network identity to advertise (cannot be empty string)

start_connection_data_log(log: wpilog._wpilog.DataLog, name: str) → int

Starts logging connection changes to a DataLog.

Parameters:

log – data log object; lifetime must extend until StopConnectionDataLog is called or the instance is destroyed
name – data log entry name

Returns:

Data logger handle

start_ds_client(port: SupportsInt | SupportsIndex = 0) → None

Starts requesting server address from Driver Station. This connects to the Driver Station running on localhost to obtain the server IP address.

Parameters:: port – server port to use in combination with IP from DS (0 = default)

start_entry_data_log(log: wpilog._wpilog.DataLog, prefix: str, log_prefix: str) → int

Starts logging entry changes to a DataLog.

Parameters:

log – data log object; lifetime must extend until StopEntryDataLog is called or the instance is destroyed
prefix – only store entries with names that start with this prefix; the prefix is not included in the data log entry name
log_prefix – prefix to add to data log entry names

Returns:

Data logger handle

start_local() → None: Starts local-only operation. Prevents calls to StartServer or StartClient from taking effect. Has no effect if StartServer or StartClient has already been called.

start_server(persist_filename: str = 'networktables.json', listen_address: str = '', mdns_service: str = '', port: SupportsInt | SupportsIndex = 5810) → None

Starts a server using the specified filename, listening address, and port.

Parameters:

persist_filename – the name of the persist file to use (UTF-8 string, null terminated)
listen_address – the address to listen on, or an empty string to listen on any address. (UTF-8 string, null terminated)
mdns_service – the mDNS service name to announce, or an empty string to not announce via mDNS (UTF-8 string, null terminated)
port – port to communicate over

stop_client() → None: Stops the client if it is running.

static stop_connection_data_log(logger: SupportsInt | SupportsIndex) → None

Stops logging connection changes to a DataLog.

Parameters:: logger – data logger handle

stop_ds_client() → None: Stops requesting server address from Driver Station.

static stop_entry_data_log(logger: SupportsInt | SupportsIndex) → None

Stops logging entry changes to a DataLog.

Parameters:: logger – data logger handle

stop_local() → None: Stops local-only operation. StartServer or StartClient can be called after this call to start a server or client.

stop_server() → None: Stops the server if it is running.

wait_for_listener_queue(timeout: SupportsFloat | SupportsIndex) → bool

Wait for the listener queue to be empty. This is primarily useful for deterministic testing. This blocks until either the listener queue is empty (e.g. there are no more events that need to be passed along to callbacks or poll queues) or the timeout expires.

Parameters:: timeout – timeout, in seconds. Set to 0 for non-blocking behavior, or a negative value to block indefinitely
Returns:: False if timed out, otherwise true.