Difference between revisions of "Swagbadge2021 GettingStarted"

From Open Hardware Miniconf
Jump to: navigation, search
(My package arrived in the mail, first steps.)
 
(34 intermediate revisions by 4 users not shown)
Line 1: Line 1:
 
= Getting started with the Swagbadge =
 
= Getting started with the Swagbadge =
 +
 +
== Support ==
 +
* The [https://spectrum.chat/lca2021-swagbadge 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. ==
 
== My package arrived in the mail, first steps. ==
* Your package should contain your badge! [insert photo here]
+
* Your package should contain your badge, and some other goodies!  
 +
** [[File:swagbadgepackage.jpg|400px|alt=Image showing the contents of the swagbag package]]
 +
** 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.
 
* Take off the protective cases to reveal the screens.
 
* Powering it up
 
* Powering it up
Line 15: Line 26:
 
== Getting it on your network ==
 
== Getting it on your network ==
  
'''Safety precautions we have provided'''
+
=== Getting the device on your wifi - wireless ===
  
* 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 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.
* 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.
 
  
=== Getting the device on your wifi - wireless ===
+
* Start your badge by plugging it in.
 +
* The screens on your badge will say <code>Configure WiFi:</code>
 +
  [[File:configurewifi-1.png|300px]]
 +
* Use your phone (or computer) to change wifi networks to use the badge. The badge wifi name starts with <code>aiko</code> followed by some numbers/letters.
 +
  [[File:configurewifi-2.png|200px]] -> [[File:configurewifi-3.png|200px]]
 +
* 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 <code>http://192.168.4.1</code>
 +
  [[File:configurewifi-5.png|300px]]
 +
* 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.
 +
  [[File:configurewifi-4.png|300px]]
 +
* Your phone/computer will go back to using its usual wifi network and badge is now online!
  
* 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: 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.
* ''Note: Your device can only talk to a 2G network: it is not compatible with 5g.''
 
* The screens on your badge will say: <code>Configure WiFi: aiko1234a12341234. Try http://192.168.4.1</code>
 
* Use your phone or computer to connect to the wifi network on the badge. Its name starts with <code>aiko</code> followed by some numbers/letters.
 
* Once you're connected to the badge, open a web browser to the IP address on the screens. Something like <code>http://192.168.4.1</code>
 
* You'll be prompted to enter your wifi SSID and wifi password.
 
* Once you've saved that, the badge will restart using the credentials you've provided and it will shut down its wifi access point.
 
  
 
=== Getting the device on your wifi - commandline with mpfshell ===
 
=== Getting the device on your wifi - commandline with mpfshell ===
  
* If setting up via the wifi AP (access point) doesn't work, you can put a configuration file onto the badge.
+
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.
* You'll need to start by getting [[Swagbadge2021_UpdatingSoftware|a copy of the aiko firmware, and installing mpfshell]]
+
 
* ''Note: Your device can only talk to a 2G network: it is not compatible with 5g.''
+
* Start by getting [[Swagbadge2021_UpdatingSoftware|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.
 
* Edit aiko_engine_mp/configuration/net.py and insert the details of your SSID and password.
* use mpfshell: <code>mpfshell -o COM3</code>
+
* use mpfshell: <code>mpfshell -o COM3</code> (substitute the com port/tty of your badge)
 
* <code>put configuration/net.py configuration/net.py</code>
 
* <code>put configuration/net.py configuration/net.py</code>
 
* fire up repl to view the console log  
 
* fire up repl to view the console log  
Line 44: Line 57:
 
* On bootup it should now talk to your network and you can see it on the console log.
 
* On bootup it should now talk to your network and you can see it on the console log.
  
On bootup you should now see...
+
Your badge will display its connection status on the screens.
  
 
= Running pre-installed applications =
 
= Running pre-installed applications =
* Pre-installed things, how to access and run them.
+
 
 +
== 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 [[Swagbadge2021_MQTT|using MQTT messages]].
 +
 
 +
== Running other applications ==
 +
At the moment, "swagbadge" is the only application that's for use with the badge.
 +
 
 +
There are [https://github.com/geekscape/aiko_engine_mp/tree/master/applications 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,
 +
# edit your local copy of configuration/main.py and change the value of the "application" to point to your new application.
 +
# using mpfshell, 'put' configuration/main.py and applications/your_application.py onto the badge
 +
# Restart the badge
 +
 
 +
== Running example code ==
 +
There is [https://github.com/geekscape/aiko_engine_mp/tree/master/examples example code] which has a number of examples in it, including a snake game and a demo of how to use various badge functions.
 +
 
 +
# From your commandline on your computer, use mpfshell to put whatever example code you want onto the badge.
 +
# To run example code, you can use the "emergency stop" function to halt any other applications and put you in the repl.
 +
## Touch both of the bottom spots on the sliders
 +
## Reboot the badge
 +
# 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:
 +
<nowiki>
 +
from examples.game_snake import run
 +
run()
 +
</nowiki>
 +
 
 +
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
 +
<pre>
 +
- 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)
 +
</pre>
 +
 
 +
== 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):
 +
<pre>
 +
  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   
 +
</pre>
 +
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 =
 
= Extensions: Adding a SAO =
* provided by others
+
* provided by others: look at [https://www.tindie.com/search/?q=SAO Tindie]
* build your own (linky here to our docs)
+
* [[Swagbadge2021_SAO|Build your own]]
  
= Extensions: Updating the software framework =
+
= 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?  
 
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?  
  
[[Swagbadge2021_UpdatingSoftware|Updating the Software]]
+
* [[Swagbadge2021_UpdatingSoftware|Updating the Software]]
 +
* [[Swagbadge2021_SoftwareDev|Writing your own badge programs]]

Latest revision as of 02:20, 15 January 2022

Getting started with the Swagbadge

Support

My package arrived in the mail, first steps.

  • Your package should contain your badge, and some other goodies!
    • Image showing the contents of the swagbag package
    • 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:
  Configurewifi-1.png
  • 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.
  Configurewifi-2.png -> Configurewifi-3.png
  • 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
  Configurewifi-5.png
  • 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.
  Configurewifi-4.png
  • 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

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?