API Reference¶
NetworkTables API¶
-
class
networktables.
NetworkTablesInstance
[source]¶ The object
networktables.NetworkTables
is a global singleton that you can use to initialize NetworkTables connections, configure global settings and listeners, and to create table objects which can be used to send data to/from NetworkTable servers and clients.First, you must initialize NetworkTables:
from networktables import NetworkTables # As a client to connect to a robot NetworkTables.initialize(server='roborio-XXX-frc.local')
Then, to interact with the SmartDashboard you get an instance of the table, and you can call the various methods:
sd = NetworkTables.getTable('SmartDashboard') sd.putNumber('someNumber', 1234) otherNumber = sd.getNumber('otherNumber')
You can create additional NetworkTablesInstance objects. 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
NetworkTablesInstance.getDefault()
) is always available, and is intended for the common case when there is only a single NetworkTables instance being used in the program.Additional instances can be created with the
create()
function.See also
The examples in the documentation.
-
DEFAULT_PORT
= 1735¶ The default port that network tables operates on
-
class
EntryFlags
[source]¶ NetworkTables entry flags
-
PERSISTENT
= 1¶ Indicates a value that will be persisted on the server
-
-
class
EntryTypes
[source]¶ NetworkTable value types used in
NetworkTable.getKeys()
-
BOOLEAN
= b'\x01'¶ True or False
-
BOOLEAN_ARRAY
= b'\x10'¶ List of booleans
-
DOUBLE
= b'\x02'¶ Floating point number
-
DOUBLE_ARRAY
= b' '¶ List of numbers
-
RAW
= b'\x08'¶ Raw bytes
-
STRING
= b'\x04'¶ Strings
-
STRING_ARRAY
= b'@'¶ List of strings
-
-
class
NetworkModes
[source]¶ Bitflags returend from
getNetworkMode()
-
CLIENT
= 2¶ Running in client mode
-
FAILURE
= 8¶ Flag for failure (either client or server)
-
NONE
= 0¶ Not running
-
SERVER
= 1¶ Running in server mode
-
STARTING
= 4¶ Flag for starting (either client or server)
-
TEST
= 16¶ Flag indicating in test mode
-
-
class
NotifyFlags
[source]¶ Bitflags passed to entry callbacks
-
DELETE
= 8¶ Key deleted
-
FLAGS
= 32¶ Flags changed
-
IMMEDIATE
= 1¶ Initial listener addition
-
LOCAL
= 2¶ Changed locally
-
NEW
= 4¶ Newly created entry
-
UPDATE
= 16¶ Value changed
-
-
PATH_SEPARATOR
= '/'¶ The path separator for sub-tables and keys
-
addConnectionListener
(listener, immediateNotify=False)[source]¶ Adds a listener that will be notified when a new connection to a NetworkTables client/server is established.
The listener is called from a NetworkTables owned thread and should return as quickly as possible.
- Parameters
listener (fn(bool, ConnectionInfo)) – A function that will be called with two parameters
immediateNotify (
bool
) – If True, the listener will be called immediately with any active connection information
Warning
You may call the NetworkTables API from within the listener, but it is not recommended.
Changed in version 2017.0.0: The listener is now a function
-
addEntryListener
(listener, immediateNotify=True, localNotify=True, paramIsNew=True)[source]¶ Adds a listener that will be notified when any key in any NetworkTable is changed. The keys that are received using this listener will be full NetworkTable keys. Most users will not want to use this listener type.
The listener is called from the NetworkTables I/O thread, and should return as quickly as possible.
- Parameters
listener (
Callable
[[str
,Any
,int
],None
]) – A callable that has this signature: callable(key, value, isNew)immediateNotify (
bool
) – If True, the listener will be called immediately with the current values of the tablelocalNotify (
bool
) – True if you wish to be notified of changes made locally (default is True)paramIsNew (
bool
) – If True, the listener third parameter is a boolean set to True if the listener is being called because of a new value in the table. Otherwise, the parameter is an integer of the raw NT_NOTIFY_* flags
New in version 2015.2.0.
Changed in version 2017.0.0: paramIsNew parameter added
Changed in version 2018.0.0: Renamed to addEntryListener, no longer initializes NetworkTables
Warning
You may call the NetworkTables API from within the listener, but it is not recommended as we are not currently sure if deadlocks will occur
- Return type
None
-
addEntryListenerEx
(listener, flags, paramIsNew=True)[source]¶ Adds a listener that will be notified when any key in any NetworkTable is changed. The keys that are received using this listener will be full NetworkTable keys. Most users will not want to use this listener type.
The listener is called from the NetworkTables I/O thread, and should return as quickly as possible.
- Parameters
listener (
Callable
[[str
,Any
,int
],None
]) – A callable that has this signature: callable(key, value, isNew)flags (
NotifyFlags
) – Bitmask of flags that indicate the types of notifications you wish to receiveparamIsNew (
bool
) – If True, the listener third parameter is a boolean set to True if the listener is being called because of a new value in the table. Otherwise, the parameter is an integer of the raw NT_NOTIFY_* flags
New in version 2017.0.0.
Changed in version 2018.0.0: Renamed to addEntryListenerEx, no longer initializes NetworkTables
- Return type
None
-
classmethod
create
()[source]¶ Create an instance.
- Return type
NetworkTablesInstance
- Returns
Newly created instance
-
deleteAllEntries
()[source]¶ Deletes ALL keys in ALL subtables (except persistent values). Use with caution!
New in version 2018.0.0.
- Return type
None
-
enableVerboseLogging
()[source]¶ Enable verbose logging that can be useful when trying to diagnose NetworkTables issues.
Warning
Don’t enable this in normal use, as it can potentially cause performance issues due to the volume of logging.
New in version 2017.0.0.
- Return type
None
-
flush
()[source]¶ 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.
New in version 2017.0.0.
- Return type
None
-
getConnections
()[source]¶ Gets information on the currently established network connections. If operating as a client, this will return either zero or one values.
- Returns
list of connection information
- Return type
list
New in version 2018.0.0.
-
getEntries
(prefix, types=0)[source]¶ Get entries starting with the given prefix. The results are optionally filtered by string prefix and entry type to only return a subset of all entries.
- Parameters
prefix (
str
) – entry name required prefix; only entries whose name starts with this string are returnedtypes (
int
) – bitmask of types; 0 is treated as a “don’t care”
- Returns
List of matching entries.
- Return type
list of
NetworkTableEntry
New in version 2018.0.0.
-
getEntry
(name)[source]¶ Gets the entry for a key.
- Parameters
name (
str
) – Absolute path of key- Return type
NetworkTableEntry
- Returns
Network table entry.
New in version 2018.0.0.
-
getEntryInfo
(prefix, types=0)[source]¶ Get information about entries starting with the given prefix. The results are optionally filtered by string prefix and entry type to only return a subset of all entries.
- Parameters
prefix (
str
) – entry name required prefix; only entries whose name starts with this string are returnedtypes (
int
) – bitmask of types; 0 is treated as a “don’t care”
- Return type
Sequence
- Returns
List of entry information.
New in version 2018.0.0.
-
getGlobalAutoUpdateValue
(key, defaultValue, writeDefault)[source]¶ Global version of getAutoUpdateValue.
- Parameters
key (
str
) – the full NT path of the value (must start with /)defaultValue – The default value to return if the key doesn’t exist
writeDefault (
bool
) – If True, force the value to the specified default
- Return type
See also
ntproperty()
is a read-write alternative to thisNew in version 2015.3.0.
Changed in version 2018.0.0: This now returns the same as
NetworkTablesInstance.getEntry()
-
getGlobalTable
()[source]¶ Returns an object that allows you to write values to absolute NetworkTable keys (which are paths with / separators).
Note
This is now an alias for
NetworkTables.getTable('/')
New in version 2015.2.0.
Changed in version 2017.0.0: Returns a NetworkTable instance
Changed in version 2018.0.0: No longer automatically initializes network tables
- Return type
NetworkTable
-
getRemoteAddress
()[source]¶ Only returns a valid address if connected to the server. If this is a server, returns None
- Return type
Optional
[str
]- Returns
IP address of server or None
New in version 2015.3.2.
-
getTable
(key)[source]¶ Gets the table with the specified key.
- Parameters
key (
str
) – the key name- Return type
NetworkTable
- Returns
the network table requested
Changed in version 2018.0.0: No longer automatically initializes network tables
-
initialize
(server=None)[source]¶ Initializes NetworkTables and begins operations
- Parameters
server (str) –
If specified, NetworkTables will be set to client mode and attempt to connect to the specified server. This is equivalent to executing:
self.startClient(server)
- Returns
True if initialized, False if already initialized
New in version 2017.0.0: The server parameter
-
isConnected
()[source]¶ - Return type
bool
- Returns
True if connected to at least one other NetworkTables instance
-
loadEntries
(filename, prefix)[source]¶ Load table values from a file. The file format used is identical to that used for SavePersistent / LoadPersistent.
- Parameters
filename (
str
) – filenameprefix (
str
) – load only keys starting with this prefix
- Returns
None if success, or a string describing the error on failure
New in version 2018.0.0.
-
loadPersistent
(filename)[source]¶ Loads persistent keys from a file. WPILib will do this automatically on a robot server.
- Parameters
filename (
str
) – Name of file to load keys from- Returns
None if success, or a string describing the error on failure
New in version 2017.0.0.
-
removeConnectionListener
(listener)[source]¶ Removes a connection listener
- Parameters
listener (
Callable
) – The function registered for connection notifications
-
removeEntryListener
(listener)[source]¶ Remove an entry listener.
- Parameters
listener (
Callable
[[str
,Any
,int
],None
]) – Listener to remove
New in version 2018.0.0.
- Return type
None
-
saveEntries
(filename, prefix)[source]¶ Save table values to a file. The file format used is identical to that used for SavePersistent.
- Parameters
filename (
str
) – filenameprefix (
str
) – save only keys starting with this prefix
- Returns
None if success, or a string describing the error on failure
New in version 2018.0.0.
-
savePersistent
(filename)[source]¶ Saves persistent keys to a file. The server does this automatically.
- Parameters
filename (
str
) – Name of file to save keys to- Returns
None if success, or a string describing the error on failure
New in version 2017.0.0.
-
setDashboardMode
(port=1735)¶ Starts requesting server address from Driver Station. This connects to the Driver Station running on localhost to obtain the server IP address.
- Parameters
port (
int
) – server port to use in combination with IP from DS
New in version 2018.0.0: Was formerly called setDashboardMode
- Return type
None
-
setNetworkIdentity
(name)[source]¶ Sets the network identity of this node. This is the name used in the initial connection handshake, and is provided in the connection info on the remote end.
- Parameters
name (
str
) – A string to communicate to other NetworkTables instances
New in version 2017.0.0.
- Return type
None
-
setServer
(server_or_servers)[source]¶ Sets server addresses and port for client (without restarting client). The client will attempt to connect to each server in round robin fashion.
- Parameters
server_or_servers (
Union
[str
,Tuple
[str
,int
],List
[Tuple
[str
,int
]],List
[str
]]) – a string, a tuple of (server, port), array of (server, port), or an array of strings
New in version 2018.0.0.
- Return type
None
-
setServerTeam
(team, port=1735)[source]¶ Sets server addresses and port for client based on the team number (without restarting client). The client will attempt to connect to each server in round robin fashion.
- Parameters
team (
int
) – Team numberport (
int
) – Port to communicate over
New in version 2018.0.0.
- Return type
None
-
setUpdateRate
(interval)[source]¶ Sets the period of time between writes to the network.
WPILib’s networktables and SmartDashboard default to 100ms, we have set it to 50ms instead for quicker response time. You should not set this value too low, as it could potentially increase the volume of data sent over the network.
- Parameters
interval (
float
) – Write flush period in seconds (default is 0.050, or 50ms)
Warning
If you don’t know what this setting affects, don’t mess with it!
New in version 2017.0.0.
- Return type
None
-
shutdown
()[source]¶ Stops all NetworkTables activities and unregisters all tables and callbacks. You can call
initialize()
again after calling this.New in version 2017.0.0.
- Return type
None
-
startClient
(server_or_servers)[source]¶ Sets server addresses and port for client (without restarting client). The client will attempt to connect to each server in round robin fashion.
- Parameters
server_or_servers (
Union
[str
,Tuple
[str
,int
],List
[Tuple
[str
,int
]],List
[str
]]) – a string, a tuple of (server, port), array of (server, port), or an array of strings
New in version 2018.0.0.
-
startClientTeam
(team, port=1735)[source]¶ Starts a client using commonly known robot addresses for the specified team.
- Parameters
team (
int
) – team numberport (
int
) – port to communicate over
New in version 2018.0.0.
-
startDSClient
(port=1735)[source]¶ Starts requesting server address from Driver Station. This connects to the Driver Station running on localhost to obtain the server IP address.
- Parameters
port (
int
) – server port to use in combination with IP from DS
New in version 2018.0.0: Was formerly called setDashboardMode
- Return type
None
-
startServer
(persistFilename='networktables.ini', listenAddress='', port=1735)[source]¶ Starts a server using the specified filename, listening address, and port.
- Parameters
persistFilename (
str
) – the name of the persist file to uselistenAddress (
str
) – the address to listen on, or empty to listen on any addressport (
int
) – port to communicate over
New in version 2018.0.0.
-
startTestMode
(server=True)[source]¶ Setup network tables to run in unit test mode, and enables verbose logging.
- Returns
True if successful
New in version 2018.0.0.
-
waitForConnectionListenerQueue
(timeout)[source]¶ Wait for the connection listener queue to be empty. This is primarily useful for deterministic testing. This blocks until either the connection 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 (
float
) – timeout, in seconds. Set to 0 for non-blocking behavior, or a negative value to block indefinitely- Return type
bool
- Returns
False if timed out, otherwise true.
New in version 2018.0.0.
-
waitForEntryListenerQueue
(timeout)[source]¶ Wait for the entry listener queue to be empty. This is primarily useful for deterministic testing. This blocks until either the entry 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.
Warning
This function is not efficient, so only use it for testing!
- Parameters
timeout (
float
) – timeout, in seconds. Set to 0 for non-blocking behavior, or None to block indefinitely- Return type
bool
- Returns
False if timed out, otherwise true.
NetworkTable Objects¶
-
class
networktables.
NetworkTable
(path, api, inst)[source]¶ This is a NetworkTable object, it allows you to interact with NetworkTables in a table-based manner. You should not directly create a NetworkTable object, but instead use
NetworkTables.getTable()
to retrieve a NetworkTable instance.For example, to interact with the SmartDashboard:
from networktables import NetworkTables sd = NetworkTables.getTable('SmartDashboard') someNumberEntry = sd.getEntry('someNumber') someNumberEntry.putNumber(1234) ...
See also
The examples in the documentation.
-
PATH_SEPARATOR
= '/'¶
-
addEntryListener
(listener, immediateNotify=False, key=None, localNotify=False)[source]¶ Adds a listener that will be notified when any key in this NetworkTable is changed, or when a specified key changes.
The listener is called from the NetworkTables I/O thread, and should return as quickly as possible.
- Parameters
listener (
Callable
) – A callable with signature callable(source, key, value, isNew)immediateNotify (
bool
) – If True, the listener will be called immediately with the current values of the tablekey (
Optional
[str
]) – If specified, the listener will only be called when this key is changedlocalNotify (
bool
) – True if you wish to be notified of changes made locally (default is False)
Warning
You may call the NetworkTables API from within the listener, but it is not recommended
Changed in version 2017.0.0: Added localNotify parameter (defaults to False, which is different from NT2)
- Return type
None
-
addEntryListenerEx
(listener, flags, key=None, paramIsNew=True)[source]¶ Adds a listener that will be notified when any key in this NetworkTable is changed, or when a specified key changes.
The listener is called from the NetworkTables I/O thread, and should return as quickly as possible.
- Parameters
listener (
Callable
) – A callable with signature callable(source, key, value, param)flags (
NotifyFlags
) – Bitmask of flags that indicate the types of notifications you wish to receivekey (
Optional
[str
]) – If specified, the listener will only be called when this key is changedparamIsNew (
bool
) – If True, the listener fourth parameter is a boolean set to True if the listener is being called because of a new value in the table. Otherwise, the parameter is an integer of the raw NT_NOTIFY_* flags
Warning
You may call the NetworkTables API from within the listener, but it is not recommended
New in version 2017.0.0.
- Return type
None
-
addSubTableListener
(listener, localNotify=False)[source]¶ Adds a listener that will be notified when any key in a subtable of this NetworkTable is changed.
The listener is called from the NetworkTables I/O thread, and should return as quickly as possible.
- Parameters
listener (
Callable
) – Callable to call when previously unseen table appears. Function signature is callable(source, key, subtable, True)localNotify (
bool
) – True if you wish to be notified when local changes result in a new table
Warning
You may call the NetworkTables API from within the listener, but it is not recommended as we are not currently sure if deadlocks will occur
Changed in version 2017.0.0: Added localNotify parameter
- Return type
None
-
clearFlags
(key, flags)[source]¶ Clears entry flags on the specified key in this table.
- Parameters
key (
str
) – the key nameflags (
EntryFlags
) – the flags to clear (bitmask)
New in version 2017.0.0.
- Return type
None
-
clearPersistent
(key)[source]¶ Stop making a key’s value persistent through program restarts.
- Parameters
key (
str
) – the key name
New in version 2017.0.0.
- Return type
None
-
containsKey
(key)[source]¶ Determines whether the given key is in this table.
- Parameters
key (
str
) – the key to search for- Return type
bool
- Returns
True if the table as a value assigned to the given key
-
containsSubTable
(key)[source]¶ Determines whether there exists a non-empty subtable for this key in this table.
- Parameters
key (
str
) – the key to search for (must not end with path separator)- Return type
bool
- Returns
True if there is a subtable with the key which contains at least one key/subtable of its own
-
delete
(key)[source]¶ Deletes the specified key in this table.
- Parameters
key (
str
) – the key name
New in version 2017.0.0.
- Return type
None
-
getAutoUpdateValue
(key, defaultValue, writeDefault=True)[source]¶ Returns an object that will be automatically updated when the value is updated by networktables.
- Parameters
key (
str
) – the key namedefaultValue (any) – Default value to use if not in the table
writeDefault (
bool
) – If True, put the default value to the table, overwriting existing values
- Return type
Note
If you modify the returned value, the value will NOT be written back to NetworkTables (though now there are functions you can use to write values). See
ntproperty()
if you’re looking for that sort of thing.See also
ntproperty()
is a better alternative to useNew in version 2015.1.3.
Changed in version 2018.0.0: This now returns the same as
NetworkTable.getEntry()
-
getBoolean
(key, defaultValue)[source]¶ Gets the boolean associated with the given name. If the key does not exist or is of different type, it will return the default value.
- Parameters
key (
str
) – the key namedefaultValue (
bool
) – the default value if no value is found
- Return type
bool
- Returns
the key
-
getBooleanArray
(key, defaultValue)[source]¶ Returns the boolean array the key maps to. If the key does not exist or is of different type, it will return the default value.
- Parameters
key (str) – the key to look up
defaultValue – the value to be returned if no value is found
- Return type
Sequence
[bool
]- Returns
the value associated with the given key or the given default value if there is no value associated with the key
New in version 2017.0.0.
-
getEntry
(key)[source]¶ Gets the entry for a subkey. This is the preferred API to use to access NetworkTable keys.
- Return type
New in version 2018.0.0.
-
getFlags
(key)[source]¶ Returns the entry flags for the specified key.
- Parameters
key (
str
) – the key name- Returns
the flags, or 0 if the key is not defined
- Return type
New in version 2017.0.0.
-
getKeys
(types=0)[source]¶ - Parameters
types (
EntryTypes
) – bitmask of types; 0 is treated as a “don’t care”.- Return type
List
[str
]- Returns
keys currently in the table
New in version 2017.0.0.
-
getNumber
(key, defaultValue)[source]¶ Gets the number associated with the given name.
- Parameters
key (
str
) – the key to look updefaultValue (
float
) – the value to be returned if no value is found
- Return type
float
- Returns
the value associated with the given key or the given default value if there is no value associated with the key
-
getNumberArray
(key, defaultValue)[source]¶ Returns the number array the key maps to. If the key does not exist or is of different type, it will return the default value.
- Parameters
key (
str
) – the key to look updefaultValue – the value to be returned if no value is found
- Return type
Sequence
[float
]- Returns
the value associated with the given key or the given default value if there is no value associated with the key
New in version 2017.0.0.
-
getPath
()[source]¶ Gets the full path of this table. Does not include the trailing “/”.
- Return type
str
- Returns
The path (e.g “”, “/foo”).
-
getRaw
(key, defaultValue)[source]¶ Returns the raw value (byte array) the key maps to. If the key does not exist or is of different type, it will return the default value.
- Parameters
key (
str
) – the key to look updefaultValue (
bytes
) – the value to be returned if no value is found
- Return type
bytes
- Returns
the value associated with the given key or the given default value if there is no value associated with the key
New in version 2017.0.0.
-
getString
(key, defaultValue)[source]¶ Gets the string associated with the given name. If the key does not exist or is of different type, it will return the default value.
- Parameters
key (
str
) – the key to look updefaultValue (
str
) – the value to be returned if no value is found
- Return type
str
- Returns
the value associated with the given key or the given default value if there is no value associated with the key
-
getStringArray
(key, defaultValue)[source]¶ Returns the string array the key maps to. If the key does not exist or is of different type, it will return the default value.
- Parameters
key (
str
) – the key to look updefaultValue – the value to be returned if no value is found
- Return type
Sequence
[str
]- Returns
the value associated with the given key or the given default value if there is no value associated with the key
New in version 2017.0.0.
-
getSubTable
(key)[source]¶ Returns the table at the specified key. If there is no table at the specified key, it will create a new table
- Parameters
key (
str
) – the key name- Return type
NetworkTable
- Returns
the networktable to be returned
-
getSubTables
()[source]¶ - Return type
List
[str
]- Returns
subtables currently in the table
New in version 2017.0.0.
-
getValue
(key, defaultValue)[source]¶ Gets the value associated with a key. This supports all NetworkTables types (unlike
putValue()
).- Parameters
key (
str
) – the key of the value to look updefaultValue (any) – The default value to return if the key doesn’t exist
- Returns
the value associated with the given key
- Return type
bool, int, float, str, bytes, tuple
New in version 2017.0.0.
-
isPersistent
(key)[source]¶ Returns whether the value is persistent through program restarts.
- Parameters
key (
str
) – the key name
New in version 2017.0.0.
- Return type
bool
-
path
¶ Path of table without trailing slash
-
putBoolean
(key, value)[source]¶ Put a boolean in the table
- Parameters
key (
str
) – the key to be assigned tovalue (
bool
) – the value that will be assigned
- Return type
bool
- Returns
False if the table key already exists with a different type
-
putBooleanArray
(key, value)[source]¶ Put a boolean array in the table
- Parameters
key (
str
) – the key to be assigned tovalue (
Sequence
[bool
]) – the value that will be assigned
- Return type
bool
- Returns
False if the table key already exists with a different type
New in version 2017.0.0.
-
putNumber
(key, value)[source]¶ Put a number in the table
- Parameters
key (
str
) – the key to be assigned tovalue (
float
) – the value that will be assigned
- Return type
bool
- Returns
False if the table key already exists with a different type
-
putNumberArray
(key, value)[source]¶ Put a number array in the table
- Parameters
key (
str
) – the key to be assigned tovalue (
Sequence
[float
]) – the value that will be assigned
- Return type
bool
- Returns
False if the table key already exists with a different type
New in version 2017.0.0.
-
putRaw
(key, value)[source]¶ Put a raw value (byte array) in the table
- Parameters
key (
str
) – the key to be assigned tovalue (
bytes
) – the value that will be assigned
- Return type
bool
- Returns
False if the table key already exists with a different type
New in version 2017.0.0.
-
putString
(key, value)[source]¶ Put a string in the table
- Parameters
key (
str
) – the key to be assigned tovalue (
str
) – the value that will be assigned
- Return type
bool
- Returns
False if the table key already exists with a different type
-
putStringArray
(key, value)[source]¶ Put a string array in the table
- Parameters
key (
str
) – the key to be assigned tovalue (
Sequence
[str
]) – the value that will be assigned
- Return type
bool
- Returns
False if the table key already exists with a different type
New in version 2017.0.0.
-
putValue
(key, value)[source]¶ Put a value in the table, trying to autodetect the NT type of the value. Refer to this table to determine the type mapping:
PyType
NT Type
Notes
bool
int
float
str
bytes
list
Error
Use putXXXArray methods instead
tuple
Error
Use putXXXArray methods instead
- Parameters
key (
str
) – the key to be assigned tovalue (bool, int, float, str, bytes) – the value that will be assigned
- Return type
bool
- Returns
False if the table key already exists with a different type
New in version 2017.0.0.
-
removeEntryListener
(listener)[source]¶ Removes a table listener
- Parameters
listener (
Callable
) – callable that was passed toaddTableListener()
oraddSubTableListener()
- Return type
None
-
setDefaultBoolean
(key, defaultValue)[source]¶ If the key doesn’t currently exist, then the specified value will be assigned to the key.
- Parameters
key (
str
) – the key to be assigned todefaultValue (
bool
) – the default value to set if key doesn’t exist.
- Return type
bool
- Returns
False if the table key exists with a different type
New in version 2017.0.0.
-
setDefaultBooleanArray
(key, defaultValue)[source]¶ If the key doesn’t currently exist, then the specified value will be assigned to the key.
- Parameters
key (
str
) – the key to be assigned todefaultValue (
Sequence
[bool
]) – the default value to set if key doesn’t exist.
- Return type
bool
- Returns
False if the table key exists with a different type
New in version 2017.0.0.
-
setDefaultNumber
(key, defaultValue)[source]¶ If the key doesn’t currently exist, then the specified value will be assigned to the key.
- Parameters
key (
str
) – the key to be assigned todefaultValue (int, float) – the default value to set if key doesn’t exist.
- Return type
bool
- Returns
False if the table key exists with a different type
New in version 2017.0.0.
-
setDefaultNumberArray
(key, defaultValue)[source]¶ If the key doesn’t currently exist, then the specified value will be assigned to the key.
- Parameters
key (
str
) – the key to be assigned todefaultValue (
Sequence
[float
]) – the default value to set if key doesn’t exist.
- Return type
bool
- Returns
False if the table key exists with a different type
New in version 2017.0.0.
-
setDefaultRaw
(key, defaultValue)[source]¶ If the key doesn’t currently exist, then the specified value will be assigned to the key.
- Parameters
key (
str
) – the key to be assigned todefaultValue (
bytes
) – the default value to set if key doesn’t exist.
- Return type
bool
- Returns
False if the table key exists with a different type
New in version 2017.0.0.
-
setDefaultString
(key, defaultValue)[source]¶ If the key doesn’t currently exist, then the specified value will be assigned to the key.
- Parameters
key (
str
) – the key to be assigned todefaultValue (
str
) – the default value to set if key doesn’t exist.
- Return type
bool
- Returns
False if the table key exists with a different type
New in version 2017.0.0.
-
setDefaultStringArray
(key, defaultValue)[source]¶ If the key doesn’t currently exist, then the specified value will be assigned to the key.
- Parameters
key (
str
) – the key to be assigned todefaultValue (
Sequence
[str
]) – the default value to set if key doesn’t exist.
- Return type
bool
- Returns
False if the table key exists with a different type
New in version 2017.0.0.
-
setDefaultValue
(key, defaultValue)[source]¶ If the key doesn’t currently exist, then the specified value will be assigned to the key.
- Parameters
key (
str
) – the key to be assigned todefaultValue (bool, int, float, str, bytes) – the default value to set if key doesn’t exist.
- Return type
bool
- Returns
False if the table key exists with a different type
New in version 2017.0.0.
See also
-
setFlags
(key, flags)[source]¶ Sets entry flags on the specified key in this table.
- Parameters
key (
str
) – the key nameflags (
EntryFlags
) – the flags to set (bitmask)
New in version 2017.0.0.
- Return type
None
-
class
networktables.
NetworkTableEntry
(api, local_id, key)[source]¶ Holds a value from NetworkTables, and changes it as new entries come in. Do not create this object directly, use
NetworkTablesInstance.getEntry()
orNetworkTable.getEntry()
to obtain an instance of this class.Using NetworkTableEntry objects to access/change NT values is more efficient than the getX/putX methods of
NetworkTable
.New in version 2018.0.0.
-
addListener
(listener, flags, paramIsNew=True)[source]¶ Add a listener for changes to the entry
- Parameters
listener (callable(entry, key, value, param)) – the listener to add
flags (
NetworkTablesInstance.NotifyFlags
) – bitmask specifying desired notificationsparamIsNew (
bool
) – If True, the listener fourth parameter is a boolean set to True if the listener is being called because of a new value in the table. Otherwise, the parameter is an integer of the raw NT_NOTIFY_* flags
- Returns
listener handle
-
clearFlags
(flags)[source]¶ Clears flags
- Parameters
flags (
int
) – the flags to clear (bitmask)- Return type
None
-
forceSetBooleanArray
(value)[source]¶ Sets the entry’s value.
- Parameters
value (
Sequence
[bool
]) – the value to set
-
forceSetDoubleArray
(value)[source]¶ Sets the entry’s value.
- Parameters
value (
Sequence
[float
]) – the value to set
-
forceSetNumber
(value)¶ Sets the entry’s value.
- Parameters
value (
float
) – the value to set
-
forceSetNumberArray
(value)¶ Sets the entry’s value.
- Parameters
value (
Sequence
[float
]) – the value to set
-
forceSetStringArray
(value)[source]¶ Sets the entry’s value.
- Parameters
value (
Sequence
[str
]) – the value to set
-
forceSetValue
(value)[source]¶ Sets the entry’s value
- Parameters
value – the value that will be assigned
Warning
Empty lists will fail
-
getBoolean
(defaultValue)[source]¶ Gets the entry’s value as a boolean. If the entry does not exist or is of different type, it will return the default value.
- Parameters
defaultValue (~D) – the value to be returned if no value is found
- Return type
Union
[bool
, ~D]- Returns
the entry’s value or the given default value
-
getBooleanArray
(defaultValue)[source]¶ Gets the entry’s value as a boolean array. If the entry does not exist or is of different type, it will return the default value.
- Parameters
defaultValue (~D) – the value to be returned if no value is found
- Return type
Union
[Sequence
[bool
], ~D]- Returns
the entry’s value or the given default value
-
getDouble
(defaultValue)[source]¶ Gets the entry’s value as a double. If the entry does not exist or is of different type, it will return the default value.
- Parameters
defaultValue (~D) – the value to be returned if no value is found
- Return type
Union
[float
, ~D]- Returns
the entry’s value or the given default value
-
getDoubleArray
(defaultValue)[source]¶ Gets the entry’s value as a double array. If the entry does not exist or is of different type, it will return the default value.
- Parameters
defaultValue (~D) – the value to be returned if no value is found
- Return type
Union
[Sequence
[float
], ~D]- Returns
the entry’s value or the given default value
-
getInfo
()[source]¶ Gets combined information about the entry.
- Returns
Entry information
- Return type
tuple of (name, type, flags)
-
getNumber
(defaultValue)¶ Gets the entry’s value as a double. If the entry does not exist or is of different type, it will return the default value.
- Parameters
defaultValue (~D) – the value to be returned if no value is found
- Return type
Union
[float
, ~D]- Returns
the entry’s value or the given default value
-
getRaw
(defaultValue)[source]¶ Gets the entry’s value as a raw value (byte array). If the entry does not exist or is of different type, it will return the default value.
- Parameters
defaultValue (~D) – the value to be returned if no value is found
- Return type
Union
[bytes
, ~D]- Returns
the entry’s value or the given default value
-
getString
(defaultValue)[source]¶ Gets the entry’s value as a string. If the entry does not exist or is of different type, it will return the default value.
- Parameters
defaultValue (~D) – the value to be returned if no value is found
- Return type
Union
[str
, ~D]- Returns
the entry’s value or the given default value
-
getStringArray
(defaultValue)[source]¶ Gets the entry’s value as a string array. If the entry does not exist or is of different type, it will return the default value.
- Parameters
defaultValue (~D) – the value to be returned if no value is found
- Returns
the entry’s value or the given default value
- Return type
list(float)
-
isPersistent
()[source]¶ Returns whether the value is persistent through program restarts.
- Return type
bool
- Returns
True if the value is persistent.
-
key
¶
-
removeListener
(listener_id)[source]¶ Remove a listener from receiving entry events
- Parameters
listener – the callable that was passed to addListener
- Return type
None
-
setBoolean
(value)[source]¶ Sets the entry’s value.
- Parameters
value (
bool
) – the value to set- Return type
bool
- Returns
False if the entry exists with a different type
-
setBooleanArray
(value)[source]¶ Sets the entry’s value.
- Parameters
value (
Sequence
[bool
]) – the value to set- Return type
bool
- Returns
False if the entry exists with a different type
-
setDefaultBoolean
(defaultValue)[source]¶ Sets the entry’s value if it does not exist.
- Parameters
defaultValue (
bool
) – the default value to set- Return type
bool
- Returns
False if the entry exists with a different type
-
setDefaultBooleanArray
(defaultValue)[source]¶ Sets the entry’s value if it does not exist.
- Parameters
defaultValue (
Sequence
[bool
]) – the default value to set- Return type
bool
- Returns
False if the entry exists with a different type
-
setDefaultDouble
(defaultValue)[source]¶ Sets the entry’s value if it does not exist.
- Parameters
defaultValue (
float
) – the default value to set- Return type
bool
- Returns
False if the entry exists with a different type
-
setDefaultDoubleArray
(defaultValue)[source]¶ Sets the entry’s value if it does not exist.
- Parameters
defaultValue (
Sequence
[float
]) – the default value to set- Return type
bool
- Returns
False if the entry exists with a different type
-
setDefaultNumber
(defaultValue)¶ Sets the entry’s value if it does not exist.
- Parameters
defaultValue (
float
) – the default value to set- Return type
bool
- Returns
False if the entry exists with a different type
-
setDefaultNumberArray
(defaultValue)¶ Sets the entry’s value if it does not exist.
- Parameters
defaultValue (
Sequence
[float
]) – the default value to set- Return type
bool
- Returns
False if the entry exists with a different type
-
setDefaultRaw
(defaultValue)[source]¶ Sets the entry’s value if it does not exist.
- Parameters
defaultValue (
bytes
) – the default value to set- Return type
bool
- Returns
False if the entry exists with a different type
-
setDefaultString
(defaultValue)[source]¶ Sets the entry’s value if it does not exist.
- Parameters
defaultValue (
str
) – the default value to set- Return type
bool
- Returns
False if the entry exists with a different type
-
setDefaultStringArray
(defaultValue)[source]¶ Sets the entry’s value if it does not exist.
- Parameters
defaultValue (
Sequence
[str
]) – the default value to set- Return type
bool
- Returns
False if the entry exists with a different type
-
setDefaultValue
(defaultValue)[source]¶ Sets the entry’s value if it does not exist.
- Parameters
defaultValue – the default value to set
- Return type
bool
- Returns
False if the entry exists with a different type
Warning
Do not set an empty list, it will fail
-
setDouble
(value)[source]¶ Sets the entry’s value.
- Parameters
value (
float
) – the value to set- Return type
bool
- Returns
False if the entry exists with a different type
-
setDoubleArray
(value)[source]¶ Sets the entry’s value.
- Parameters
value (
Sequence
[float
]) – the value to set- Return type
bool
- Returns
False if the entry exists with a different type
-
setFlags
(flags)[source]¶ Sets flags.
- Parameters
flags (
int
) – the flags to set (bitmask)- Return type
None
-
setNumber
(value)¶ Sets the entry’s value.
- Parameters
value (
float
) – the value to set- Return type
bool
- Returns
False if the entry exists with a different type
-
setNumberArray
(value)¶ Sets the entry’s value.
- Parameters
value (
Sequence
[float
]) – the value to set- Return type
bool
- Returns
False if the entry exists with a different type
-
setRaw
(value)[source]¶ Sets the entry’s value.
- Parameters
value (
bytes
) – the value to set- Return type
bool
- Returns
False if the entry exists with a different type
-
setString
(value)[source]¶ Sets the entry’s value.
- Parameters
value (
str
) – the value to set- Return type
bool
- Returns
False if the entry exists with a different type
-
setStringArray
(value)[source]¶ Sets the entry’s value.
- Parameters
value (
Sequence
[str
]) – the value to set- Return type
bool
- Returns
False if the entry exists with a different type
-
setValue
(value)[source]¶ Sets the entry’s value
- Parameters
value – the value that will be assigned
- Return type
bool
- Returns
False if the table key already exists with a different type
Warning
Empty lists will fail
-
property
value
¶ Property to access the value of this entry, or None if the entry hasn’t been initialized yet (use setXXX or forceXXX)
-
Utilities¶
-
class
networktables.util.
ChooserControl
(key, on_choices=None, on_selected=None, *, inst=<_pynetworktables.instance.NetworkTablesInstance object>)[source]¶ Interacts with a
wpilib.SendableChooser
object over NetworkTables.- Parameters
key (
str
) – NetworkTables keyon_choices (
Optional
[Callable
[[Sequence
[str
]],None
]]) – A function that will be called when the choices change.on_selection – A function that will be called when the selection changes.
inst (
NetworkTablesInstance
) – The NetworkTables instance to use.
-
networktables.util.
ntproperty
(key, defaultValue, writeDefault=True, doc=None, persistent=False, *, inst=<_pynetworktables.instance.NetworkTablesInstance object>)[source]¶ A property that you can add to your classes to access NetworkTables variables like a normal variable.
- Parameters
key (
str
) – A full NetworkTables key (eg/SmartDashboard/foo
)defaultValue (any) – Default value to use if not in the table
writeDefault (
bool
) – If True, put the default value to the table, overwriting existing valuesdoc (
Optional
[str
]) – If given, will be the docstring of the property.persistent (
bool
) – If True, persist set values across restarts. writeDefault is ignored if this is True.inst (
NetworkTablesInstance
) – The NetworkTables instance to use.
Example usage:
class Foo(object): something = ntproperty('/SmartDashboard/something', True) ... def do_thing(self): if self.something: # reads from value ... self.something = False # writes value
Note
Does not work with empty lists/tuples.
Getting the value of this property should be reasonably fast, but setting the value will have just as much overhead as
NetworkTable.putValue()
Warning
This function assumes that the value’s type never changes. If it does, you’ll get really strange errors… so don’t do that.
New in version 2015.3.0.
Changed in version 2017.0.6: The doc parameter.
Changed in version 2018.0.0: The persistent parameter.
- Return type
property