Swagbadge2021 GettingStarted

Getting started with the Swagbadge

Support

• The Swag Badge Spectrum chat is a place where the badge team hangs out, ready to answer your questions.

My package arrived in the mail, first steps.

• Your package should contain your badge, and some other goodies!
  • 
  • Badge
  • SAO headers (x 4)
  • SAO proto boards (x 2)
  • SAO tux board
  • Lanyard
  • Stickers
  • Instructions
• Take off the protective cases to reveal the screens.
• Powering it up
  • Insert a micro USB cable into the badge and connect the other end to a USB port on your computer or USB power source.
  • A green light should glow on the rear of the board, and a title appear across the two screens.
• Turning it on and off again
  • Plugging/unplugging it is fine. Usually the badge isn't running anything intensely enough that just unpowering it would cause a problem.
• On bootup, you should see:
  • The OLED screens will display "Aiko" and a version number as a title
  • It will also display something else to tell you to set up your wifi.

Getting it on your network

Getting the device on your wifi - wireless

The first time you boot your badge, it won't know how to talk to your wifi network, so it creates its own temporary wifi network for you to connect to, so you can configure it.

• Start your badge by plugging it in.
• The screens on your badge will say Configure WiFi:

• Use your phone (or computer) to change wifi networks to use the badge. The badge wifi name starts with aiko followed by some numbers/letters.

   -> 

• Once you're connected to the badge wifi, open a web browser on that device to the IP address shown on the screens. Something like http://192.168.4.1

• You'll be prompted to enter your wifi SSID and wifi password. Note: Your device can only use a 2.4GHz network: it is not compatible with 5GHz WiFi.
• The badge will restart using the credentials you've provided and it will shut down its wifi access point.

• Your phone/computer will go back to using its usual wifi network and badge is now online!

Note: If you are using an Android device to link the badge to your WiFi, it will pop up a dialog to say you are switching to a network that doesn't have Internet access and ask if you want to switch back. Select "Keep" to stay on the badge's temporary access point.

Getting the device on your wifi - commandline with mpfshell

If the above guide to setting up via the wifi AP (access point) doesn't work, you can put a configuration file onto the badge. You'll need a Python environment to do so, which you'll need anyway if you plan on writing your own badge software applications.

• Start by getting a copy of the aiko firmware, and installing mpfshell
• Note: Your device can only talk to a 2.4GHz network: it is not compatible with 5GHz.
• Edit aiko_engine_mp/configuration/net.py and insert the details of your SSID and password.
• use mpfshell: mpfshell -o COM3 (substitute the com port/tty of your badge)
• put configuration/net.py configuration/net.py
• fire up repl to view the console log
• You can now restart your device
• On bootup it should now talk to your network and you can see it on the console log.

Your badge will display its connection status on the screens.

Running pre-installed applications

Aiko's minimal Swagbadge application

At the moment the badge by default a basic "Swagbadge" application within the Aiko framework. This application

• has a thread to keep wifi running,
• has a thread to stay connected to (our Australian, private) mqtt server
• has a thread to display a rotating header across the two oleds.

You can now talk to your badge using MQTT messages.

Running other applications

At the moment, "swagbadge" is the only application that's for use with the badge.

There are other applications in the repo which are for other places the Aiko framework has been used.

If you've written an application of your own and want to run that by default on badge startup,

1. edit your local copy of configuration/main.py and change the value of the "application" to point to your new application.
2. using mpfshell, 'put' configuration/main.py and applications/your_application.py onto the badge
3. Restart the badge

Running example code

There is example code which has a number of examples in it, including a snake game and a demo of how to use various badge functions.

1. From your commandline on your computer, use mpfshell to put whatever example code you want onto the badge.
2. To run example code, you can use the "emergency stop" function to halt any other applications and put you in the repl.
   1. Touch both of the bottom spots on the sliders
   2. Reboot the badge
3. Now at the repl prompt, type (replace the name of the module as appropriate for the code you want to run):

Use examples.game_snake as example:

from examples.game_snake import run
run()

Use ctrl-c to halt operation and return to the repl prompt.

Hardware pinout

You can get the schematic and pin mapping on this page: https://github.com/CCHS-Melbourne/Swag-Badge/blob/master/Swag-Badge-2021/swag-badge-schematic.pdf

- GPIO0 : left breakout pin4 (can be VSPI CS/SS#1 if 2 SPI devices, otherwise wire CS to GND)
- GPIO2 : left breakout pin3 (can be VSPI CS/SS#2 if 2 SPI devices, otherwise wire CS to GND)

- GPIO4 : SCL (shared across all SAO connectors and the screens)
- GPIO5 : SDA (shared across all SAO connectors and the screens)
- GPIO12/15: slider #1
- GPIO13: left breakout pin3 (can be used for TFT backlight)
- GPIO14/27: slider #2
- GPIO16: left switch  (under screen #1)
- GPIO17: right switch (under screen #2)

- GPIO18: SAO3 pin3 + LB pin7  (also VSPI SCL/SCK/CLK/D0)
- GPIO23: SAO3 pin4            (also VSPI SDA/SDI/MOSI/D1)

- GPIO19: SAO1 pin4
- GPIO22: SAO1 pin3 (also onboard blue LED in the back)

- GPIO21: unused but not wired on this chip

- GPIO25: SAO4 pin4 + RB pin6  (also VSPI DC/A0/RS)
- GPIO26: SAO4 pin3 + RB pin7  (also VSPI RES/RST or RST can be wired to EN for auto)

- GPIO32: SAO2 pin3 + RB pin4 (touch pin, can be used with SAO tux foot or nose touchpad) 
- GPIO33: SAO2 pin4 + RB pin5 (touch pin, can be used with SAO tux foot or nose touchpad)

- GPIO34: right breakout pin2 (input only)
- GPIO35: right breakout pin3 (input only)

- GPIO36: unused but not wired on this chip (input only)
- GPIO39: unused but not wired on this chip (input only)

Using Hardware SPI for a device like SSD1331

ESP32 has 2 DMA capable hardware SPI busses usable by the user: SPI2/HSPI and SPI3/VSPI (see https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/peripherals/spi_master.html and https://github.com/espressif/arduino-esp32/blob/master/libraries/SPI/examples/SPI_Multiple_Buses/SPI_Multiple_Buses.ino for how to use them at the same time ). The important note in the espressif doc is that if you do not use the dedicated default HWSPI pins, they get routed through a hardware MUX and your maximum SPI speed is lowered from 80Mhz to 40Mhz.

If you would like to connect an SPI device like an SSD1331 96x64 color TFT, here are default hardware pin numbers, and pins you can use for non SPI signals (RES/RST, DC/A0/RS, and CS/SS):

  SD1331 Pin	        ESP32	ESP32
1 GND                   VSPI    HSPI 
2 VCC
3 SCL/SCK/CLK/D0	18	14   
4 SDA/SDI/MOSI/D1	23	13   
---- 2 pins above and MISO are HWSPI, pins below are anything
---- RST is not part of SPI, it's an out of band signal to reset a TFT
---- This could be wired to the ESP32 EN(reset) pin
5 RES/RST		26	26   
---- Data/Command pin is not part of SPI but used to tell the TFT if incoming SPI
---- data is actually a command, or pixel data.
6 DC/A0/RS (data)	25	25   
---- Cable select chooses which SPI device we're talking to, if there is only
---- one, it can be tied to ground. Any pin is fine
7 CS/SS => GND	        0	2   

---- MISO is not used to talk to TFTs, and is a hardware pin, but unused here
  MISO		        19	12    

pins 12/13/14 are already used by the badge, but 18/19/23 are usable (SAO3 and SAO1), and since MISO is unused, you could also assign it to GPIO21 which isn't wired at all on the lolin lite chip. If you'd also like to keep SAO4 usable (25/26), you can wire CS/SS to ground to free up pin 27, move DC/AO/RS to pin 27, and free up pin 26 (RST) by wiring RST to the ESP32 ENA pin, which should issue a TFT reset every time the ESP32 is reset.

End result: https://youtu.be/TYItVAa4tJY

Extensions: Adding a SAO

• provided by others: look at Tindie
• Build your own

Extensions: Writing your own applications

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. Or perhaps you're interested in writing your own applications?

• Updating the Software
• Writing your own badge programs