new command: rtc

Author: pavelrevak

README.md

@@ -233,6 +233,24 @@ $ mpytool edit :newfile.py           # create new file if doesn't exist
 Downloads file to a temp file, opens in editor, uploads back if changed.
 Editor priority: `--editor` > `$VISUAL` > `$EDITOR` > error.
 
+### Device RTC (real-time clock)
+```
+$ mpytool rtc                        # display current RTC
+2026-02-21 15:30:45
+
+$ mpytool rtc --set                  # set RTC to local PC time
+RTC set to 2026-02-21 15:30:45 (local)
+
+$ mpytool rtc --utc                  # set RTC to UTC time
+RTC set to 2026-02-21 14:30:45 (UTC)
+
+$ mpytool rtc "2026-02-21 14:30:00"  # set RTC to specific datetime
+RTC set to 2026-02-21 14:30:00
+```
+
+Flags: `-s`/`--set` and `-l`/`--local` both set local time, `-u`/`--utc` sets UTC.
+Manual datetime format: `YYYY-MM-DD HH:MM:SS`.
+
 ### Mount local directory on device
 ```
 $ mpytool mount ./src                       # mount ./src as /remote, auto-start REPL

README_mpremote.md

@@ -35,7 +35,7 @@ Detailed comparison between [mpytool](https://github.com/pavelrevak/mpytool) and
 | Unmount VFS | 🔴 exit session | 🟢 `umount` |
 | Virtual submount | 🟢 `ln ./src :/dst` | 🔴 |
 | Package install | 🔴 | 🟢 `mip install pkg` |
-| RTC control | 🔴 | 🟢 `rtc`, `rtc --set` |
+| RTC control | 🟢 `rtc`, `rtc --set` | 🟢 `rtc`, `rtc --set` |
 | ROMFS manage | 🔴 | 🟢 `romfs` |
 | Edit remote file | 🟢 `edit :file` | 🟢 `edit :file` |
 | Flash read/write/ota | 🟢 `flash r/w/erase/ota` | 🔴 |

completions/_mpytool

@@ -278,6 +278,11 @@ _mpytool() {
                     fi
                     [[ $nargs -ge 1 ]] && compadd -- '--'
                     ;;
+                rtc)
+                    # rtc [-s|-l|-u] [datetime]
+                    _mpytool_options rtc
+                    compadd -- '--'
+                    ;;
                 pwd)
                     # No arguments, -- immediately
                     compadd -- '--'

completions/mpytool.bash

@@ -289,6 +289,10 @@ _mpytool() {
             fi
             [[ $nargs -ge 1 && ( -z "$cur" || "--" == "$cur"* ) ]] && COMPREPLY+=("--")
             ;;
+        rtc)
+            # rtc [-s|-l|-u] [datetime]
+            COMPREPLY=($(compgen -W "$(_mpytool_get_options rtc) --" -- "$cur"))
+            ;;
         pwd)
             # No arguments, -- immediately
             [[ -z "$cur" || "--" == "$cur"* ]] && COMPREPLY+=("--")

mpytool/mpytool.py

@@ -1,6 +1,7 @@
 """MicroPython tool"""
 
 import argparse as _argparse
+import datetime as _datetime
 import fnmatch as _fnmatch
 import importlib.metadata as _metadata
 import os as _os
@@ -31,7 +32,7 @@
 _CMD_ORDER = [
     'ls', 'tree', 'cat', 'cp', 'mv', 'mkdir', 'rm', 'pwd', 'cd', 'path',
     'stop', 'reset', 'monitor', 'repl', 'exec', 'run', 'edit', 'info',
-    'flash', 'mount', 'ln', 'speedtest', 'sleep',
+    'rtc', 'flash', 'mount', 'ln', 'speedtest', 'sleep',
 ]
 
 
@@ -147,12 +148,12 @@ def _make_parser(method):
     for group_opts in getattr(method, '_cmd_groups', []):
         group = parser.add_mutually_exclusive_group()
         for opt_args, opt_kwargs in getattr(method, '_cmd_options', []):
-            # Match by first option string (e.g., '--machine')
-            if opt_args and opt_args[0] in group_opts:
+            # Match any option string (e.g., '-s' or '--set')
+            if opt_args and any(opt in group_opts for opt in opt_args):
                 group.add_argument(*opt_args, **opt_kwargs)
     # Add non-grouped options
     for opt_args, opt_kwargs in getattr(method, '_cmd_options', []):
-        if not opt_args or opt_args[0] not in grouped_opts:
+        if not opt_args or not any(opt in grouped_opts for opt in opt_args):
             parser.add_argument(*opt_args, **opt_kwargs)
     # Add positional arguments
     for args, kwargs in getattr(method, '_cmd_args', []):
@@ -957,6 +958,63 @@ def _dispatch_edit(self, commands, is_last_group):
         path = _parse_device_path(args.path, 'edit')
         self.cmd_edit(path, editor=args.editor)
 
+    @command('rtc', 'Get or set device RTC.')
+    @mutually_exclusive('--set', '--local', '--utc')
+    @option('-s', '--set', action='store_true',
+        help='set to local PC time')
+    @option('-l', '--local', action='store_true',
+        help='set to local PC time')
+    @option('-u', '--utc', action='store_true',
+        help='set to UTC time')
+    @argument('datetime', nargs='?', metavar='DATETIME',
+        help='datetime string (YYYY-MM-DD HH:MM:SS)')
+    def _dispatch_rtc(self, commands, is_last_group):
+        args = _make_parser(self._dispatch_rtc).parse_args(commands)
+        commands.clear()
+        if args.datetime:
+            if args.set or args.local or args.utc:
+                raise ParamsError(
+                    'datetime argument is incompatible with --set/--local/--utc')
+            try:
+                parsed = _datetime.datetime.strptime(
+                    args.datetime, '%Y-%m-%d %H:%M:%S')
+            except ValueError:
+                raise ParamsError(
+                    'invalid datetime format (use YYYY-MM-DD HH:MM:SS)')
+            self._set_rtc(parsed)
+            self.verbose(
+                f"RTC set to {parsed.strftime('%Y-%m-%d %H:%M:%S')}", 1)
+        elif args.set or args.local:
+            now = _datetime.datetime.now()
+            self._set_rtc(now)
+            self.verbose(
+                f"RTC set to {now.strftime('%Y-%m-%d %H:%M:%S')} (local)", 1)
+        elif args.utc:
+            now = _datetime.datetime.now(_datetime.timezone.utc)
+            self._set_rtc(now)
+            self.verbose(
+                f"RTC set to {now.strftime('%Y-%m-%d %H:%M:%S')} (UTC)", 1)
+        else:
+            rtc = self._get_rtc()
+            print(
+                f"{rtc[0]:04d}-{rtc[1]:02d}-{rtc[2]:02d} "
+                f"{rtc[4]:02d}:{rtc[5]:02d}:{rtc[6]:02d}")
+
+    def _set_rtc(self, dt_obj):
+        """Set device RTC from datetime object"""
+        timetuple = (
+            dt_obj.year, dt_obj.month, dt_obj.day, dt_obj.weekday(),
+            dt_obj.hour, dt_obj.minute, dt_obj.second, dt_obj.microsecond)
+        self.mpy.comm.exec(
+            f"__import__('machine').RTC().datetime({timetuple})")
+
+    def _get_rtc(self):
+        """Get device RTC as tuple"""
+        import ast
+        result = self.mpy.comm.exec(
+            "print(__import__('machine').RTC().datetime())")
+        return ast.literal_eval(result.decode().strip())
+
     @command('info', 'Show device info (platform, memory, filesystem).')
     def _dispatch_info(self, commands, is_last_group):
         _, commands[:] = _make_parser(self._dispatch_info).parse_known_args(
@@ -1274,7 +1332,7 @@ def _dispatch_args(self, commands, is_last_group):
     _COMMANDS = frozenset({
         'ls', 'tree', 'cat', 'mkdir', 'rm', 'pwd', 'cd', 'path',
         'reset', 'stop', 'monitor', 'repl', 'exec', 'run', 'edit', 'info',
-        'flash', 'sleep', 'cp', 'mv', 'mount', 'ln', 'speedtest',
+        'rtc', 'flash', 'sleep', 'cp', 'mv', 'mount', 'ln', 'speedtest',
         '_paths', '_ports', '_commands', '_options', '_args',
     })
 

tests/test_integration.py

@@ -2687,5 +2687,78 @@ def test_10_append_multiple_paths(self):
         self.assertEqual(path[-2:], ['/a', '/b'])
 
 
+@requires_device
+class TestRtc(unittest.TestCase):
+    """Test RTC operations"""
+
+    @classmethod
+    def setUpClass(cls):
+        from mpytool import ConnSerial, Mpy
+        from mpytool.mpytool import MpyTool
+        from mpytool.logger import SimpleColorLogger
+        cls.conn = ConnSerial(port=DEVICE_PORT, baudrate=115200)
+        cls.mpy = Mpy(cls.conn)
+        cls.log = SimpleColorLogger(loglevel=0, verbose_level=0)
+        cls.tool = MpyTool(cls.conn, log=cls.log, verbose=None)
+        cls.tool._mpy = cls.mpy
+
+    @classmethod
+    def tearDownClass(cls):
+        cls.mpy.comm.exit_raw_repl()
+        cls.conn.close()
+
+    def test_01_rtc_display(self):
+        """Test RTC display returns valid datetime tuple"""
+        rtc = self.tool._get_rtc()
+        self.assertEqual(len(rtc), 8)
+        # Year should be reasonable (2000 is default, up to 2100)
+        self.assertGreaterEqual(rtc[0], 2000)
+        self.assertLessEqual(rtc[0], 2100)
+        # Month 1-12
+        self.assertGreaterEqual(rtc[1], 1)
+        self.assertLessEqual(rtc[1], 12)
+        # Day 1-31
+        self.assertGreaterEqual(rtc[2], 1)
+        self.assertLessEqual(rtc[2], 31)
+
+    def test_02_rtc_set_local(self):
+        """Test setting RTC to local time"""
+        import datetime
+        now = datetime.datetime.now()
+        self.tool._set_rtc(now)
+        rtc = self.tool._get_rtc()
+        # Year, month, day should match
+        self.assertEqual(rtc[0], now.year)
+        self.assertEqual(rtc[1], now.month)
+        self.assertEqual(rtc[2], now.day)
+        # Hour, minute should be close (within 1 minute tolerance)
+        self.assertEqual(rtc[4], now.hour)
+        self.assertAlmostEqual(rtc[5], now.minute, delta=1)
+
+    def test_03_rtc_set_utc(self):
+        """Test setting RTC to UTC time"""
+        import datetime
+        utc_now = datetime.datetime.now(datetime.timezone.utc)
+        self.tool._set_rtc(utc_now)
+        rtc = self.tool._get_rtc()
+        self.assertEqual(rtc[0], utc_now.year)
+        self.assertEqual(rtc[1], utc_now.month)
+        self.assertEqual(rtc[2], utc_now.day)
+        self.assertEqual(rtc[4], utc_now.hour)
+
+    def test_04_rtc_set_manual(self):
+        """Test setting RTC to manual datetime"""
+        import datetime
+        test_dt = datetime.datetime(2025, 6, 15, 12, 30, 45)
+        self.tool._set_rtc(test_dt)
+        rtc = self.tool._get_rtc()
+        self.assertEqual(rtc[0], 2025)
+        self.assertEqual(rtc[1], 6)
+        self.assertEqual(rtc[2], 15)
+        self.assertEqual(rtc[4], 12)
+        self.assertEqual(rtc[5], 30)
+        self.assertEqual(rtc[6], 45)
+
+
 if __name__ == "__main__":
     unittest.main()

tests/test_mpytool.py

@@ -813,5 +813,152 @@ def test_path_unknown_flag(self):
         self.assertIn('-x', str(ctx.exception))
 
 
+class TestRtcCommand(unittest.TestCase):
+    """Tests for rtc command"""
+
+    def setUp(self):
+        self.mock_conn = Mock()
+        self.tool = MpyTool(self.mock_conn, verbose=None)
+        self.tool._mpy = Mock()
+        self.tool._mpy.comm = Mock()
+
+    def test_rtc_display(self):
+        """'rtc' displays current RTC"""
+        # RTC tuple: (year, month, day, weekday, hour, min, sec, subsec)
+        self.tool._mpy.comm.exec.return_value = b"(2026, 2, 21, 5, 14, 30, 45, 0)\n"
+        with patch('builtins.print') as mock_print:
+            commands = []
+            self.tool._dispatch_rtc(commands, False)
+            mock_print.assert_called_once_with("2026-02-21 14:30:45")
+
+    def test_rtc_set_local(self):
+        """'rtc --set' sets RTC to local time"""
+        self.tool._mpy.comm.exec.return_value = b""
+        with patch('mpytool.mpytool._datetime') as mock_dt:
+            mock_now = Mock()
+            mock_now.year = 2026
+            mock_now.month = 2
+            mock_now.day = 21
+            mock_now.weekday.return_value = 5
+            mock_now.hour = 14
+            mock_now.minute = 30
+            mock_now.second = 45
+            mock_now.microsecond = 0
+            mock_now.strftime.return_value = "2026-02-21 14:30:45"
+            mock_dt.datetime.now.return_value = mock_now
+            commands = ['--set']
+            self.tool._dispatch_rtc(commands, False)
+            # Verify RTC was set
+            call_args = self.tool._mpy.comm.exec.call_args[0][0]
+            self.assertIn("RTC().datetime", call_args)
+            self.assertIn("2026", call_args)
+
+    def test_rtc_local_flag(self):
+        """'rtc --local' sets RTC to local time"""
+        self.tool._mpy.comm.exec.return_value = b""
+        with patch('mpytool.mpytool._datetime') as mock_dt:
+            mock_now = Mock()
+            mock_now.year = 2026
+            mock_now.month = 1
+            mock_now.day = 15
+            mock_now.weekday.return_value = 2
+            mock_now.hour = 10
+            mock_now.minute = 0
+            mock_now.second = 0
+            mock_now.microsecond = 0
+            mock_now.strftime.return_value = "2026-01-15 10:00:00"
+            mock_dt.datetime.now.return_value = mock_now
+            commands = ['--local']
+            self.tool._dispatch_rtc(commands, False)
+            call_args = self.tool._mpy.comm.exec.call_args[0][0]
+            self.assertIn("RTC().datetime", call_args)
+
+    def test_rtc_utc_flag(self):
+        """'rtc --utc' sets RTC to UTC time"""
+        self.tool._mpy.comm.exec.return_value = b""
+        with patch('mpytool.mpytool._datetime') as mock_dt:
+            mock_utc = Mock()
+            mock_utc.year = 2026
+            mock_utc.month = 2
+            mock_utc.day = 21
+            mock_utc.weekday.return_value = 5
+            mock_utc.hour = 13
+            mock_utc.minute = 30
+            mock_utc.second = 45
+            mock_utc.microsecond = 0
+            mock_utc.strftime.return_value = "2026-02-21 13:30:45"
+            mock_dt.datetime.now.return_value = mock_utc
+            mock_dt.timezone.utc = Mock()
+            commands = ['--utc']
+            self.tool._dispatch_rtc(commands, False)
+            # Verify datetime.now was called with UTC timezone
+            mock_dt.datetime.now.assert_called_with(mock_dt.timezone.utc)
+
+    def test_rtc_manual_datetime(self):
+        """'rtc "2026-02-21 14:30:00"' sets RTC manually"""
+        self.tool._mpy.comm.exec.return_value = b""
+        with patch('mpytool.mpytool._datetime') as mock_dt:
+            mock_parsed = Mock()
+            mock_parsed.year = 2026
+            mock_parsed.month = 2
+            mock_parsed.day = 21
+            mock_parsed.weekday.return_value = 5
+            mock_parsed.hour = 14
+            mock_parsed.minute = 30
+            mock_parsed.second = 0
+            mock_parsed.microsecond = 0
+            mock_parsed.strftime.return_value = "2026-02-21 14:30:00"
+            mock_dt.datetime.strptime.return_value = mock_parsed
+            commands = ['2026-02-21 14:30:00']
+            self.tool._dispatch_rtc(commands, False)
+            mock_dt.datetime.strptime.assert_called_with(
+                '2026-02-21 14:30:00', '%Y-%m-%d %H:%M:%S')
+
+    def test_rtc_invalid_datetime_format(self):
+        """'rtc "invalid"' raises ParamsError"""
+        commands = ['invalid']
+        with self.assertRaises(ParamsError) as ctx:
+            self.tool._dispatch_rtc(commands, False)
+        self.assertIn('invalid datetime format', str(ctx.exception))
+
+    def test_rtc_datetime_with_flag_error(self):
+        """'rtc --set "2026-02-21 14:30:00"' raises ParamsError"""
+        commands = ['--set', '2026-02-21 14:30:00']
+        with self.assertRaises(ParamsError) as ctx:
+            self.tool._dispatch_rtc(commands, False)
+        self.assertIn('incompatible', str(ctx.exception))
+
+    def test_rtc_short_flags(self):
+        """Test short flags -s, -l, -u"""
+        self.tool._mpy.comm.exec.return_value = b""
+        with patch('mpytool.mpytool._datetime') as mock_dt:
+            mock_now = Mock()
+            mock_now.year = 2026
+            mock_now.month = 1
+            mock_now.day = 1
+            mock_now.weekday.return_value = 2
+            mock_now.hour = 0
+            mock_now.minute = 0
+            mock_now.second = 0
+            mock_now.microsecond = 0
+            mock_now.strftime.return_value = "2026-01-01 00:00:00"
+            mock_dt.datetime.now.return_value = mock_now
+            mock_dt.timezone.utc = Mock()
+            # Test -s
+            commands = ['-s']
+            self.tool._dispatch_rtc(commands, False)
+            self.assertTrue(self.tool._mpy.comm.exec.called)
+            self.tool._mpy.comm.exec.reset_mock()
+            # Test -l
+            commands = ['-l']
+            self.tool._dispatch_rtc(commands, False)
+            self.assertTrue(self.tool._mpy.comm.exec.called)
+            self.tool._mpy.comm.exec.reset_mock()
+            # Test -u
+            commands = ['-u']
+            self.tool._dispatch_rtc(commands, False)
+            mock_dt.datetime.now.assert_called_with(mock_dt.timezone.utc)
+
+
 if __name__ == "__main__":
     unittest.main()