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
- addSchema(*args, **kwargs)
Overloaded function.
addSchema(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
addSchema(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
- 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
- getStructArrayTopic(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
- getStructTopic(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
- 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.
- hasSchema(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
- 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.