Swagbadge2021 GettingStarted

Getting started with the Swagbadge

My package arrived in the mail, first steps.

• Your package should contain [insert photo here]
• Powering it up
  • Insert the micro USB cable into the badge and connect the other end to a USB port on your computer.
  • A green light should glow on the board.
• Turning it on and off again
  • If the board has a switch, you can switch it on/off safely. Otherwise just plugging/unplugging it will be sufficient.
• On bootup, you should see:
  • The OLED screens will display "Aiko 0.1" as a title
  • It will also display something else to tell you to set up your wifi.

Getting it on your network

• Safety precautions we have provided
  • When using any hardware ordered off the internet, you can't be quite certain what software might be present on it. Before shipping these badges to you, we reflashed a fresh copy of MicroPython onto the Lolin32.
  • The framework running on the badge is Aiko, which is open source.
  • The software on the badge is available on the CCHS repository, also all open source.
  • The badges are designed to communicate over MQTT - a lightweight standard for messaging on IoT devices, but we are aware of privacy considerations: you don't want anybody able to control your badge from afar. The swagbadge protocol provides support for encrypted messages.
• Restart device
  • The first time you boot your device, it won't know how to talk to your network. If it can't detect a pre-existing set of network credentials, or connect to anything it knows about, it will establish a temporary access point and prompt you to navigate to it to enter your wifi details.
  • Note: Your device can only talk to a 2G network: it is not compatible with 5g.
  • This will look like ...
  • You can now restart your device
• On bootup you should now see...

Running pre-installed applications

• Pre-installed things, how to access and run them.

Extensions: Adding a SAO

• provided by others
• build your own (linky here to our docs)

Extensions: Updating the software framework

Between when we ship the board and when it arrives, there might be some changes to the software framework (Aiko). Here's how to update it.

• anaconda or equiv
  • conda create -n swagbadge python=3
  • conda activate swagbadge
• Get the latest version of the framework, Aiko for Micropython: git clone https://github.com/geekscape/aiko_engine_mp.git
• Get the latest version of the swagbadge applications, git clone swagbadge stuff
• Driving mpfshell
  • mpfshell lets you communicate with the ESP32. It provides a basic ftp-like capability to get files to and from the badge, as well as a shell, called REPL. This will let you see the log messages coming out of the badge as applications run on it.
  • pip install mpfshell
  • Unix:
    • mpfshell <some sort of path>
  • Windows:
    • mpfshell <com port>
    • How to find your com port: Use the Device Manager. Under the "Ports" entry, you'll see one or more entries. Hopefully one of which is your badge! It will tell you what Port it is on. If you can't see your badge, you might need to go up to the View menu and use "Show hidden devices" and see if that helps.
    • If nothing still shows up, you might need to update your USB drivers for comms support.
• Now you can push the new code onto the board
  • mpfshell <path/comport>
  • put source/file destination/file rinse repeat for every changed aiko/swagbadge file
  • exit when done.

Extensions: Software development

Whether you just want to do more things with the board as it comes, or you have a SAO addon you want to control, you might want to update the software.

• write code
• mpfshell to device
  • put <localpath/file> <remotepath/file>
  • repl
• push the reboot button on the lolin32
• watch the output go by - hopefully you don't see any errors!
• To get out of mpfshell
  • Press Ctrl-Q (or equivalent)
  • type exit