feat: add emulator code with instructions

[KaustubhPatange]

As discussed here SeedSigner/seedsigner#878,

This PR adds emulator as a separate repository decoupled from the main seedsigner repo. The PR contains multiple (2) commits as of now,

1. initial commit to emulator code (copied from above PR)
2. updated README.md with instructions.

Approach

To run this emulator we need actual SeedSigner repository. Instead of git submodules or alias / symlinks to the main repo, the run_emulator.py script accepts a path argument that should point to the seedsigner repository. So,

python run_emulator.py <path-to-seedsigner-repo>

is how we would be able to run the emulator.

The benefit of this approach is,

• agnostic to git submodule
• no symlinks / alias commands which are OS specific (adds an overhead for a user to read an execute it)
• can run emulator against multiple git worktrees / multiple clones without maintaining submodule or symlinks.

---

The setup is simple and easy to walk through by following README.md. Let me know any changes required.

---

• Next steps would be to add CI.

[hectorchu]

I think it would be related to announce here that I ported SeedSigner to Android using Kivy. And Kivy is a cross-platform technology, so my port also runs equally on desktop. I also have touch screen/mouse support.

https://github.com/ltcmweb/seedsigner/tree/kivy

[KaustubhPatange]

I think it would be related to announce here that I ported SeedSigner to Android using Kivy. And Kivy is a cross-platform technology, so my port also runs equally on desktop. I also have touch screen/mouse support.

https://github.com/ltcmweb/seedsigner/tree/kivy

I'm super inspired by your work so great job on that part. I discussed the emulator project with SeedSigner team earlier, the goal is to have minimal initial setup + CI action to test changes with working emulator so users can set it up without much hastle.

Once the model is solid we or you can work on incorporating your changes if SeedSigner team agrees with it.

[newtonick]

I had to run brew install python-tk@3.12 to install tkinter on macOS. After I did this I could run python3 -m tkinter without errors. Before that I was getting this error:

Traceback (most recent call last):
  File "<frozen runpy>", line 189, in _run_module_as_main
  File "<frozen runpy>", line 148, in _get_module_details
  File "<frozen runpy>", line 112, in _get_module_details
  File "/usr/local/Cellar/python@3.14/3.14.3_1/Frameworks/Python.framework/Versions/3.14/lib/python3.14/tkinter/__init__.py", line 38, in <module>
    import _tkinter # If this fails your Python may not be configured for Tk
    ^^^^^^^^^^^^^^^
ModuleNotFoundError: No module named '_tkinter'

Then when I ran python run_emulator.py ../seedsigner/src it crashed when launching.

seedsigner-emulator % python run_emulator.py ../seedsigner/src
Starting GUI simulator...
Starting SeedSigner main application...
Set LANGUAGE locale to en
2026-03-12 16:58:20,773     INFO [main main (46)]: Starting SeedSigner with: {'loglevel': 'INFO'}
Process Main:
Traceback (most recent call last):
  File "/usr/local/Cellar/python@3.14/3.14.3_1/Frameworks/Python.framework/Versions/3.14/lib/python3.14/multiprocessing/process.py", line 320, in _bootstrap
    self.run()
    ~~~~~~~~^^
  File "/usr/local/Cellar/python@3.14/3.14.3_1/Frameworks/Python.framework/Versions/3.14/lib/python3.14/multiprocessing/process.py", line 108, in run
    self._target(*self._args, **self._kwargs)
    ~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/nklockenga/Source/seedsigner-emulator/run_emulator.py", line 122, in run_main
    main()
    ~~~~^^
  File "/Users/nklockenga/Source/seedsigner/src/main.py", line 49, in main
    Controller.get_instance().start()
    ~~~~~~~~~~~~~~~~~~~~~~~^^
  File "/Users/nklockenga/Source/seedsigner/src/seedsigner/controller.py", line 150, in get_instance
    return cls.configure_instance()
           ~~~~~~~~~~~~~~~~~~~~~~^^
  File "/Users/nklockenga/Source/seedsigner/src/seedsigner/controller.py", line 192, in configure_instance
    Renderer.configure_instance()
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~^^
  File "/Users/nklockenga/Source/seedsigner/src/seedsigner/gui/renderer.py", line 32, in configure_instance
    renderer.initialize_display()
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~^^
  File "/Users/nklockenga/Source/seedsigner/src/seedsigner/gui/renderer.py", line 51, in initialize_display
    self.disp = DisplayDriverFactory.instantiate_display_driver(self.display_type, width=int(width), height=int(height))
                ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/nklockenga/Source/seedsigner/src/seedsigner/hardware/displays/display_driver.py", line 77, in instantiate_display_driver
    return original_ST7789(_width=width, _height=height)
TypeError: MockST7789.__init__() got an unexpected keyword argument '_width'. Did you mean 'width'?

[KaustubhPatange]

@newtonick Are you using a different modified seedsigner source? I tested on latest "dev" branch from seedsigner repo and the DisplayDriver class accepts width and height parameter not the _width. I also tested on 240x240 resolution but 320x240 also seems to work.

[wolgwang1729]

@KaustubhPatange I was getting the same error. I've opened a PR (KaustubhPatange#1) to fix the crash. To make sure the emulator works for both the older releases and the latest dev branch you are testing on, I updated MockST7789.__init__ to explicitly accept _width and _height as optional parameters, seamlessly falling back to width and height. Let me know if this approach looks good to merge!"

[KaustubhPatange]

@wolgwang1729, I merged your changes. I think this will also fix the upstream branch in this PR, so it should also fix for @newtonick.