0
# Device Configuration
1

2
Configure MicroPython device settings including real-time clock synchronization and system-level device configuration for optimal operation.
3

4
## Capabilities
5

6
### Real-Time Clock Management
7

8
Get and set the device real-time clock to synchronize with host system time.
9

10
```python { .api }
11
def do_rtc(state, args):
12
    """
13
    Get or set device real-time clock.
14
    
15
    Parameters:
16
    - state: State object with active transport
17
    - args: RTC command arguments
18
    
19
    Args attributes:
20
    - set: Boolean flag to set RTC to current local time
21
    
22
    Without --set flag: displays current device RTC time
23
    With --set flag: synchronizes device RTC with host system time
24
    """
25
```
26

27
## Command-Line Interface
28

29
### Real-Time Clock Operations
30

31
```bash
32
# Get current device RTC time
33
mpremote rtc
34

35
# Set device RTC to current system time
36
mpremote rtc --set
37

38
# RTC operations with device connection
39
mpremote connect /dev/ttyUSB0 rtc --set
40
```
41

42
## Usage Examples
43

44
### RTC Synchronization
45

46
```python
47
from mpremote.main import State
48
from mpremote.commands import do_rtc
49

50
# Set up connected device
51
state = State()
52
# ... connect to device ...
53

54
# Get current RTC time
55
args = type('Args', (), {'set': False})()
56
do_rtc(state, args)
57

58
# Set RTC to system time
59
args = type('Args', (), {'set': True})()
60
do_rtc(state, args)
61
```
62

63
### System Time Synchronization
64

65
```bash
66
# Check current device time
67
mpremote exec "
68
import time
69
print('Device time:', time.localtime())
70
"
71

72
# Synchronize with host system
73
mpremote rtc --set
74

75
# Verify synchronization
76
mpremote exec "
77
import time
78
print('Synchronized time:', time.localtime())
79
"
80
```
81

82
## Advanced Configuration
83

84
### Automated Time Synchronization
85

86
```bash
87
# Synchronize time at device startup
88
mpremote rtc --set exec "
89
import time
90
print('Device time synchronized:', time.localtime())
91
"
92

93
# Verify time synchronization with fallback
94
mpremote exec "
95
import time
96
try:
97
    import ntptime  # if available
98
    ntptime.settime()
99
    print('NTP sync successful')
100
except:
101
    print('Using RTC time:', time.localtime())
102
"
103
```
104

105
### Time-Based Operations
106

107
```bash
108
# Set up scheduled tasks based on RTC
109
mpremote rtc --set exec "
110
import time
111
import machine
112

113
def scheduled_task():
114
    current_time = time.localtime()
115
    print(f'Task executed at: {current_time}')
116
    # Perform scheduled operations
117

118
# Set up timer for periodic execution
119
timer = machine.Timer(-1)
120
timer.init(period=60000, mode=machine.Timer.PERIODIC, callback=lambda t: scheduled_task())
121
"
122
```
123

124
## Error Handling
125

126
Device configuration operations may encounter various errors:
127

128
```python
129
from mpremote.transport import TransportError, TransportExecError
130

131
try:
132
    do_rtc(state, args)
133
except TransportExecError as e:
134
    if "RTC not supported" in e.error_output:
135
        print("Device does not support RTC")
136
    elif "time sync failed" in e.error_output:
137
        print("Time synchronization failed")
138
    else:
139
        print(f"RTC operation failed: {e.error_output}")
140
except TransportError as e:
141
    print(f"Communication error: {e}")
142
```
143

144
### Common Error Scenarios
145

146
```bash
147
# RTC not supported
148
mpremote rtc --set
149
# Error: RTC functionality not available on this device
150

151
# Communication timeout
152
mpremote rtc
153
# Error: Device communication timeout
154
```
155

156
## Best Practices
157

158
### RTC Management
159

160
```bash
161
# Always synchronize time after connecting to a new device
162
mpremote connect auto rtc --set
163

164
# Verify time synchronization before time-critical operations
165
mpremote rtc exec "
166
import time
167
current_time = time.localtime()
168
if current_time[0] < 2020:  # Check if year seems valid
169
    print('Warning: RTC may not be synchronized')
170
else:
171
    print('RTC appears synchronized')
172
"
173
```
174

175
### Development Workflow
176

177
```bash
178
# Include RTC synchronization in device setup scripts
179
#!/bin/bash
180
echo "Setting up MicroPython device..."
181
mpremote connect auto rtc --set
182
echo "Device time synchronized"
183

184
# Verify device configuration
185
mpremote exec "
186
import time
187
import sys
188
print('Device time:', time.localtime())
189
print('Python version:', sys.version)
190
print('Platform:', sys.platform)
191
"
192
```
193

194
### Time Zone Considerations
195

196
```bash
197
# Note: mpremote sets RTC to host system local time
198
# For UTC operations, consider timezone handling in device code
199
mpremote exec "
200
import time
201

202
# Convert local time to UTC offset
203
local_time = time.localtime()
204
# Note: MicroPython may not have timezone info
205
# Handle timezone conversion in application code as needed
206
print('Local time:', local_time)
207
"
208
```