Simulate your app

You can run badge apps on your computer with the local simulator from the badge-2024-software repo.

There is also a web emulator. Use it to explore the badge UI and try apps from the app store before installing them on your badge. Once you publish your apps you can also try them there.

Installation

1. Install Python.

   macOS

   The simulator depends on SDL2. Install it with Homebrew before continuing:

   brew install sdl2 sdl2_image sdl2_mixer sdl2_ttf pkg-config
   

2. Install pipenv: pip install --user pipenv.

3. Run pipenv --version in a terminal. If you don't see a version number, try python -m pipenv --version. If that works but pipenv --version didn't, you'll need to remember to type python -m before pipenv for the rest of this guide.
4. Clone the badge-2024-software repo.
5. Open a terminal and navigate to the sim folder.
6. From there, run pipenv install to install all dependencies.

Simulate your app

The local badge simulator simulates all apps in the sim/apps/ folder. To test your app, place your app's python file into the sim/apps/ folder:

1. Create a folder for your app, for example MyApp.
2. In the new folder (for example sim/apps/MyApp/), copy your app's python file. For example, this is app.py for an example app:

import app

from events.input import Buttons, BUTTON_TYPES


class ExampleApp(app.App):
    def __init__(self):
        self.button_states = Buttons(self)

    def update(self, delta):
        if self.button_states.get(BUTTON_TYPES["CANCEL"]):
            # The button_states do not update while you are in the background.
            # Calling clear() ensures the next time you open the app, it stays open.
            # Without it the app would close again immediately.
            self.button_states.clear()
            self.minimise()

    def draw(self, ctx):
        ctx.save()
        ctx.rgb(0.2, 0, 0).rectangle(-120, -120, 240, 240).fill()
        ctx.rgb(1, 0, 0).move_to(-80, 0).text("Hello world")
        ctx.restore()

__app_export__ = ExampleApp

3. In the same folder, create a file called __init__.py and use it to import your app's class. If you called your python app app.py and the class for your app is called ExampleApp, you would use the following content:

from .app import ExampleApp

4. In the same folder, create a file called metadata.json and add your app's metadata. The file needs to contain:

• your app's name
• the category for the app
• the callable - which is the Python class for your app. When your app is run, this is the class that will be called to instantiate your app:

{
  "callable": "ExampleApp",
  "name": "Example app",
  "category": "unknown",
  "hidden": false
}

5. Run the simulator an select your app to test it:

pipenv run python run.py

Troubleshooting

What next?