0
# PyNetworkTables
1

2
A pure Python implementation of NetworkTables, used for robot communications in the FIRST Robotics Competition. This library enables non-Driver Station data transmission between robots and other systems across the network, serving as a Python alternative to the C++ ntcore implementation.
3

4
## Package Information
5

6
- **Package Name**: pynetworktables
7
- **Language**: Python
8
- **Installation**: `pip install pynetworktables`
9
- **Python Requirements**: >=3.5
10

11
## Core Imports
12

13
```python
14
import networktables
15
```
16

17
Basic usage with the global instance:
18

19
```python
20
from networktables import NetworkTables
21
```
22

23
For advanced usage with custom instances:
24

25
```python
26
from networktables import NetworkTablesInstance, NetworkTable, NetworkTableEntry, Value
27
```
28

29
Property decorator for class-based integration:
30

31
```python
32
from networktables.util import ntproperty, ChooserControl
33
```
34

35
## Basic Usage
36

37
```python
38
from networktables import NetworkTables
39

40
# Initialize as client to connect to robot
41
NetworkTables.initialize(server='roborio-1234-frc.local')
42

43
# Get SmartDashboard table for robot data sharing
44
sd = NetworkTables.getTable('SmartDashboard')
45

46
# Send data to robot
47
sd.putNumber('driveSpeed', 0.8)
48
sd.putString('autonomousMode', 'defense')
49
sd.putBoolean('climbEnabled', True)
50

51
# Read data from robot
52
batteryVoltage = sd.getNumber('batteryVoltage', 0.0)
53
robotState = sd.getString('robotState', 'unknown')
54
isConnected = NetworkTables.isConnected()
55

56
# Using entries for more efficient operations
57
speedEntry = NetworkTables.getEntry('/SmartDashboard/driveSpeed')
58
speedEntry.setDouble(0.5)
59
currentSpeed = speedEntry.getDouble(0.0)
60
```
61

62
## Architecture
63

64
PyNetworkTables uses a hierarchical table structure with type-safe entry operations:
65

66
- **NetworkTablesInstance**: Main instance managing connections, servers, and global operations
67
- **NetworkTable**: Represents a subtable in the hierarchy for grouped key-value operations  
68
- **NetworkTableEntry**: Individual entry providing type-safe access to specific keys
69
- **Value**: Immutable container for NetworkTables data with type information
70

71
The library supports dual backends: the preferred `pyntcore` (C++ implementation) with fallback to pure Python `_pynetworktables` for maximum compatibility.
72

73
## Capabilities
74

75
### Instance Management
76

77
Core NetworkTables instance functionality for connection management, server operations, and global configuration. Provides both singleton access and support for multiple independent instances.
78

79
```python { .api }
80
class NetworkTablesInstance:
81
    @classmethod
82
    def getDefault() -> NetworkTablesInstance: ...
83
    @classmethod  
84
    def create() -> NetworkTablesInstance: ...
85
    
86
    def initialize(server=None): ...
87
    def startServer(persistFilename="networktables.ini", listenAddress="", port=1735): ...
88
    def startClient(server_or_servers): ...
89
    def shutdown(): ...
90
```
91

92
[Instance Management](./instance-management.md)
93

94
### Table Operations
95

96
Table-based interface for reading and writing values in NetworkTable hierarchies. Provides convenient methods for all supported data types and table navigation.
97

98
```python { .api }
99
class NetworkTable:
100
    def getEntry(key: str) -> NetworkTableEntry: ...
101
    def putNumber(key: str, value: float): ...
102
    def getNumber(key: str, defaultValue: float) -> float: ...
103
    def putString(key: str, value: str): ...
104
    def getString(key: str, defaultValue: str) -> str: ...
105
    def putBoolean(key: str, value: bool): ...
106
    def getBoolean(key: str, defaultValue: bool) -> bool: ...
107
```
108

109
[Table Operations](./table-operations.md)
110

111
### Entry Interface
112

113
Type-safe interface to individual NetworkTables entries with efficient access patterns. Provides the most performant way to read and write NetworkTable values.
114

115
```python { .api }
116
class NetworkTableEntry:
117
    def exists() -> bool: ...
118
    def getType() -> int: ...
119
    def setValue(value): ...
120
    def setDouble(value: float): ...
121
    def getDouble(defaultValue: float) -> float: ...
122
    def setString(value: str): ...
123
    def getString(defaultValue: str) -> str: ...
124
```
125

126
[Entry Interface](./entry-interface.md)
127

128
### Listeners and Events
129

130
Real-time notification system for NetworkTable changes including entry modifications, connection status, and table updates. Essential for responsive robotics applications.
131

132
```python { .api }
133
def addEntryListener(listener: Callable, immediateNotify: bool = True, localNotify: bool = True): ...
134
def addConnectionListener(listener: Callable, immediateNotify: bool = False): ...
135
def removeEntryListener(listener): ...
136
def removeConnectionListener(listener): ...
137
```
138

139
[Listeners and Events](./listeners-events.md)
140

141
### Persistence and Data Management
142

143
Data persistence across restarts, entry management, and bulk operations. Critical for maintaining configuration and state information between robot sessions.
144

145
```python { .api }
146
def savePersistent(filename: str): ...
147
def loadPersistent(filename: str): ...
148
def setPersistent(key: str): ...
149
def clearPersistent(key: str): ...
150
def deleteAllEntries(): ...
151
```
152

153
[Persistence and Data Management](./persistence-data.md)
154

155
### Integration Utilities
156

157
Property decorators and utility classes for seamless integration with object-oriented robotics code and WPILib components.
158

159
```python { .api }
160
def ntproperty(key: str, defaultValue, writeDefault: bool = True, 
161
               doc: str = None, persistent: bool = False, 
162
               *, inst = NetworkTables) -> property: ...
163

164
class ChooserControl:
165
    def __init__(key: str, on_choices=None, on_selected=None, *, inst=NetworkTables): ...
166
    def getChoices() -> List[str]: ...
167
    def getSelected() -> Optional[str]: ...
168
```
169

170
[Integration Utilities](./integration-utilities.md)
171

172
## Types
173

174
```python { .api }
175
class Value:
176
    """Immutable container for NetworkTables values with type information."""
177
    type: int
178
    value: Any
179
    
180
    @classmethod
181
    def makeBoolean(value: bool) -> Value: ...
182
    @classmethod
183
    def makeDouble(value: float) -> Value: ...
184
    @classmethod
185
    def makeString(value: str) -> Value: ...
186
    @classmethod
187
    def makeBooleanArray(value: List[bool]) -> Value: ...
188
    @classmethod
189
    def makeDoubleArray(value: List[float]) -> Value: ...
190
    @classmethod
191
    def makeStringArray(value: List[str]) -> Value: ...
192

193
# Entry Type Constants
194
NT_BOOLEAN = 0x01
195
NT_DOUBLE = 0x02  
196
NT_STRING = 0x04
197
NT_RAW = 0x08
198
NT_BOOLEAN_ARRAY = 0x10
199
NT_DOUBLE_ARRAY = 0x20
200
NT_STRING_ARRAY = 0x40
201

202
# Entry Flag Constants  
203
NT_PERSISTENT = 0x01
204

205
# Notification Flag Constants
206
NT_NOTIFY_IMMEDIATE = 0x01
207
NT_NOTIFY_LOCAL = 0x02
208
NT_NOTIFY_NEW = 0x04
209
NT_NOTIFY_DELETE = 0x08
210
NT_NOTIFY_UPDATE = 0x10
211
NT_NOTIFY_FLAGS = 0x20
212
```