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

class LogLevel(value: int)

Bases: pybind11_object

Logging levels (as used by SetLogger()).

Members:

kLogCritical

kLogError

kLogWarning

kLogInfo

kLogDebug

kLogDebug1

kLogDebug2

kLogDebug3

kLogDebug4

kLogCritical = <LogLevel.kLogCritical: 50>

kLogDebug = <LogLevel.kLogDebug: 10>

kLogDebug1 = <LogLevel.kLogDebug1: 9>

kLogDebug2 = <LogLevel.kLogDebug2: 8>

kLogDebug3 = <LogLevel.kLogDebug3: 7>

kLogDebug4 = <LogLevel.kLogDebug4: 6>

kLogError = <LogLevel.kLogError: 40>

kLogInfo = <LogLevel.kLogInfo: 20>

kLogWarning = <LogLevel.kLogWarning: 30>

property name

property value

class NetworkMode(value: int)

Bases: pybind11_object

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

Members:

kNetModeNone

kNetModeServer

kNetModeClient3

kNetModeClient4

kNetModeLocal

kNetModeStarting

kNetModeClient3 = <NetworkMode.kNetModeClient3: 2>

kNetModeClient4 = <NetworkMode.kNetModeClient4: 4>

kNetModeLocal = <NetworkMode.kNetModeLocal: 16>

kNetModeNone = <NetworkMode.kNetModeNone: 0>

kNetModeServer = <NetworkMode.kNetModeServer: 1>

kNetModeStarting = <NetworkMode.kNetModeStarting: 8>

property name

property value

addConnectionListener(immediate_notify: bool, callback: 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

addListener(*args, **kwargs)

Overloaded function.

addListener(self: ntcore._ntcore.NetworkTableInstance, topic: ntcore._ntcore.Topic, eventMask: int, listener: 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
eventMask – Bitmask of EventFlags values
listener – Listener function

Returns:

Listener handle

addListener(self: ntcore._ntcore.NetworkTableInstance, subscriber: ntcore._ntcore.Subscriber, eventMask: int, listener: 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
eventMask – Bitmask of EventFlags values
listener – Listener function

Returns:

Listener handle

addListener(self: ntcore._ntcore.NetworkTableInstance, subscriber: ntcore._ntcore.MultiSubscriber, eventMask: int, listener: 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
eventMask – Bitmask of EventFlags values
listener – Listener function

Returns:

Listener handle

addListener(self: ntcore._ntcore.NetworkTableInstance, entry: ntcore._ntcore.NetworkTableEntry, eventMask: int, listener: 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
eventMask – Bitmask of EventFlags values
listener – Listener function

Returns:

Listener handle

addListener(self: ntcore._ntcore.NetworkTableInstance, prefixes: List[str], eventMask: int, listener: 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
eventMask – Bitmask of EventFlags values
listener – Listener function

Returns:

Listener handle

addLogger(minLevel: int, maxLevel: int, func: 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:

minLevel – minimum log level
maxLevel – maximum log level
func – callback function

Returns:

Listener handle

addTimeSyncListener(immediate_notify: bool, callback: 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

configPythonLogging(*, min: ntcore._ntcore.NetworkTableInstance.LogLevel = <LogLevel.kLogInfo: 20>, max: ntcore._ntcore.NetworkTableInstance.LogLevel = <LogLevel.kLogCritical: 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.

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

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

Gets a boolean array topic.

Parameters:: name – topic name
Returns:: Topic

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

Gets a boolean topic.

Parameters:: name – topic name
Returns:: Topic

getConnections() → 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 getDefault() → ntcore._ntcore.NetworkTableInstance

Get global default instance.

Returns:: Global default instance

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

Gets a double array topic.

Parameters:: name – topic name
Returns:: Topic

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

Gets a double topic.

Parameters:: name – topic name
Returns:: Topic

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

Gets the entry for a key.

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

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

Gets a float array topic.

Parameters:: name – topic name
Returns:: Topic

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

Gets a float topic.

Parameters:: name – topic name
Returns:: Topic

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

Gets an integer array topic.

Parameters:: name – topic name
Returns:: Topic

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

Gets an integer topic.

Parameters:: name – topic name
Returns:: Topic

getNetworkMode() → int

Get the current network mode.

Returns:: Bitmask of NetworkMode.

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

Gets a raw topic.

Parameters:: name – topic name
Returns:: Topic

getServerTimeOffset() → 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)

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

Gets a string array topic.

Parameters:: name – topic name
Returns:: Topic

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

Gets a string topic.

Parameters:: name – topic name
Returns:: Topic

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

Gets the table with the specified key.

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

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

Gets a “generic” (untyped) topic.

Parameters:: name – topic name
Returns:: Topic

getTopicInfo(*args, **kwargs)

Overloaded function.

getTopicInfo(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.

getTopicInfo(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.

getTopicInfo(self: ntcore._ntcore.NetworkTableInstance, prefix: str, types: int) -> 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.

getTopicInfo(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.

getTopics(*args, **kwargs)

Overloaded function.

getTopics(self: ntcore._ntcore.NetworkTableInstance) -> List[ntcore._ntcore.Topic]

Get Published Topics.

Returns an array of topics.

Returns:: Array of topics.

getTopics(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.

getTopics(self: ntcore._ntcore.NetworkTableInstance, prefix: str, types: int) -> 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.

getTopics(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.

isConnected() → bool

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

Returns:: True if connected.

kDefaultPort3 = 1735

kDefaultPort4 = 5810

static removeListener(listener: int) → None

Remove a listener.

Parameters:: listener – Listener handle to remove

setServer(*args, **kwargs)

Overloaded function.

setServer(self: ntcore._ntcore.NetworkTableInstance, server_name: str, port: int = 0) -> None

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

Parameters:

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

setServer(self: ntcore._ntcore.NetworkTableInstance, servers: List[Tuple[str, int]]) -> 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

setServer(self: ntcore._ntcore.NetworkTableInstance, servers: List[str], port: int = 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)

setServerTeam(team: int, port: int = 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)

startClient3(identity: str) → None

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

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

startClient4(identity: str) → None

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

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

startConnectionDataLog(log: wpiutil._wpiutil.log.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

startDSClient(port: int = 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)

startEntryDataLog(log: wpiutil._wpiutil.log.DataLog, prefix: str, logPrefix: 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
logPrefix – prefix to add to data log entry names

Returns:

Data logger handle

startLocal() → 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.

startServer(persist_filename: str = 'networktables.json', listen_address: str = '', port3: int = 1735, port4: int = 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 null to listen on any address (UTF-8 string, null terminated)
port3 – port to communicate over (NT3)
port4 – port to communicate over (NT4)

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

static stopConnectionDataLog(logger: int) → None

Stops logging connection changes to a DataLog.

Parameters:: logger – data logger handle

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

static stopEntryDataLog(logger: int) → None

Stops logging entry changes to a DataLog.

Parameters:: logger – data logger handle

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

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

waitForListenerQueue(timeout: float) → 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.