Open Hardware Miniconf - User contributions [en]

Swagbadge2021 GettingStarted

2021-02-13T04:46:01Z

Marcmerlin: /* Hardware pinout */

= 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. ==
* 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.
* 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 <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!

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 [[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.
* use mpfshell: <code>mpfshell -o COM3</code> (substitute the com port/tty of your badge)
* <code>put configuration/net.py configuration/net.py</code>
* 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 [[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-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 =
* provided by others: look at [https://www.tindie.com/search/?q=SAO Tindie]
* [[Swagbadge2021_SAO|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?

* [[Swagbadge2021_UpdatingSoftware|Updating the Software]]
* [[Swagbadge2021_SoftwareDev|Writing your own badge programs]]

Swagbadge2021 GettingStarted

2021-02-13T04:30:36Z

Marcmerlin: /* Using Hardware SPI for a device like SSD1331 */

= 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. ==
* 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.
* 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 <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!

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 [[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.
* use mpfshell: <code>mpfshell -o COM3</code> (substitute the com port/tty of your badge)
* <code>put configuration/net.py configuration/net.py</code>
* 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 [[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-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)

- 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 =
* provided by others: look at [https://www.tindie.com/search/?q=SAO Tindie]
* [[Swagbadge2021_SAO|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?

* [[Swagbadge2021_UpdatingSoftware|Updating the Software]]
* [[Swagbadge2021_SoftwareDev|Writing your own badge programs]]

Swagbadge2021 GettingStarted

2021-02-13T02:45:27Z

Marcmerlin: /* Hardware pinout */

= 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. ==
* 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.
* 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 <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!

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 [[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.
* use mpfshell: <code>mpfshell -o COM3</code> (substitute the com port/tty of your badge)
* <code>put configuration/net.py configuration/net.py</code>
* 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 [[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-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)

- 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 27 15

---- 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 =
* provided by others: look at [https://www.tindie.com/search/?q=SAO Tindie]
* [[Swagbadge2021_SAO|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?

* [[Swagbadge2021_UpdatingSoftware|Updating the Software]]
* [[Swagbadge2021_SoftwareDev|Writing your own badge programs]]

Swagbadge2021 GettingStarted

2021-02-13T02:44:35Z

Marcmerlin: /* Hardware pinout */

= 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. ==
* 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.
* 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 <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!

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 [[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.
* use mpfshell: <code>mpfshell -o COM3</code> (substitute the com port/tty of your badge)
* <code>put configuration/net.py configuration/net.py</code>
* 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 [[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-schematic.pdf
<pre>
- GPIO0 : left breakout pin4 (can be used as VSPI CS/SS#1 if 2 SPI devices, otherwise CS can be wired to GND)
- GPIO2 : left breakout pin3 (can be used as VSPI CS/SS#2 if 2 SPI devices, otherwise CS can be wired 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)

- 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 27 15

---- 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 =
* provided by others: look at [https://www.tindie.com/search/?q=SAO Tindie]
* [[Swagbadge2021_SAO|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?

* [[Swagbadge2021_UpdatingSoftware|Updating the Software]]
* [[Swagbadge2021_SoftwareDev|Writing your own badge programs]]

Swagbadge2021 GettingStarted

2021-02-08T05:37:35Z

Marcmerlin: /* Hardware pinout */

= 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. ==
* 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.
* 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 <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!

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 [[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.
* use mpfshell: <code>mpfshell -o COM3</code> (substitute the com port/tty of your badge)
* <code>put configuration/net.py configuration/net.py</code>
* 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 [[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-schematic.pdf
<pre>
- GPIO0 : left breakout pin4
- GPIO2 : left breakout pin3

- 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
- GPIO14/27: slider #2 (can be used as VSPI CS/SS#2 and #1 of if one SPI device only, CS is wired to GND)
- 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)

- 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 27 15

---- 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 =
* provided by others: look at [https://www.tindie.com/search/?q=SAO Tindie]
* [[Swagbadge2021_SAO|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?

* [[Swagbadge2021_UpdatingSoftware|Updating the Software]]
* [[Swagbadge2021_SoftwareDev|Writing your own badge programs]]

Swagbadge2021 GettingStarted

2021-02-08T05:35:30Z

Marcmerlin: /* Using Hardware SPI for a device like SSD1331 */

= 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. ==
* 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.
* 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 <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!

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 [[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.
* use mpfshell: <code>mpfshell -o COM3</code> (substitute the com port/tty of your badge)
* <code>put configuration/net.py configuration/net.py</code>
* 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 [[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-schematic.pdf
<pre>
- GPIO0 : left breakout pin4
- GPIO2 : left breakout pin3

- 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
- GPIO14/27: slider #2 (can be used as VSPI CS/SS#2 and #1 of if one SPI device only, CS is wired to GND)
- 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)

- GPIO27: free (pin available on the chip, not routed anywhere)

- 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 27 15

---- 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 =
* provided by others: look at [https://www.tindie.com/search/?q=SAO Tindie]
* [[Swagbadge2021_SAO|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?

* [[Swagbadge2021_UpdatingSoftware|Updating the Software]]
* [[Swagbadge2021_SoftwareDev|Writing your own badge programs]]

Swagbadge2021 GettingStarted

2021-02-08T05:31:36Z

Marcmerlin: /* Hardware pinout */

= 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. ==
* 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.
* 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 <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!

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 [[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.
* use mpfshell: <code>mpfshell -o COM3</code> (substitute the com port/tty of your badge)
* <code>put configuration/net.py configuration/net.py</code>
* 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 [[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-schematic.pdf
<pre>
- GPIO0 : left breakout pin4
- GPIO2 : left breakout pin3

- 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
- GPIO14/27: slider #2 (can be used as VSPI CS/SS#2 and #1 of if one SPI device only, CS is wired to GND)
- 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)

- GPIO27: free (pin available on the chip, not routed anywhere)

- 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 27 15

---- 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, 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 [https://www.tindie.com/search/?q=SAO Tindie]
* [[Swagbadge2021_SAO|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?

* [[Swagbadge2021_UpdatingSoftware|Updating the Software]]
* [[Swagbadge2021_SoftwareDev|Writing your own badge programs]]

Swagbadge2021 MQTT

2021-01-23T22:08:14Z

Marcmerlin: /* Making your badge perform */

= About MQTT =

MQTT is a lightweight message platform that uses individual topics (like a slack channel) that people can send messages to (called publishing) or listen for messages on (called subscribing).

MQTT is designed for use on IoT devices. Check out [https://en.wikipedia.org/wiki/MQTT Wikipedia] for some background or [https://mqtt.org/ mqtt.org] for more information on it generally.

== About the LCA Swagbadge MQTT server ==

The badges have MQTT configured to talk to a dedicated server hosted by Andy Gelme, one of the OHMC organisers. We have done this for security and privacy reasons, and because it gives us an Australian server so it's faster.

This server is at <code>101.181.46.180</code>, the configuration for which is held on the badge at [https://github.com/geekscape/aiko_engine_mp/blob/master/configuration/mqtt.py configuration/mqtt.py]. The server has some special features:
* The ''upgrade/'' topic path prefix is public read: only Jon and Andy can update it.
* The ''aiko/'' topic path prefix is public read/write
* The ''public/'' topic path prefix is available for everyone to read/write
* The ''secret/'' topic path prefix is write-only
* We have some server monitoring to look for things snooping for all the channels, or who aren't using aiko/on a badge, and mitigations in the event a badge goes beserk and starts a spamming DOS attack.

You are welcome to change which MQTT server your badge uses, by updating the mqtt.py configuration file. Some publicly hosted alternatives are provided (commented out) in the config.

= Controlling your badge over MQTT =

== Making your badge perform ==

The easiest thing to do is send messages to show up on your screens.

# Install an mqtt client on your machine
# Connect to the mqtt server (if you forget what it is, the IP address is shown on bootup)
# Using your badge's topic (public/esp32_your_badge_id/0/in) send it a message

Messages are usually in the form of <code>(component:command arguments)</code>.

<code>
mosquitto_sub -h 101.181.46.180 -t public/esp32_id/0/# (will receive messages output by the badge like "(boot v04 swagbadge)")

mosquitto_sub -h 101.181.46.180 -t public/esp32_id/# (shows message sent to the badge)

mosquitto_sub -h 101.181.46.180 -t public/# (show all messages for all badges)

mosquitto_pub -h 101.181.46.180 -t public/esp32_id/0/in -m "(oled:clear)"

mosquitto_pub -h 101.181.46.180 -t public/esp32_id/0/in -m "(oled:pixel 64 32)"

mosquitto_pub -h 101.181.46.180 -t public/esp32_id/0/in -m "(oled:text 0 50 Hello World)"
</code>

=== OLED messages ===
;(oled:clear)
: clears both screens
;(oled:log Hello World!)
: writes a message along the bottom of the screens, scrolling up whatever is there out of the way
; (oled:pixel x y)
: lights a pixel at that spot
; (oled:text x y This is a test !)
: Puts some text at the position x,y. It will be displayed over the top of whatever's there.

If you'd like to make your application MQTT aware, take a look at the [https://github.com/geekscape/aiko_engine_mp/blob/master/lib/aiko/oled.py oled code].

= Using MQTT on your badge =

== Over Aiko ==

Aiko has some convenience handlers to make using MQTT easier.

Behind the scenes, Aiko routes messages to the specific handlers matching a given topic and supports multiple handlers “listening” to various specific topics. There is an exception handler wrapped around every message handler, so that the overall MQTT thread doesn’t fail.

=== Receiving a message and taking action ===

'''Subscribe to a topic'''
Update ''configuration/mqtt.py'' and add in the topic to the <code>topic_subscribe</code> list
"topic_subscribe": [ "$me/in", "$me/exec", upgrade_topic, "YOUR_TOPIC" ],

If you want to listen/subscribe to all sub-topics, use a <code>#</code> at the end. For example <code>public/chocolate/#</code> will listen to public/chocolate and public/chocolate/lindt and public/chocolate/kokoblack and public/chocolate/ganache

See https://github.com/geekscape/aiko_engine_mp/blob/master/configuration/mqtt.py#L13 as well as line 132 and 63

'''Handle messages on that topic'''

Define a message handler function, which takes a topic argument (in case you use the same message handler for multiple topics), and the payload (the message that was seen)
def on_message(topic, payload_in):
print(topic + ": " + payload_in)

Add this handler function to the MQTT client: this is typically done in your application's initialise() method.
mqtt.add_message_handler(on_message, "YOUR_TOPIC")

'''Example code'''

Here is a complete application example … https://github.com/geekscape/aiko_engine_mp/blob/master/applications/step_controller.py

In this case, Aiko’s general MQTT on_message() handler will route all incoming messages to the specific handlers matching a given topic and supports multiple handlers “listening” to various specific topics. There is an exception handler wrapped around every message handler … so that the MQTT thread doesn’t fail. And over time Aiko’s error handling will improve, e.g re-subscribe to all MQTT topics on reconnection, etc. At some point, Aiko will provide the heavy lifting for encrypted message publish / subscribe. Finally, once Aiko Services (a general purpose distributed / embedded system) is released, then our ESP32 devices can become first-class citizens of a broader distributed service-based network (perhaps a month or so away). Aiko also supports some “dangerous” fun, like opt-in enabling receiving microPython code as an MQTT message and executing it (obviously this is dangerous)

=== Publishing a message ===

Use the aiko mqtt client object to send a message.

from aiko.mqtt import client
client.publish(topic, message)

Which topic to use? On our LCA server, we are constrained to only use the 'public' and 'aiko' prefixed topics.

To keep things neat and orderly, we recommend using
;public/esp32_SERIAL_ID/YOUR_TOPIC_HERE: for topics specific to your personal swagbadge
;public/SUBJECT/YOUR_TOPIC_HERE: for topics intended to share information with multiple swagbadges

== Going direct to MQTT ==

Since Aiko already makes an MQTT connection (to our server), you don’t need to make another MQTT connect, unless you want to interact with multiple MQTT servers (beyond the MQTT server already configured in ''configuration/mqtt.py''.

You can use the Aiko MQTT client object reference to access any of the MQTT library functions …
>>> import aiko.mqtt.client as mqttclient
>>> help(aiko.mqtt.client)

[https://github.com/geekscape/aiko_engine_mp/blob/master/lib/umqtt/simple.py All of the available MQTT Client functions]

=== MQTT message publishing ===

you can always use the Aiko MQTT client object to publish messages to any topic … to which you have access permission.
On our MQTT server, that is read / write access to aiko/# and public/#. By default, each #swagbadge will be using public/esp32_SERIAL_ID/0/# as their own topic path prefix and using specific topic paths under that, e.g public/esp32_SERIAL_ID/0/in (all #swagbadges subscribe to that topic path aka $me/in … where Aiko substitutes the topic path prefix for $me) and publish on public/esp32_SERIAL_ID/0/out:
<pre>
aiko.mqtt.client.publish(topic, payload)
</pre>

So for example, you could use:
* public/esp32_SERIAL_ID/WHATEVER_YOU_LIKE … recommended for topics specific to interacting with your #swagbadge
* public/nicola/WHATEVER_YOU_LIKE … recommended for topics where you’d like to share information with a bunch of #swagbadges, i.e not specific to your #swagbadge

It doesn’t matter too much apart from being tidy and organised. If everyone follows reasonable conventions, then it is more orderly, e.g like taking care of a filesystem layout.

= Encrypting messages with your badge =

Placeholder text.

Swagbadge2021 MQTT

2021-01-23T21:46:23Z

Marcmerlin: /* Controlling your badge over MQTT */

= About MQTT =

MQTT is a lightweight message platform that uses individual topics (like a slack channel) that people can send messages to (called publishing) or listen for messages on (called subscribing).

MQTT is designed for use on IoT devices. Check out [https://en.wikipedia.org/wiki/MQTT Wikipedia] for some background or [https://mqtt.org/ mqtt.org] for more information on it generally.

== About the LCA Swagbadge MQTT server ==

The badges have MQTT configured to talk to a dedicated server hosted by Andy Gelme, one of the OHMC organisers. We have done this for security and privacy reasons, and because it gives us an Australian server so it's faster.

This server is at <code>101.181.46.180</code>, the configuration for which is held on the badge at [https://github.com/geekscape/aiko_engine_mp/blob/master/configuration/mqtt.py configuration/mqtt.py]. The server has some special features:
* The ''upgrade/'' topic path prefix is public read: only Jon and Andy can update it.
* The ''aiko/'' topic path prefix is public read/write
* The ''public/'' topic path prefix is available for everyone to read/write
* The ''secret/'' topic path prefix is write-only
* We have some server monitoring to look for things snooping for all the channels, or who aren't using aiko/on a badge, and mitigations in the event a badge goes beserk and starts a spamming DOS attack.

You are welcome to change which MQTT server your badge uses, by updating the mqtt.py configuration file. Some publicly hosted alternatives are provided (commented out) in the config.

= Controlling your badge over MQTT =

== Making your badge perform ==

The easiest thing to do is send messages to show up on your screens.

# Install an mqtt client on your machine
# Connect to the mqtt server (if you forget what it is, the IP address is shown on bootup)
# Using your badge's topic (public/esp32_your_badge_id/0/in) send it a message

Messages are usually in the form of <code>(component:command arguments)</code>.

<code>
mosquitto_sub -h 101.181.46.180 -t public/esp32_id/0/out (may receive messages output by the badge)

mosquitto_sub -h 101.181.46.180 -t public/esp32_id/# (shows message sent to the badge)

mosquitto_sub -h 101.181.46.180 -t public/# (show all messages for all badges)

mosquitto_pub -h 101.181.46.180 -t public/esp32_id/0/in -m "(oled:clear)"

mosquitto_pub -h 101.181.46.180 -t public/esp32_id/0/in -m "(oled:pixel 64 32)"

mosquitto_pub -h 101.181.46.180 -t public/esp32_id/0/in -m "(oled:text 0 50 Hello World)"
</code>

=== OLED messages ===
;(oled:clear)
: clears both screens
;(oled:log Hello World!)
: writes a message along the bottom of the screens, scrolling up whatever is there out of the way
; (oled:pixel x y)
: lights a pixel at that spot
; (oled:text x y This is a test !)
: Puts some text at the position x,y. It will be displayed over the top of whatever's there.

If you'd like to make your application MQTT aware, take a look at the [https://github.com/geekscape/aiko_engine_mp/blob/master/lib/aiko/oled.py oled code].

= Using MQTT on your badge =

== Over Aiko ==

Aiko has some convenience handlers to make using MQTT easier.

Behind the scenes, Aiko routes messages to the specific handlers matching a given topic and supports multiple handlers “listening” to various specific topics. There is an exception handler wrapped around every message handler, so that the overall MQTT thread doesn’t fail.

=== Receiving a message and taking action ===

'''Subscribe to a topic'''
Update ''configuration/mqtt.py'' and add in the topic to the <code>topic_subscribe</code> list
"topic_subscribe": [ "$me/in", "$me/exec", upgrade_topic, "YOUR_TOPIC" ],

If you want to listen/subscribe to all sub-topics, use a <code>#</code> at the end. For example <code>public/chocolate/#</code> will listen to public/chocolate and public/chocolate/lindt and public/chocolate/kokoblack and public/chocolate/ganache

See https://github.com/geekscape/aiko_engine_mp/blob/master/configuration/mqtt.py#L13 as well as line 132 and 63

'''Handle messages on that topic'''

Define a message handler function, which takes a topic argument (in case you use the same message handler for multiple topics), and the payload (the message that was seen)
def on_message(topic, payload_in):
print(topic + ": " + payload_in)

Add this handler function to the MQTT client: this is typically done in your application's initialise() method.
mqtt.add_message_handler(on_message, "YOUR_TOPIC")

'''Example code'''

Here is a complete application example … https://github.com/geekscape/aiko_engine_mp/blob/master/applications/step_controller.py

In this case, Aiko’s general MQTT on_message() handler will route all incoming messages to the specific handlers matching a given topic and supports multiple handlers “listening” to various specific topics. There is an exception handler wrapped around every message handler … so that the MQTT thread doesn’t fail. And over time Aiko’s error handling will improve, e.g re-subscribe to all MQTT topics on reconnection, etc. At some point, Aiko will provide the heavy lifting for encrypted message publish / subscribe. Finally, once Aiko Services (a general purpose distributed / embedded system) is released, then our ESP32 devices can become first-class citizens of a broader distributed service-based network (perhaps a month or so away). Aiko also supports some “dangerous” fun, like opt-in enabling receiving microPython code as an MQTT message and executing it (obviously this is dangerous)

=== Publishing a message ===

Use the aiko mqtt client object to send a message.

from aiko.mqtt import client
client.publish(topic, message)

Which topic to use? On our LCA server, we are constrained to only use the 'public' and 'aiko' prefixed topics.

To keep things neat and orderly, we recommend using
;public/esp32_SERIAL_ID/YOUR_TOPIC_HERE: for topics specific to your personal swagbadge
;public/SUBJECT/YOUR_TOPIC_HERE: for topics intended to share information with multiple swagbadges

== Going direct to MQTT ==

Since Aiko already makes an MQTT connection (to our server), you don’t need to make another MQTT connect, unless you want to interact with multiple MQTT servers (beyond the MQTT server already configured in ''configuration/mqtt.py''.

You can use the Aiko MQTT client object reference to access any of the MQTT library functions …
>>> import aiko.mqtt.client as mqttclient
>>> help(aiko.mqtt.client)

[https://github.com/geekscape/aiko_engine_mp/blob/master/lib/umqtt/simple.py All of the available MQTT Client functions]

=== MQTT message publishing ===

you can always use the Aiko MQTT client object to publish messages to any topic … to which you have access permission.
On our MQTT server, that is read / write access to aiko/# and public/#. By default, each #swagbadge will be using public/esp32_SERIAL_ID/0/# as their own topic path prefix and using specific topic paths under that, e.g public/esp32_SERIAL_ID/0/in (all #swagbadges subscribe to that topic path aka $me/in … where Aiko substitutes the topic path prefix for $me) and publish on public/esp32_SERIAL_ID/0/out:
<pre>
aiko.mqtt.client.publish(topic, payload)
</pre>

So for example, you could use:
* public/esp32_SERIAL_ID/WHATEVER_YOU_LIKE … recommended for topics specific to interacting with your #swagbadge
* public/nicola/WHATEVER_YOU_LIKE … recommended for topics where you’d like to share information with a bunch of #swagbadges, i.e not specific to your #swagbadge

It doesn’t matter too much apart from being tidy and organised. If everyone follows reasonable conventions, then it is more orderly, e.g like taking care of a filesystem layout.

= Encrypting messages with your badge =

Placeholder text.

Swagbadge2021 MQTT

2021-01-23T21:31:50Z

Marcmerlin: /* Going direct to MQTT */

= About MQTT =

MQTT is a lightweight message platform that uses individual topics (like a slack channel) that people can send messages to (called publishing) or listen for messages on (called subscribing).

MQTT is designed for use on IoT devices. Check out [https://en.wikipedia.org/wiki/MQTT Wikipedia] for some background or [https://mqtt.org/ mqtt.org] for more information on it generally.

== About the LCA Swagbadge MQTT server ==

The badges have MQTT configured to talk to a dedicated server hosted by Andy Gelme, one of the OHMC organisers. We have done this for security and privacy reasons, and because it gives us an Australian server so it's faster.

This server is at <code>101.181.46.180</code>, the configuration for which is held on the badge at [https://github.com/geekscape/aiko_engine_mp/blob/master/configuration/mqtt.py configuration/mqtt.py]. The server has some special features:
* The ''upgrade/'' topic path prefix is public read: only Jon and Andy can update it.
* The ''aiko/'' topic path prefix is public read/write
* The ''public/'' topic path prefix is available for everyone to read/write
* The ''secret/'' topic path prefix is write-only
* We have some server monitoring to look for things snooping for all the channels, or who aren't using aiko/on a badge, and mitigations in the event a badge goes beserk and starts a spamming DOS attack.

You are welcome to change which MQTT server your badge uses, by updating the mqtt.py configuration file. Some publicly hosted alternatives are provided (commented out) in the config.

= Controlling your badge over MQTT =

== Making your badge perform ==

The easiest thing to do is send messages to show up on your screens.

# Install an mqtt client on your machine
# Connect to the mqtt server (if you forget what it is, the IP address is shown on bootup)
# Using your badge's topic (public/esp32_your_badge_id/0/in) send it a message

Messages are usually in the form of <code>(component:command arguments)</code>.

<code>
mosquitto_sub -h 101.181.46.180 -t public/esp32_id/0 & << does this receive anything?

mosquitto_pub -h 101.181.46.180 -t public/esp32_id/0/in -m "(oled:clear)"

mosquitto_pub -h 101.181.46.180 -t public/esp32_id/0/in -m "(oled:pixel 64 32)"

mosquitto_pub -h 101.181.46.180 -t public/esp32_id/0/in -m "(oled:text 0 50 Hello World)"
</code>

=== OLED messages ===
;(oled:clear)
: clears both screens
;(oled:log Hello World!)
: writes a message along the bottom of the screens, scrolling up whatever is there out of the way
; (oled:pixel x y)
: lights a pixel at that spot
; (oled:text x y This is a test !)
: Puts some text at the position x,y. It will be displayed over the top of whatever's there.

If you'd like to make your application MQTT aware, take a look at the [https://github.com/geekscape/aiko_engine_mp/blob/master/lib/aiko/oled.py oled code].

= Using MQTT on your badge =

== Over Aiko ==

Aiko has some convenience handlers to make using MQTT easier.

Behind the scenes, Aiko routes messages to the specific handlers matching a given topic and supports multiple handlers “listening” to various specific topics. There is an exception handler wrapped around every message handler, so that the overall MQTT thread doesn’t fail.

=== Receiving a message and taking action ===

'''Subscribe to a topic'''
Update ''configuration/mqtt.py'' and add in the topic to the <code>topic_subscribe</code> list
"topic_subscribe": [ "$me/in", "$me/exec", upgrade_topic, "YOUR_TOPIC" ],

If you want to listen/subscribe to all sub-topics, use a <code>#</code> at the end. For example <code>public/chocolate/#</code> will listen to public/chocolate and public/chocolate/lindt and public/chocolate/kokoblack and public/chocolate/ganache

See https://github.com/geekscape/aiko_engine_mp/blob/master/configuration/mqtt.py#L13 as well as line 132 and 63

'''Handle messages on that topic'''

Define a message handler function, which takes a topic argument (in case you use the same message handler for multiple topics), and the payload (the message that was seen)
def on_message(topic, payload_in):
print(topic + ": " + payload_in)

Add this handler function to the MQTT client: this is typically done in your application's initialise() method.
mqtt.add_message_handler(on_message, "YOUR_TOPIC")

'''Example code'''

Here is a complete application example … https://github.com/geekscape/aiko_engine_mp/blob/master/applications/step_controller.py

In this case, Aiko’s general MQTT on_message() handler will route all incoming messages to the specific handlers matching a given topic and supports multiple handlers “listening” to various specific topics. There is an exception handler wrapped around every message handler … so that the MQTT thread doesn’t fail. And over time Aiko’s error handling will improve, e.g re-subscribe to all MQTT topics on reconnection, etc. At some point, Aiko will provide the heavy lifting for encrypted message publish / subscribe. Finally, once Aiko Services (a general purpose distributed / embedded system) is released, then our ESP32 devices can become first-class citizens of a broader distributed service-based network (perhaps a month or so away). Aiko also supports some “dangerous” fun, like opt-in enabling receiving microPython code as an MQTT message and executing it (obviously this is dangerous)

=== Publishing a message ===

Use the aiko mqtt client object to send a message.

from aiko.mqtt import client
client.publish(topic, message)

Which topic to use? On our LCA server, we are constrained to only use the 'public' and 'aiko' prefixed topics.

To keep things neat and orderly, we recommend using
;public/esp32_SERIAL_ID/YOUR_TOPIC_HERE: for topics specific to your personal swagbadge
;public/SUBJECT/YOUR_TOPIC_HERE: for topics intended to share information with multiple swagbadges

== Going direct to MQTT ==

Since Aiko already makes an MQTT connection (to our server), you don’t need to make another MQTT connect, unless you want to interact with multiple MQTT servers (beyond the MQTT server already configured in ''configuration/mqtt.py''.

You can use the Aiko MQTT client object reference to access any of the MQTT library functions …
>>> import aiko.mqtt.client as mqttclient
>>> help(aiko.mqtt.client)

[https://github.com/geekscape/aiko_engine_mp/blob/master/lib/umqtt/simple.py All of the available MQTT Client functions]

=== MQTT message publishing ===

you can always use the Aiko MQTT client object to publish messages to any topic … to which you have access permission.
On our MQTT server, that is read / write access to aiko/# and public/#. By default, each #swagbadge will be using public/esp32_SERIAL_ID/0/# as their own topic path prefix and using specific topic paths under that, e.g public/esp32_SERIAL_ID/0/in (all #swagbadges subscribe to that topic path aka $me/in … where Aiko substitutes the topic path prefix for $me) and publish on public/esp32_SERIAL_ID/0/out:
<pre>
aiko.mqtt.client.publish(topic, payload)
</pre>

So for example, you could use:
* public/esp32_SERIAL_ID/WHATEVER_YOU_LIKE … recommended for topics specific to interacting with your #swagbadge
* public/nicola/WHATEVER_YOU_LIKE … recommended for topics where you’d like to share information with a bunch of #swagbadges, i.e not specific to your #swagbadge

It doesn’t matter too much apart from being tidy and organised. If everyone follows reasonable conventions, then it is more orderly, e.g like taking care of a filesystem layout.

= Encrypting messages with your badge =

Placeholder text.

Swagbadge2021 MQTT

2021-01-23T21:19:05Z

Marcmerlin: /* Receiving a message and taking action */

= About MQTT =

MQTT is a lightweight message platform that uses individual topics (like a slack channel) that people can send messages to (called publishing) or listen for messages on (called subscribing).

MQTT is designed for use on IoT devices. Check out [https://en.wikipedia.org/wiki/MQTT Wikipedia] for some background or [https://mqtt.org/ mqtt.org] for more information on it generally.

== About the LCA Swagbadge MQTT server ==

The badges have MQTT configured to talk to a dedicated server hosted by Andy Gelme, one of the OHMC organisers. We have done this for security and privacy reasons, and because it gives us an Australian server so it's faster.

This server is at <code>101.181.46.180</code>, the configuration for which is held on the badge at [https://github.com/geekscape/aiko_engine_mp/blob/master/configuration/mqtt.py configuration/mqtt.py]. The server has some special features:
* The ''upgrade/'' topic path prefix is public read: only Jon and Andy can update it.
* The ''aiko/'' topic path prefix is public read/write
* The ''public/'' topic path prefix is available for everyone to read/write
* The ''secret/'' topic path prefix is write-only
* We have some server monitoring to look for things snooping for all the channels, or who aren't using aiko/on a badge, and mitigations in the event a badge goes beserk and starts a spamming DOS attack.

You are welcome to change which MQTT server your badge uses, by updating the mqtt.py configuration file. Some publicly hosted alternatives are provided (commented out) in the config.

= Controlling your badge over MQTT =

== Making your badge perform ==

The easiest thing to do is send messages to show up on your screens.

# Install an mqtt client on your machine
# Connect to the mqtt server (if you forget what it is, the IP address is shown on bootup)
# Using your badge's topic (public/esp32_your_badge_id/0/in) send it a message

Messages are usually in the form of <code>(component:command arguments)</code>.

<code>
mosquitto_sub -h 101.181.46.180 -t public/esp32_id/0 & << does this receive anything?

mosquitto_pub -h 101.181.46.180 -t public/esp32_id/0/in -m "(oled:clear)"

mosquitto_pub -h 101.181.46.180 -t public/esp32_id/0/in -m "(oled:pixel 64 32)"

mosquitto_pub -h 101.181.46.180 -t public/esp32_id/0/in -m "(oled:text 0 50 Hello World)"
</code>

=== OLED messages ===
;(oled:clear)
: clears both screens
;(oled:log Hello World!)
: writes a message along the bottom of the screens, scrolling up whatever is there out of the way
; (oled:pixel x y)
: lights a pixel at that spot
; (oled:text x y This is a test !)
: Puts some text at the position x,y. It will be displayed over the top of whatever's there.

If you'd like to make your application MQTT aware, take a look at the [https://github.com/geekscape/aiko_engine_mp/blob/master/lib/aiko/oled.py oled code].

= Using MQTT on your badge =

== Over Aiko ==

Aiko has some convenience handlers to make using MQTT easier.

Behind the scenes, Aiko routes messages to the specific handlers matching a given topic and supports multiple handlers “listening” to various specific topics. There is an exception handler wrapped around every message handler, so that the overall MQTT thread doesn’t fail.

=== Receiving a message and taking action ===

'''Subscribe to a topic'''
Update ''configuration/mqtt.py'' and add in the topic to the <code>topic_subscribe</code> list
"topic_subscribe": [ "$me/in", "$me/exec", upgrade_topic, "YOUR_TOPIC" ],

If you want to listen/subscribe to all sub-topics, use a <code>#</code> at the end. For example <code>public/chocolate/#</code> will listen to public/chocolate and public/chocolate/lindt and public/chocolate/kokoblack and public/chocolate/ganache

See https://github.com/geekscape/aiko_engine_mp/blob/master/configuration/mqtt.py#L13 as well as line 132 and 63

'''Handle messages on that topic'''

Define a message handler function, which takes a topic argument (in case you use the same message handler for multiple topics), and the payload (the message that was seen)
def on_message(topic, payload_in):
print(topic + ": " + payload_in)

Add this handler function to the MQTT client: this is typically done in your application's initialise() method.
mqtt.add_message_handler(on_message, "YOUR_TOPIC")

'''Example code'''

Here is a complete application example … https://github.com/geekscape/aiko_engine_mp/blob/master/applications/step_controller.py

In this case, Aiko’s general MQTT on_message() handler will route all incoming messages to the specific handlers matching a given topic and supports multiple handlers “listening” to various specific topics. There is an exception handler wrapped around every message handler … so that the MQTT thread doesn’t fail. And over time Aiko’s error handling will improve, e.g re-subscribe to all MQTT topics on reconnection, etc. At some point, Aiko will provide the heavy lifting for encrypted message publish / subscribe. Finally, once Aiko Services (a general purpose distributed / embedded system) is released, then our ESP32 devices can become first-class citizens of a broader distributed service-based network (perhaps a month or so away). Aiko also supports some “dangerous” fun, like opt-in enabling receiving microPython code as an MQTT message and executing it (obviously this is dangerous)

=== Publishing a message ===

Use the aiko mqtt client object to send a message.

from aiko.mqtt import client
client.publish(topic, message)

Which topic to use? On our LCA server, we are constrained to only use the 'public' and 'aiko' prefixed topics.

To keep things neat and orderly, we recommend using
;public/esp32_SERIAL_ID/YOUR_TOPIC_HERE: for topics specific to your personal swagbadge
;public/SUBJECT/YOUR_TOPIC_HERE: for topics intended to share information with multiple swagbadges

== Going direct to MQTT ==

Since Aiko already makes an MQTT connection (to our server), you don’t need to make another MQTT connect, unless you want to interact with multiple MQTT servers (beyond the MQTT server already configured in ''configuration/mqtt.py''.

You can use the Aiko MQTT client object reference to access any of the MQTT library functions …
>>> import aiko.mqtt.client as mqttclient
>>> help(aiko.mqtt.client)

[https://github.com/geekscape/aiko_engine_mp/blob/master/lib/umqtt/simple.py All of the available MQTT Client functions]

= Encrypting messages with your badge =

Placeholder text.

Swagbadge2021 GettingStarted

2021-01-23T20:59:50Z

Marcmerlin: /* Using Hardware SPI for a device like SSD1331 */

= 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. ==
* 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.
* 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 <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!

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 [[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.
* use mpfshell: <code>mpfshell -o COM3</code> (substitute the com port/tty of your badge)
* <code>put configuration/net.py configuration/net.py</code>
* 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 [[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-schematic.pdf
<pre>
- GPIO0 : left breakout pin4
- GPIO2 : left breakout pin3

- 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
- GPIO14/27: slider #2
- GPIO16: left switch (under screen #1)
- GPIO17: right switch (under screen #2)

- GPIO18: SAO3 pin3 + LB pin7
- GPIO23: SAO3 pin4

- 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
- GPIO26: SAO4 pin3 + RB pin7

- GPIO27: free (pin available on the chip, not routed anywhere)

- 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 27 15

---- 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, 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
* build your own (linky here to our docs)

= 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?

* [[Swagbadge2021_UpdatingSoftware|Updating the Software]]
* [[Swagbadge2021_SoftwareDev|Writing your own badge programs]]

Swagbadge2021 GettingStarted

2021-01-23T20:57:52Z

Marcmerlin: /* Using Hardware SPI for a device like SSD1331 */

= 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. ==
* 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.
* 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 <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!

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 [[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.
* use mpfshell: <code>mpfshell -o COM3</code> (substitute the com port/tty of your badge)
* <code>put configuration/net.py configuration/net.py</code>
* 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 [[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-schematic.pdf
<pre>
- GPIO0 : left breakout pin4
- GPIO2 : left breakout pin3

- 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
- GPIO14/27: slider #2
- GPIO16: left switch (under screen #1)
- GPIO17: right switch (under screen #2)

- GPIO18: SAO3 pin3 + LB pin7
- GPIO23: SAO3 pin4

- 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
- GPIO26: SAO4 pin3 + RB pin7

- GPIO27: free (pin available on the chip, not routed anywhere)

- 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 27 15

---- 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, 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.

= Extensions: Adding a SAO =
* provided by others
* build your own (linky here to our docs)

= 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?

* [[Swagbadge2021_UpdatingSoftware|Updating the Software]]
* [[Swagbadge2021_SoftwareDev|Writing your own badge programs]]

Swagbadge2021 GettingStarted

2021-01-23T20:57:00Z

Marcmerlin: /* Using Hardware SPI for a device like SSD1331 */

= 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. ==
* 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.
* 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 <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!

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 [[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.
* use mpfshell: <code>mpfshell -o COM3</code> (substitute the com port/tty of your badge)
* <code>put configuration/net.py configuration/net.py</code>
* 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 [[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-schematic.pdf
<pre>
- GPIO0 : left breakout pin4
- GPIO2 : left breakout pin3

- 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
- GPIO14/27: slider #2
- GPIO16: left switch (under screen #1)
- GPIO17: right switch (under screen #2)

- GPIO18: SAO3 pin3 + LB pin7
- GPIO23: SAO3 pin4

- 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
- GPIO26: SAO4 pin3 + RB pin7

- GPIO27: free (pin available on the chip, not routed anywhere)

- 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
<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 27 15

---- 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, 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.

= Extensions: Adding a SAO =
* provided by others
* build your own (linky here to our docs)

= 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?

* [[Swagbadge2021_UpdatingSoftware|Updating the Software]]
* [[Swagbadge2021_SoftwareDev|Writing your own badge programs]]

Swagbadge2021 GettingStarted

2021-01-23T20:31:46Z

Marcmerlin: /* Using Hardware SPI for a device like SSD1331 */

= 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. ==
* 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.
* 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 <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!

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 [[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.
* use mpfshell: <code>mpfshell -o COM3</code> (substitute the com port/tty of your badge)
* <code>put configuration/net.py configuration/net.py</code>
* 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 [[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-schematic.pdf
<pre>
- GPIO0 : left breakout pin4
- GPIO2 : left breakout pin3

- 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
- GPIO14/27: slider #2
- GPIO16: left switch (under screen #1)
- GPIO17: right switch (under screen #2)

- GPIO18: SAO3 pin3 + LB pin7
- GPIO23: SAO3 pin4

- 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
- GPIO26: SAO4 pin3 + RB pin7

- GPIO27: free (pin available on the chip, not routed anywhere)

- 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
<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 27 15

---- 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.

= Extensions: Adding a SAO =
* provided by others
* build your own (linky here to our docs)

= 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?

* [[Swagbadge2021_UpdatingSoftware|Updating the Software]]
* [[Swagbadge2021_SoftwareDev|Writing your own badge programs]]

Swagbadge2021 GettingStarted

2021-01-23T20:28:58Z

Marcmerlin: /* Hardware pinout */

= 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. ==
* 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.
* 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 <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!

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 [[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.
* use mpfshell: <code>mpfshell -o COM3</code> (substitute the com port/tty of your badge)
* <code>put configuration/net.py configuration/net.py</code>
* 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 [[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-schematic.pdf
<pre>
- GPIO0 : left breakout pin4
- GPIO2 : left breakout pin3

- 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
- GPIO14/27: slider #2
- GPIO16: left switch (under screen #1)
- GPIO17: right switch (under screen #2)

- GPIO18: SAO3 pin3 + LB pin7
- GPIO23: SAO3 pin4

- 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
- GPIO26: SAO4 pin3 + RB pin7

- GPIO27: free (pin available on the chip, not routed anywhere)

- 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 ). If you would like to connect an SPI device like an SSD1331 96x64 color TFT, here are default hardware pin numbers, and
<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 27 15

---- 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.

= Extensions: Adding a SAO =
* provided by others
* build your own (linky here to our docs)

= 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?

* [[Swagbadge2021_UpdatingSoftware|Updating the Software]]
* [[Swagbadge2021_SoftwareDev|Writing your own badge programs]]

Swagbadge2021 UpdatingSoftware

2021-01-20T06:47:26Z

Marcmerlin: /* Download #swagbadge (Aiko Engine) firmware */

= Updating the software framework =

Swagbadge owners might want to update the software framework (Aiko). Dagbadge owners will need to put the framework onto their badge before they can use it.

Here's how to do that!

== Requirements ==

* #swagbadge or #dagbadge or any ESP32 with an OLED screen
* Micro-USB cable
* Linux, Mac OS or Linux system running Python 3
* Command line tools: git

== Setting up your Windows 10 system for connecting to badge hardware ==

How to find your serial COM port on Windows:
* Use the Device Manager.
* Under the "Ports" category, 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.

Windows 10 may automatically discover your #swagbadge USB hardware and automatically install the correct USB serial hardware driver, or if nothing still shows up, you might need to update your USB drivers for supporting the USB hardware CP210x on your #swagbadge, please follow these instructions:
* Download the CP210x drivers from [https://www.silabs.com/developers/usb-to-uart-bridge-vcp-drivers Silicon Labs Windows Universal Driver]
* Unpack the zip file
* Follow the Silicon Labs instructions for [https://www.silabs.com/documents/public/application-notes/AN335.pdf INF only install] (Section 5 on page 9)

By this point, you have know the serial COM port that your #swagbadge is connected to, e.g COM4

== Setting up your Mac OS system for connecting to #swagbadge hardware ==

How to find your serial COM port on OS X:

$ ls /dev/tty.usb*

Unless you have lot of dev boards (or maybe a phone) plugged in you should just see a single filename there.
Use this (without the `/dev/` prefix) when using the `open` command in `mpfshell`

To get a working `mpfshell` install a recent version of Python (Python3.8 is known to work) using a installed DMG.
Then create a *venv* and install the necessary tools using pip.
For example:

$ mkdir swag
$ cd swag
$ python3.8 -m venv env
$ ./env/bin/pip install esptool mpfshell

You can then run `mpfshell` to connect:

$ ./env/bin/mpfshell
mpfs [/]> open <your device node as found previously>

== Setting up your Linux system for connecting to #swagbadge hardware ==
[Link other instructions here]

== Setting up your Windows 10 system for installing #swagbadge firmware ==

* Install [https://docs.conda.io/en/latest/miniconda.html Miniconda3] to create a specific Python development environment. (Note we are using Python3 not Python2)
* Create specific Python 3 environment for playing around with your #swagbadge
** Start an Anaconda Powershell Prompt (aka Windows Terminal)
** <code>conda create --yes -n swagbadge python=3</code>
** <code>conda activate swagbadge</code>
* Your command prompt should now look like: <code>(swagbadge) C:\Users\[Username]></code>

* Install some python tools to let us prepare and communicate with the badge
** <code>pip install esptool mpfshell</code>

* To test that the required tools are installed, trying running the following commands
** <code>esptool</code> # Should show you help on running the esptool
** <code>mpfshell</code> # Should show three lines of output
*** <code>exit</code> # To exit mpfshell

== Download #swagbadge (Aiko Engine) firmware ==

Within your Anaconda Prompt session, change directory to where you’d like the #swagbadge software to be downloaded, for example:
* <code>cd $HOME/software</code>

Download #swagbadge firmware:
* <code>git clone https://github.com/geekscape/aiko_engine_mp.git</code> # NOTE: this URL will change once we're live
* <code>cd aiko_engine_mp</code>

Install MicroPython
* Create a directory to hold the MicroPython firmware, such as aiko_engine_mp/firmware/
* <code>mkdir firmware</code>
* Using your web browser, download: [http://micropython.org/resources/firmware/esp32-idf4-20200902-v1.13.bin esp32-idf4-20200902-v1.13.bin] (mouse right button click → [Save As …] saving the MicroPython firmware in the firmware directory you just made.
** The [http://micropython.org/download/ MicroPython download list] has a link to a bunch of firmware drivers, we are using the one for the esp32 device, with the latest 1.4 generic

Erase #swagbadge LoLin-Lite ESP32 flash memory
* <code>esptool --chip esp32 --port COM3 erase_flash</code> # adjust the port to suit.
* You’ll know it’s worked, if the output finishes with “Hard resetting via RTS pin…”

You may get this error, if so, try esptool.py instead:
<pre>
sauron [mc]$ esptool --chip esp32 --port /dev/ttyUSB0 erase_flash
esptool.py v2.8
Serial port /dev/ttyUSB0
Connecting....
Chip is ESP32D0WDQ6 (revision 1)
Features: WiFi, BT, Dual Core, 240MHz, VRef calibration in efuse, Coding Scheme None
Crystal is 40MHz
MAC: 7c:9e:bd:ed:79:24
Enabling default SPI flash mode...
Erasing flash (this may take a while)...

A fatal error occurred: ESP32 ROM does not support function erase_flash.
sauron [mc]$ esptool.py --chip esp32 --port /dev/ttyUSB0 erase_flash
esptool.py v2.6
Serial port /dev/ttyUSB0
Connecting....
Chip is ESP32D0WDQ6 (revision 1)
Features: WiFi, BT, Dual Core, 240MHz, VRef calibration in efuse, Coding Scheme None
MAC: 7c:9e:bd:ed:79:24
Uploading stub...
Running stub...
Stub running...
Erasing flash (this may take a while)...
Chip erase completed successfully in 11.8s
Hard resetting via RTS pin...
</pre>

Install microPython on the badge
* <code>esptool --chip esp32 --port COM3 --baud 460800 write_flash -z 0x1000 firmware\esp32-idf4-20200902-v1.13.bin</code> #adjust port and firmware location if necessary
* You’ll know it’s worked, if the output finishes with “Hard resetting via RTS pin…”

Test that the software is installed correctly by using mpfshell
* <code>mpfshell -o COM3</code> # Adjust port to suit
* If it has made a connection to your badge, you will see it say
<nowiki>Connected to esp32
** Micropython File Shell v0.9.1, sw@kaltpost.de **
-- Running on Python 3.8 using PySerial 3.4 --
mpfs [/]> </nowiki>

== Using mpfshell ==

mpfshell has two functions: it lets you put files on/off the device, and it can give you a python shell to execute code on the device.
* Getting files on/off the device is a bit like commandline ftp
** ls - looks at the files on your micropython device
** lls - looks at the files on your local computer in the current directory
** put - puts a file to the device
** cat - shows you the contents of the file
** help() - gives you more information on the commands
** repl - opens up the python shell on the badge

Note: To get out of repl, use Ctrl-Q (on Windows) which drops you back into mpfshell

A little program to say hello world!
* <code> >>> print("hello world")</code>
* Output: <code>hello world</code>

A little program to turn the blue light on the board on and off (this is on the underside of the Swagbadge, visible through a circular cutout)
<nowiki>>>> import machine
>>> pin22=machine.Pin(22, machine.Pin.OUT, machine.Pin.PULL_UP)
>>> pin22.value(0)
>>> pin22.value(1)</nowiki>

== Alternatives to mpfshell: rshell and pyboard.py ==

rshell is an option, but it may not be reliable in all cases. However 'pip install rshell' also installs pyboard.

pyboard.py is the official tool that ships with micropython and is more flexible and reliable: http://docs.micropython.org/en/latest/reference/pyboard.py.html

<pre>
sauron [mc]$ pyboard.py --device /dev/ttyUSB0 -c 'import os; print(os.statvfs("/")[0]*os.statvfs("/")[3], "bytes free out of",os.statvfs("/")[1]*os.statvfs("/")[2])'
1699840 bytes free out of 2097152
</pre>

== Saving your private key ==

Use mpfshell to get the file: `configuration/keys.db`.

== Putting the Aiko framework onto the device, using mpfshell ==
* <code>mpfshell COM5 -s scripts\aiko.mpf</code> #run from within the aiko_framework_mp directory

=== Windows only: Patch mpfshell ===

''Note!'' mpfshell needs a patch applied to let it run a script under Windows. (the patch is included upstream, it's just not in a released distribution yet)

* Inside <code>C:/users/USERNAME/Miniconda2/envs/swagbadge/Lib/site-packages/mp</code>
* edit <code>mpfshell.py</code>
* Search for <code>elif args.script is not None:</code>, around line 796
* between that line and the next, insert two lines. It should look like:
<nowiki>
elif args.script is not None:

if platform.system() == "Windows": #INSERT THIS LINE
mpfs.use_rawinput = True #INSERT THIS LINE

f = open(args.script, "r")
</nowiki>
* Python is very particular about spacing. The rest of the code uses 4 spaces for indents so follow suit.

= Software development =

See [[Swagbadge2021_SoftwareDev]]

Swagbadge2021 GettingStarted

2021-01-19T23:16:16Z

Marcmerlin: /* Hardware pinout */

= 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. ==
* 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.
* 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 ==

'''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.

=== Getting the device on your wifi - wireless ===

* 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 2.4GHz network: it is not compatible with 5GHz WiFi.''
* 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.

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 setting up via the wifi AP (access point) doesn't work, you can put a configuration file onto the badge.
* 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 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: <code>mpfshell -o COM3</code>
* <code>put configuration/net.py configuration/net.py</code>
* 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.

On bootup you should now see...

= 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 [[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-schematic.pdf
<pre>
- GPIO0 : left breakout pin4
- GPIO2 : left breakout pin3

- 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
- GPIO14/27: slider #2
- GPIO16: left switch (under screen #1)
- GPIO17: right switch (under screen #2)

- GPIO18: SAO3 pin3 + LB pin7
- GPIO23: SAO3 pin4

- 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
- GPIO26: SAO4 pin3 + RB pin7

- GPIO27: free (pin available on the chip, not routed anywhere)

- 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>

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

* [[Swagbadge2021_UpdatingSoftware|Updating the Software]]
* [[Swagbadge2021_SoftwareDev|Writing your own badge programs]]

Swagbadge2021 GettingStarted

2021-01-19T23:15:30Z

Marcmerlin: /* Hardware pinout */

= 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. ==
* 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.
* 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 ==

'''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.

=== Getting the device on your wifi - wireless ===

* 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 2.4GHz network: it is not compatible with 5GHz WiFi.''
* 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.

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 setting up via the wifi AP (access point) doesn't work, you can put a configuration file onto the badge.
* 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 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: <code>mpfshell -o COM3</code>
* <code>put configuration/net.py configuration/net.py</code>
* 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.

On bootup you should now see...

= 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 [[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-schematic.pdf
<pre>
- GPIO0 : left breakout pin4
- GPIO2 : left breakout pin3

- 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
- GPIO14/27: slider #2
- GPIO16: left switch (under screen #1)
- GPIO17: right switch (under screen #2)

- GPIO18: SAO3 pin3 + LB pin7
- GPIO23: SAO3 pin4

- 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
- GPIO26: SAO4 pin3 + RB pin7

- GPIO27: free

- 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>

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

* [[Swagbadge2021_UpdatingSoftware|Updating the Software]]
* [[Swagbadge2021_SoftwareDev|Writing your own badge programs]]

Swagbadge2021 UpdatingSoftware

2021-01-19T19:24:23Z

Marcmerlin:

= Updating the software framework =

Swagbadge owners might want to update the software framework (Aiko). Dagbadge owners will need to put the framework onto their badge before they can use it.

Here's how to do that!

== Requirements ==

* #swagbadge or #dagbadge or any ESP32 with an OLED screen
* Micro-USB cable
* Linux, Mac OS or Linux system running Python 3
* Command line tools: git

== Setting up your Windows 10 system for connecting to badge hardware ==

How to find your serial COM port on Windows:
* Use the Device Manager.
* Under the "Ports" category, 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.

Windows 10 may automatically discover your #swagbadge USB hardware and automatically install the correct USB serial hardware driver, or if nothing still shows up, you might need to update your USB drivers for supporting the USB hardware CP210x on your #swagbadge, please follow these instructions:
* Download the CP210x drivers from [https://www.silabs.com/developers/usb-to-uart-bridge-vcp-drivers Silicon Labs Windows Universal Driver]
* Unpack the zip file
* Follow the Silicon Labs instructions for [https://www.silabs.com/documents/public/application-notes/AN335.pdf INF only install] (Section 5 on page 9)

By this point, you have know the serial COM port that your #swagbadge is connected to, e.g COM4

== Setting up your Mac OS system for connecting to #swagbadge hardware ==

How to find your serial COM port on OS X:

$ ls /dev/tty.usb*

Unless you have lot of dev boards (or maybe a phone) plugged in you should just see a single filename there.
Use this (without the `/dev/` prefix) when using the `open` command in `mpfshell`

To get a working `mpfshell` install a recent version of Python (Python3.8 is known to work) using a installed DMG.
Then create a *venv* and install the necessary tools using pip.
For example:

$ mkdir swag
$ cd swag
$ python3.8 -m venv env
$ ./env/bin/pip install esptool mpfshell

You can then run `mpfshell` to connect:

$ ./env/bin/mpfshell
mpfs [/]> open <your device node as found previously>

== Setting up your Linux system for connecting to #swagbadge hardware ==
[Link other instructions here]

== Setting up your Windows 10 system for installing #swagbadge firmware ==

* Install [https://docs.conda.io/en/latest/miniconda.html Miniconda3] to create a specific Python development environment. (Note we are using Python3 not Python2)
* Create specific Python 3 environment for playing around with your #swagbadge
** Start an Anaconda Powershell Prompt (aka Windows Terminal)
** <code>conda create --yes -n swagbadge python=3</code>
** <code>conda activate swagbadge</code>
* Your command prompt should now look like: <code>(swagbadge) C:\Users\[Username]></code>

* Install some python tools to let us prepare and communicate with the badge
** <code>pip install esptool mpfshell</code>

* To test that the required tools are installed, trying running the following commands
** <code>esptool</code> # Should show you help on running the esptool
** <code>mpfshell</code> # Should show three lines of output
*** <code>exit</code> # To exit mpfshell

== Download #swagbadge (Aiko Engine) firmware ==

Within your Anaconda Prompt session, change directory to where you’d like the #swagbadge software to be downloaded, for example:
* <code>cd $HOME/software</code>

Download #swagbadge firmware:
* <code>git clone https://github.com/geekscape/aiko_engine_mp.git</code> # NOTE: this URL will change once we're live
* <code>cd aiko_engine_mp</code>

Install MicroPython
* Create a directory to hold the MicroPython firmware, such as aiko_engine_mp/firmware/
* <code>mkdir firmware</code>
* Using your web browser, download: [http://micropython.org/resources/firmware/esp32-idf4-20200902-v1.13.bin esp32-idf4-20200902-v1.13.bin] (mouse right button click → [Save As …] saving the MicroPython firmware in the firmware directory you just made.
** The [http://micropython.org/download/ MicroPython download list] has a link to a bunch of firmware drivers, we are using the one for the esp32 device, with the latest 1.4 generic

Erase #swagbadge LoLin-Lite ESP32 flash memory
* <code>esptool --chip esp32 --port COM3 erase_flash</code> # adjust the port to suit.
* You’ll know it’s worked, if the output finishes with “Hard resetting via RTS pin…”

Install microPython on the badge
* <code>esptool --chip esp32 --port COM3 --baud 460800 write_flash -z 0x1000 firmware\esp32-idf4-20200902-v1.13.bin</code> #adjust port and firmware location if necessary
* You’ll know it’s worked, if the output finishes with “Hard resetting via RTS pin…”

Test that the software is installed correctly by using mpfshell
* <code>mpfshell -o COM3</code> # Adjust port to suit
* If it has made a connection to your badge, you will see it say
<nowiki>Connected to esp32
** Micropython File Shell v0.9.1, sw@kaltpost.de **
-- Running on Python 3.8 using PySerial 3.4 --
mpfs [/]> </nowiki>

== Using mpfshell ==

mpfshell has two functions: it lets you put files on/off the device, and it can give you a python shell to execute code on the device.
* Getting files on/off the device is a bit like commandline ftp
** ls - looks at the files on your micropython device
** lls - looks at the files on your local computer in the current directory
** put - puts a file to the device
** cat - shows you the contents of the file
** help() - gives you more information on the commands
** repl - opens up the python shell on the badge

Note: To get out of repl, use Ctrl-Q (on Windows) which drops you back into mpfshell

A little program to say hello world!
* <code> >>> print("hello world")</code>
* Output: <code>hello world</code>

A little program to turn the blue light on the board on and off (this is on the underside of the Swagbadge, visible through a circular cutout)
<nowiki>>>> import machine
>>> pin22=machine.Pin(22, machine.Pin.OUT, machine.Pin.PULL_UP)
>>> pin22.value(0)
>>> pin22.value(1)</nowiki>

== Alternatives to mpfshell: rshell and pyboard.py ==

rshell is an option, but it may not be reliable in all cases. However 'pip install rshell' also installs pyboard.

pyboard.py is the official tool that ships with micropython and is more flexible and reliable: http://docs.micropython.org/en/latest/reference/pyboard.py.html

<pre>
sauron [mc]$ pyboard.py --device /dev/ttyUSB0 -c 'import os; print(os.statvfs("/")[0]*os.statvfs("/")[3], "bytes free out of",os.statvfs("/")[1]*os.statvfs("/")[2])'
1699840 bytes free out of 2097152
</pre>

== Saving your private key ==

Use mpfshell to get the file: `configuration/keys.db`.

== Putting the Aiko framework onto the device, using mpfshell ==
* <code>mpfshell COM5 -s scripts\aiko.mpf</code> #run from within the aiko_framework_mp directory

=== Windows only: Patch mpfshell ===

''Note!'' mpfshell needs a patch applied to let it run a script under Windows.

* Inside <code>C:/users/USERNAME/Miniconda2/envs/swagbadge/Lib/site-packages/mp</code>
* edit <code>mpfshell.py</code>
* Search for <code>elif args.script is not None:</code>, around line 796
* between that line and the next, insert two lines. It should look like:
<nowiki>
elif args.script is not None:

if platform.system() == "Windows": #INSERT THIS LINE
mpfs.use_rawinput = True #INSERT THIS LINE

f = open(args.script, "r")
</nowiki>
* Python is very particular about spacing. The rest of the code uses 4 spaces for indents so follow suit.

= Software development =

See [[Swagbadge2021_SoftwareDev]]

Swagbadge2021 SoftwareDev

2021-01-17T23:03:19Z

Marcmerlin: /* OLED screens */

{{DISPLAYTITLE:Badge Software Development}}

Want to write your own programs to run on your badge? This page gives a brief overview of the software architecture, an example of a program, and a reference guide on how to access the hardware.

<div style="float:right">
__TOC__
</div>

== Background ==
The badge runs [https://micropython.org MicroPython] (written by [http://dpgeorge.net/ Damien George] from Melbourne!) and has the [https://github.com/geekscape/aiko_engine_mp Aiko framework] (written by OHMC's [https://twitter.com/geekscape Andy Gelme]) loaded on it.

MicroPython gives you libraries to access the ESP32 microprocessor functionality. Things like: reading and writing to specific pins on the processor or performing operating system functions such as accessing the file system).

Aiko gives you convenience libraries for driving the badge hardware like the OLED screens, as well as running threads to keep your badge connected to wifi, a connection to the MQTT server, the emergency-stop function to prevent runaway code, and an automatic upgrade function so we can ship upgrades to your device without you having to wrangle git.

== Sample code ==

This code writes "Hello world" to one screen, while displaying the status of the wifi, MQTT connection, button presses and slider status on the left hand screen.

It demonstrates how to use the Aiko event loop to periodically poll for hardware state, as well as how to access some of the features of the badge.

You can find more example code in the '''examples''' directory of the [https://github.com/geekscape/aiko_engine_mp/tree/master/examples Aiko repository] on github.

<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Example code: use "expand" to view</div>
<div class="mw-collapsible-content">
<nowiki>
# examples/helloworld.py
#
# Writes a message to the oled and displays some state info
#
# Usage
# ~~~~~
# import examples.helloworld as helloworld
# from examples.helloworld import run
# run()
#

from machine import Pin, TouchPad
import aiko.event as event
import aiko.oled as oled

title = "Hello!"

import configuration.main

# Buttons: underneath the screens
button_right = Pin(17, Pin.IN, Pin.PULL_UP)
button_left = Pin(16, Pin.IN, Pin.PULL_UP)

# Clean out the whole line that was there before
# Write some new text and show it
def oled_write_line(oled_target, x, y, text):
oled_target.fill_rect(0,y,oled.width, oled.font_size, oled.bg)
oled_target.text(text, x, y)
oled_target.show()

def status():
sliders = touch_slider_handler()
oledL = oled.oleds[0]
oledR = oled.oleds[1]
oled.write_line(oledR, 1, 10, "Hello world!")
oled_write_line(oledL, 1, 10, "Wifi: "+str(net.is_connected()))
oled_write_line(oledL, 1, 20, "MQTT: "+str(mqtt.is_connected()))
oled_write_line(oledL, 1, 30, " "+str(int(not(buttonL.value())))+" Button "+str(int(not(buttonR.value()))))

# Check on the status of the badge hardware and display that every 500ms
def run():
oled.oleds_clear(oled.bg)
oled.set_title(title)
event.add_timer_handler(status, 500)
try:
event.loop()
finally:
event.remove_timer_handler(statusbar)
</nowiki>
</div></div>

== Architecture of a Swagbadge application ==

An application runs when the Aiko framework is also running, so you can rely on having all the badge services available.

An application is designed to be triggered when the badge is rebooted (either via pushing the button on the back, or via using ^D in the repl). The badge knows which application to run by the state of the <code>configuration\main.py</code> file.

The framework will call your application's '''initialise()''' function. The framework is running an event loop, so the initialise function is the place to add in event handlers to respond to actions you take on the badge.

{{Note|Note: Refreshing the OLEDs is reasonably intense on the microprocessor. If you have too many event loops triggering too often and/or too much screen activity, you can starve the badge of resources. This can produce wifi dropouts, or non-responsiveness. If you have a lot of screen activity, consider using a buffer or recording state and just doing a screen update periodically}}

== Software reference ==

=== MicroPython environment ===

[https://micropython.org MicroPython docs]

==== Special files ====

There are two special files which are run automatically by MicroPython if they exist on the filesystem: <code>boot.py</code> and <code>main.py</code>.

* '''boot.py''': This file is run first on power up/reset. We don't modify it from what MicroPython ships with, but it's important to know it exists (and not to delete it), and is interesting to look into it to see what it does.
* '''main.py''': This is run after boot.py so if you want something to automatically happen on boot/reset, this is where to put it. We use this to start up the Aiko framework, initialise the hardware (such as the network and mqtt) and start up any application that is configured inside <code>configuration/main.py</code>

==== Directory structure ====

What's on the processor? Where does it live?

* <code>main.py</code>, <code>boot.py</code> - files run on bootup
* <code>lib</code> - code in here is aiko framework code and automatically in the micropython 'path'.
** <code>aiko</code> - the aiko framework
* <code>applications</code> - programs to run automatically on bootup. Must have an initialise function
* <code>configuration</code> - control the config of aiko using files in here
* <code>examples</code> - sample code!

You can't edit the files directly on the processor (there's no editing tooling): you edit a copy of it on your computer, then use mpfshell to <code>put</code> it onto the badge.

For micropython purposes, you can use the <code>import</code> statement to import anything in the <code>lib</code> directory without prefacing it with "lib", anything else is imported from root.
For example:
* to import lib/aiko/net.py, you would use <code>import aiko.net</code>
* to import examples/showcase.py, you would use <code>import examples.showcase</code>

Because the aiko configuration files are, themselves, just python, you can also do <code>import configuration.main.settings</code> where the file is in /configuration/main.py but it contains a datastructure called 'settings'.
=== MQTT ===

See [[Swagbadge2021_MQTT]]

== Software development ==

=== Aiko ===
The Aiko Engine is what runs after boot (FreeRTOS, then microPython). Aiko provides a framework for developing applications, by providing higher level abstractions over the basic hardware, events, messaging and other conveniences. Basically, a lot of house keeping that you'd end up writing yourself. After boot, there are two background threads, one looking after Wi-Fi connectivity and the other looking after MQTT connectivity.
There are also three event handlers: MQTT keep-alive, firmware upgrader and the work-in-progress SwagBadge application handler.

<pre>
>>> aiko.event.event_list.print()
<function swagbadge_handler at 0x3ffe6c70> every 5000 next 23099
<function upgrade_handler at 0x3ffedfa0> every 5000 next 23099
<function mqtt_ping_handler at 0x3ffe9820> every 60000 next 73672
</pre>
That last handler, which every 5 seconds is updating the title bar "LCA2021" <--> "SwagBadge" (see https://github.com/geekscape/aiko_engine_mp/blob/master/applications/swagbadge.py ).

You can stop a handler, like this (this will stop the top bar status updater):
<pre>
>>> import applications.swagbadge
>>> aiko.event.remove_timer_handler(application.swagbadge_handler)
</pre>

=== Testing code ===

First write your code on your computer, and make sure it compiles ( python -m py_compile code.py )

Then, you can go in repl and use paste mode (^E). It only works if you paste a few lines at a time. End your paste with ^D and then if you pasted a function, call the function:
<pre>
>>> ^E
paste mode; Ctrl-C to cancel, Ctrl-D to finish
=== PASTE_YOUR_CODE_HERE
=== ^D
>>>
</pre>

=== Pushing new code ===
Occasionally you might find that the updated source code that you just used the mpfshell "put" command to transfer isn't properly stored on the ESP32 microPython flash filesystem. After rebooting, you might see unexpected errors. A simple way to check is to use the mpfshell "cat" command to check that the file was completely transferred.

The safest way to update code is to perform a reboot after transferring all the files. Doing a soft-reboot using Control-D doesn't take long, i.e it is faster and easier than doing a hard-reboot with the reset button. The good thing about a reboot (microPython interpreter restart) is that there is no confusion about the complete state of your system, i.e what references have been held onto from your older source code that might still be running in a thread or as an event handler (via the Aiko Engine framework).

You can also delete all running modules:
<pre>
import sys
sys.modules.clear()
</pre>

More details in https://spectrum.chat/lca2021-swagbadge/software/safe-software-updates~ba541e3c-d8a2-41a8-ac47-71d87696de2d

=== Replacing the swagbadge application with your own ===

Edit configuration/main.py and set "application": "application/yourcode"

=== Reboot to shell / Force runaway code to stop ===

It's possible to write code that will leave your badge unresponsive. Rebooting just reruns the same bad code. What to do?

* Place a finger on each of the bottom slider pads, either side of the microprocessor.
* Trigger a restart by using the button on the back of the badge, or Ctrl-D in repl (if you can get into repl)

The badge will restart but not autorun any code, just drop you back at the repl prompt. From there you can <code>put</code> bugfixed code back onto the device.

See https://github.com/geekscape/aiko_engine_mp/blob/a5b5593d37509df64a3dcb4cdc3d13a411152d82/main.py#L20

== Hardware reference ==

=== OLED screens ===

==== via MQTT ====

* '''(oled:clear)''' : clears both screens
* '''(oled:log Hello World!)''' : writes a message along the bottom of the screens, scrolling up whatever is there out of the way
* '''(oled:pixel x y)''' : lights a pixel at that spot
* '''(oled:text x y This is a test!)''' : Puts some text at the position x,y. It will be displayed over the top of whatever's there.

==== via API ====

On the badge, by default the two oleds work as a single long screen, with text split across both of them. You can access a specific oled and use the underlying functions to write to them

Library
* '''from aiko import oled''' # make the oled functions available for use within your code

Globals
* '''[] oled.oleds''' # an array of oleds, letting you address them separately if you choose
* '''int oled.fg/oled.bg''' # get/set fg and bg colours (0 or 1)
* '''int oled.font_size''' # helpful to work out how much space a line of text will take up
* '''boolean oled.lock_title''' # true/false. True means the display always shows the title. False means it'll be wiped once the display is cleared.

Functions
* '''oled.initialise()''' # uses configuration.oled.settings by default, normally already invoked by the base swagbadge handler
* '''oled.oleds_clear(colour)''' # pass in oled.bg or oled.fg for easy set. Wipes the display
* '''oled.log(text)''' # scroll up text to insert a new line at the bottom of the display
* '''oled.text(text, x, y, colour)''' # add text at the position x,y in the colour specified. Note: does not clear the contents at this spot first.
* '''oled.oleds_show()''' # refresh the display with the latest text/image additions
* '''oled.set_title(text)''' # set the title text
* '''oled.write_title()''' # write the title text

==== Oled image push and I2C speed ====

- example #1: https://github.com/geekscape/aiko_engine_mp/blob/master/examples/oled_image.py

- example #2: https://github.com/geekscape/aiko_engine_mp/blob/master/examples/oled_benchmark.py

The 2nd example gets a speed of 21fps per screen (or about 10fps for both screens).

Using C++ code (see https://github.com/geekscape/aiko_engine_mp/commit/a22b3099584c9978807e08adf752f3082af65875 ) you get at least 61fps per screen (if you do assembly: 86fps, and with crazy I2C noacks hacks, you can get 150fps: https://bitbanksoftware.blogspot.com/2018/05/fast-ssd1306-oled-drawing-with-i2c-bit.html ).

Back to python, if you increase the CPU speed with machine.freq(240000000) , you'll get 26fps per screen, and if you replace the image pixel pushes by a full back or full white push, you get 29fps, which seems to be an upper limit of the python oled code. A better end to end C++ driver could give a lot more speed.

=== Screen buttons ===

If you push (gently!) on the screens, you'll discover they double as buttons: there's a small switch under each OLED that is pressed when you push down on the screen.

{{Note|'''Warning''': Push on the '''middle''' of the screen, not the edge. This will minimise the risk of bending... and breaking... the screen.}}

The left screen button is pin 16. The right screen button is pin 17.

==== via API ====

<pre>
from machine import Pin

button_left = Pin(16, Pin.IN, Pin.PULL_UP)
button_right = Pin(17, Pin.IN, Pin.PULL_UP)

pressed = not(button_left.value())
</pre>

The button sends "1" when it's ''not'' being pressed, and "0" when it is. This is counterintuitive to most of us, so I recommend inverting the value when reading it.

=== Sliders ===

The sliders operate via capacitive touch. You can use them to detect if someone has their finger on the circular pads at either end (which let you treat them like buttons), or you can detect the position of the finger along the slider by checking the relative values as the capacitance changes.

The left slider is on pins 12 (bottom) and 15 (top), right slider is on pins 14 (bottom) and 27 (top).

More info from MicroPython about [http://docs.micropython.org/en/latest/esp32/quickref.html?highlight=touchpad#capacitive-touch capacitive touch].

<pre>
from machine import Pin, TouchPad
import aiko.common

bottom_left = TouchPad(Pin(12))
top_left = TouchPad(Pin(15))
bottom_right = TouchPad(Pin(14))
top_right = TouchPad(Pin(27))

# is this button pressed?
# the commons library returns true/false
pressed_bottom_left = common.touch_pins_check([bottom_left])

# check where we are along the slider
# the 'read' functions return an integer of the 'strength' of the
# capacitance. As you move your finger between the endpoints,
#the relative value of the difference between them will change.
slider_left = bottom_left.read() - bottom_left.read()
</pre>

Micropython functions
* '''touchpad.read()''' - gives you the current value of the sensor. It will be large when not touched (over 1000) and smaller when touched.
Aiko functions
* '''common.touch_pins_check(touchpad_array)''' - Returns true if ''all'' the touchpad sensors listed are being touched, false otherwise.

=== SAOs (simple addons) ===

Swagbadge2021 SoftwareDev

2021-01-17T01:06:44Z

Marcmerlin:

{{DISPLAYTITLE:Badge Software Development}}

Want to write your own programs to run on your badge? This page gives a brief overview of the software architecture, an example of a program, and a reference guide on how to access the hardware.

<div style="float:right">
__TOC__
</div>

== Background ==
The badge runs [https://micropython.org MicroPython] (written by [http://dpgeorge.net/ Damien George] from Melbourne!) and has the [https://github.com/geekscape/aiko_engine_mp Aiko framework] (written by OHMC's [https://twitter.com/geekscape Andy Gelme]) loaded on it.

MicroPython gives you libraries to access the ESP32 microprocessor functionality. Things like: reading and writing to specific pins on the processor or performing operating system functions such as accessing the file system).

Aiko gives you convenience libraries for driving the badge hardware like the OLED screens, as well as running threads to keep your badge connected to wifi, a connection to the MQTT server, the emergency-stop function to prevent runaway code, and an automatic upgrade function so we can ship upgrades to your device without you having to wrangle git.

== Sample code ==

This code writes "Hello world" to one screen, while displaying the status of the wifi, MQTT connection, button presses and slider status on the left hand screen.

It demonstrates how to use the Aiko event loop to periodically poll for hardware state, as well as how to access some of the features of the badge.

You can find more example code in the '''examples''' directory of the [https://github.com/geekscape/aiko_engine_mp/tree/master/examples Aiko repository] on github.

<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Example code: use "expand" to view</div>
<div class="mw-collapsible-content">
<nowiki>
# examples/helloworld.py
#
# Writes a message to the oled and displays some state info
#
# Usage
# ~~~~~
# import examples.helloworld as helloworld
# from examples.helloworld import run
# run()
#

from machine import Pin, TouchPad
import aiko.event as event
import aiko.oled as oled

title = "Hello!"

import configuration.main

# Buttons: underneath the screens
button_right = Pin(17, Pin.IN, Pin.PULL_UP)
button_left = Pin(16, Pin.IN, Pin.PULL_UP)

# Clean out the whole line that was there before
# Write some new text and show it
def oled_write_line(oled_target, x, y, text):
oled_target.fill_rect(0,y,oled.width, oled.font_size, oled.bg)
oled_target.text(text, x, y)
oled_target.show()

def status():
sliders = touch_slider_handler()
oledL = oled.oleds[0]
oledR = oled.oleds[1]
oled.write_line(oledR, 1, 10, "Hello world!")
oled_write_line(oledL, 1, 10, "Wifi: "+str(net.is_connected()))
oled_write_line(oledL, 1, 20, "MQTT: "+str(mqtt.is_connected()))
oled_write_line(oledL, 1, 30, " "+str(int(not(buttonL.value())))+" Button "+str(int(not(buttonR.value()))))

# Check on the status of the badge hardware and display that every 500ms
def run():
oled.oleds_clear(oled.bg)
oled.set_title(title)
event.add_timer_handler(status, 500)
try:
event.loop()
finally:
event.remove_timer_handler(statusbar)
</nowiki>
</div></div>

== Architecture of a Swagbadge application ==

An application runs when the Aiko framework is also running, so you can rely on having all the badge services available.

An application is designed to be triggered when the badge is rebooted (either via pushing the button on the back, or via using ^D in the repl). The badge knows which application to run by the state of the <code>configuration\main.py</code> file.

The framework will call your application's '''initialise()''' function. The framework is running an event loop, so the initialise function is the place to add in event handlers to respond to actions you take on the badge.

{{Note|Note: Refreshing the OLEDs is reasonably intense on the microprocessor. If you have too many event loops triggering too often and/or too much screen activity, you can starve the badge of resources. This can produce wifi dropouts, or non-responsiveness. If you have a lot of screen activity, consider using a buffer or recording state and just doing a screen update periodically}}

== Software reference ==

=== MicroPython environment ===

[https://micropython.org MicroPython docs]

==== Special files ====

There are two special files which are run automatically by MicroPython if they exist on the filesystem: <code>boot.py</code> and <code>main.py</code>.

* '''boot.py''': This file is run first on power up/reset. We don't modify it from what MicroPython ships with, but it's important to know it exists (and not to delete it), and is interesting to look into it to see what it does.
* '''main.py''': This is run after boot.py so if you want something to automatically happen on boot/reset, this is where to put it. We use this to start up the Aiko framework, initialise the hardware (such as the network and mqtt) and start up any application that is configured inside <code>configuration/main.py</code>

==== Directory structure ====

What's on the processor? Where does it live?

* <code>main.py</code>, <code>boot.py</code> - files run on bootup
* <code>lib</code> - code in here is aiko framework code and automatically in the micropython 'path'.
** <code>aiko</code> - the aiko framework
* <code>applications</code> - programs to run automatically on bootup. Must have an initialise function
* <code>configuration</code> - control the config of aiko using files in here
* <code>examples</code> - sample code!

You can't edit the files directly on the processor (there's no editing tooling): you edit a copy of it on your computer, then use mpfshell to <code>put</code> it onto the badge.

For micropython purposes, you can use the <code>import</code> statement to import anything in the <code>lib</code> directory without prefacing it with "lib", anything else is imported from root.
For example:
* to import lib/aiko/net.py, you would use <code>import aiko.net</code>
* to import examples/showcase.py, you would use <code>import examples.showcase</code>

Because the aiko configuration files are, themselves, just python, you can also do <code>import configuration.main.settings</code> where the file is in /configuration/main.py but it contains a datastructure called 'settings'.
=== MQTT ===

See [[Swagbadge2021_MQTT]]

== Software development ==

=== Aiko ===
The Aiko Engine is what runs after boot (FreeRTOS, then microPython). Aiko provides a framework for developing applications, by providing higher level abstractions over the basic hardware, events, messaging and other conveniences. Basically, a lot of house keeping that you'd end up writing yourself. After boot, there are two background threads, one looking after Wi-Fi connectivity and the other looking after MQTT connectivity.
There are also three event handlers: MQTT keep-alive, firmware upgrader and the work-in-progress SwagBadge application handler.

<pre>
>>> aiko.event.event_list.print()
<function swagbadge_handler at 0x3ffe6c70> every 5000 next 23099
<function upgrade_handler at 0x3ffedfa0> every 5000 next 23099
<function mqtt_ping_handler at 0x3ffe9820> every 60000 next 73672
</pre>
That last handler, which every 5 seconds is updating the title bar "LCA2021" <--> "SwagBadge" (see https://github.com/geekscape/aiko_engine_mp/blob/master/applications/swagbadge.py ).

You can stop a handler, like this (this will stop the top bar status updater):
<pre>
>>> import applications.swagbadge
>>> aiko.event.remove_timer_handler(application.swagbadge_handler)
</pre>

=== Testing code ===

First write your code on your computer, and make sure it compiles ( python -m py_compile code.py )

Then, you can go in repl and use paste mode (^E). It only works if you paste a few lines at a time. End your paste with ^D and then if you pasted a function, call the function:
<pre>
>>> ^E
paste mode; Ctrl-C to cancel, Ctrl-D to finish
=== PASTE_YOUR_CODE_HERE
=== ^D
>>>
</pre>

=== Pushing new code ===
Occasionally you might find that the updated source code that you just used the mpfshell "put" command to transfer isn't properly stored on the ESP32 microPython flash filesystem. After rebooting, you might see unexpected errors. A simple way to check is to use the mpfshell "cat" command to check that the file was completely transferred.

The safest way to update code is to perform a reboot after transferring all the files. Doing a soft-reboot using Control-D doesn't take long, i.e it is faster and easier than doing a hard-reboot with the reset button. The good thing about a reboot (microPython interpreter restart) is that there is no confusion about the complete state of your system, i.e what references have been held onto from your older source code that might still be running in a thread or as an event handler (via the Aiko Engine framework).

You can also delete all running modules:
<pre>
import sys
sys.modules.clear()
</pre>

More details in https://spectrum.chat/lca2021-swagbadge/software/safe-software-updates~ba541e3c-d8a2-41a8-ac47-71d87696de2d

=== Replacing the swagbadge application with your own ===

Edit configuration/main.py and set "application": "application/yourcode"

=== Reboot to shell / Force runaway code to stop ===

It's possible to write code that will leave your badge unresponsive. Rebooting just reruns the same bad code. What to do?

* Place a finger on each of the bottom slider pads, either side of the microprocessor.
* Trigger a restart by using the button on the back of the badge, or Ctrl-D in repl (if you can get into repl)

The badge will restart but not autorun any code, just drop you back at the repl prompt. From there you can <code>put</code> bugfixed code back onto the device.

See https://github.com/geekscape/aiko_engine_mp/blob/a5b5593d37509df64a3dcb4cdc3d13a411152d82/main.py#L20

== Hardware reference ==

=== OLED screens ===

==== via MQTT ====

* '''(oled:clear)''' : clears both screens
* '''(oled:log Hello World!)''' : writes a message along the bottom of the screens, scrolling up whatever is there out of the way
* '''(oled:pixel x y)''' : lights a pixel at that spot
* '''(oled:text x y This is a test!)''' : Puts some text at the position x,y. It will be displayed over the top of whatever's there.

==== via API ====

On the badge, by default the two oleds work as a single long screen, with text split across both of them. You can access a specific oled and use the underlying functions to write to them

Library
* '''from aiko import oled''' # make the oled functions available for use within your code

Globals
* '''[] oled.oleds''' # an array of oleds, letting you address them separately if you choose
* '''int oled.fg/oled.bg''' # get/set fg and bg colours (0 or 1)
* '''int oled.font_size''' # helpful to work out how much space a line of text will take up
* '''boolean oled.lock_title''' # true/false. True means the display always shows the title. False means it'll be wiped once the display is cleared.

Functions
* '''oled.initialise()''' # uses configuration.oled.settings by default, normally already invoked by the base swagbadge handler
* '''oled.oleds_clear(colour)''' # pass in oled.bg or oled.fg for easy set. Wipes the display
* '''oled.log(text)''' # scroll up text to insert a new line at the bottom of the display
* '''oled.text(text, x, y, colour)''' # add text at the position x,y in the colour specified. Note: does not clear the contents at this spot first.
* '''oled.oleds_show()''' # refresh the display with the latest text/image additions
* '''oled.set_title(text)''' # set the title text
* '''oled.write_title()''' # write the title text

Coming soon - a way to easily write images to an oled.

=== Screen buttons ===

If you push (gently!) on the screens, you'll discover they double as buttons: there's a small switch under each OLED that is pressed when you push down on the screen.

{{Note|'''Warning''': Push on the '''middle''' of the screen, not the edge. This will minimise the risk of bending... and breaking... the screen.}}

The left screen button is pin 16. The right screen button is pin 17.

==== via API ====

<pre>
from machine import Pin

button_left = Pin(16, Pin.IN, Pin.PULL_UP)
button_right = Pin(17, Pin.IN, Pin.PULL_UP)

pressed = not(button_left.value())
</pre>

The button sends "1" when it's ''not'' being pressed, and "0" when it is. This is counterintuitive to most of us, so I recommend inverting the value when reading it.

=== Sliders ===

The sliders operate via capacitive touch. You can use them to detect if someone has their finger on the circular pads at either end (which let you treat them like buttons), or you can detect the position of the finger along the slider by checking the relative values as the capacitance changes.

The left slider is on pins 12 (bottom) and 15 (top), right slider is on pins 14 (bottom) and 27 (top).

More info from MicroPython about [http://docs.micropython.org/en/latest/esp32/quickref.html?highlight=touchpad#capacitive-touch capacitive touch].

<pre>
from machine import Pin, TouchPad
import aiko.common

bottom_left = TouchPad(Pin(12))
top_left = TouchPad(Pin(15))
bottom_right = TouchPad(Pin(14))
top_right = TouchPad(Pin(27))

# is this button pressed?
# the commons library returns true/false
pressed_bottom_left = common.touch_pins_check([bottom_left])

# check where we are along the slider
# the 'read' functions return an integer of the 'strength' of the
# capacitance. As you move your finger between the endpoints,
#the relative value of the difference between them will change.
slider_left = bottom_left.read() - bottom_left.read()
</pre>

Micropython functions
* '''touchpad.read()''' - gives you the current value of the sensor. It will be large when not touched (over 1000) and smaller when touched.
Aiko functions
* '''common.touch_pins_check(touchpad_array)''' - Returns true if ''all'' the touchpad sensors listed are being touched, false otherwise.

=== SAOs (simple addons) ===

Swagbadge2021 SoftwareDev

2021-01-16T23:22:47Z

Marcmerlin: /* MQTT */

{{DISPLAYTITLE:Badge Software Development}}

Want to write your own programs to run on your badge? This page gives a brief overview of the software architecture, an example of a program, and a reference guide on how to access the hardware.

<div style="float:right">
__TOC__
</div>

== Background ==
The badge runs [https://micropython.org MicroPython] (written by [http://dpgeorge.net/ Damien George] from Melbourne!) and has the [https://github.com/geekscape/aiko_engine_mp Aiko framework] (written by OHMC's [https://twitter.com/geekscape Andy Gelme]) loaded on it.

MicroPython gives you libraries to access the ESP32 microprocessor functionality. Things like: reading and writing to specific pins on the processor or performing operating system functions such as accessing the file system).

Aiko gives you convenience libraries for driving the badge hardware like the OLED screens, as well as running threads to keep your badge connected to wifi, a connection to the MQTT server, the emergency-stop function to prevent runaway code, and an automatic upgrade function so we can ship upgrades to your device without you having to wrangle git.

== Sample code ==

This code writes "Hello world" to one screen, while displaying the status of the wifi, MQTT connection, button presses and slider status on the left hand screen.

It demonstrates how to use the Aiko event loop to periodically poll for hardware state, as well as how to access some of the features of the badge.

You can find more example code in the '''examples''' directory of the [https://github.com/geekscape/aiko_engine_mp/tree/master/examples Aiko repository] on github.

<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Example code: use "expand" to view</div>
<div class="mw-collapsible-content">
<nowiki>
# examples/helloworld.py
#
# Writes a message to the oled and displays some state info
#
# Usage
# ~~~~~
# import examples.helloworld as helloworld
# from examples.helloworld import run
# run()
#

from machine import Pin, TouchPad
import aiko.event as event
import aiko.oled as oled

title = "Hello!"

import configuration.main

# Buttons: underneath the screens
button_right = Pin(17, Pin.IN, Pin.PULL_UP)
button_left = Pin(16, Pin.IN, Pin.PULL_UP)

# Clean out the whole line that was there before
# Write some new text and show it
def oled_write_line(oled_target, x, y, text):
oled_target.fill_rect(0,y,oled.width, oled.font_size, oled.bg)
oled_target.text(text, x, y)
oled_target.show()

def status():
sliders = touch_slider_handler()
oledL = oled.oleds[0]
oledR = oled.oleds[1]
oled.write_line(oledR, 1, 10, "Hello world!")
oled_write_line(oledL, 1, 10, "Wifi: "+str(net.is_connected()))
oled_write_line(oledL, 1, 20, "MQTT: "+str(mqtt.is_connected()))
oled_write_line(oledL, 1, 30, " "+str(int(not(buttonL.value())))+" Button "+str(int(not(buttonR.value()))))

# Check on the status of the badge hardware and display that every 500ms
def run():
oled.oleds_clear(oled.bg)
oled.set_title(title)
event.add_timer_handler(status, 500)
try:
event.loop()
finally:
event.remove_timer_handler(statusbar)
</nowiki>
</div></div>

== Architecture of a Swagbadge application ==

An application runs when the Aiko framework is also running, so you can rely on having all the badge services available.

An application is designed to be triggered when the badge is rebooted (either via pushing the button on the back, or via using ^D in the repl). The badge knows which application to run by the state of the <code>configuration\main.py</code> file.

The framework will call your application's '''initialise()''' function. The framework is running an event loop, so the initialise function is the place to add in event handlers to respond to actions you take on the badge.

{{Note|Note: Refreshing the OLEDs is reasonably intense on the microprocessor. If you have too many event loops triggering too often and/or too much screen activity, you can starve the badge of resources. This can produce wifi dropouts, or non-responsiveness. If you have a lot of screen activity, consider using a buffer or recording state and just doing a screen update periodically}}

== Software reference ==

=== MicroPython environment ===

[https://micropython.org MicroPython docs]

==== Special files ====

There are two special files which are run automatically by MicroPython if they exist on the filesystem: <code>boot.py</code> and <code>main.py</code>.

* '''boot.py''': This file is run first on power up/reset. We don't modify it from what MicroPython ships with, but it's important to know it exists (and not to delete it), and is interesting to look into it to see what it does.
* '''main.py''': This is run after boot.py so if you want something to automatically happen on boot/reset, this is where to put it. We use this to start up the Aiko framework, initialise the hardware (such as the network and mqtt) and start up any application that is configured inside <code>configuration/main.py</code>

==== Directory structure ====

What's on the processor? Where does it live?

* <code>main.py</code>, <code>boot.py</code> - files run on bootup
* <code>lib</code> - code in here is aiko framework code and automatically in the micropython 'path'.
** <code>aiko</code> - the aiko framework
* <code>applications</code> - programs to run automatically on bootup. Must have an initialise function
* <code>configuration</code> - control the config of aiko using files in here
* <code>examples</code> - sample code!

You can't edit the files directly on the processor (there's no editing tooling): you edit a copy of it on your computer, then use mpfshell to <code>put</code> it onto the badge.

For micropython purposes, you can use the <code>import</code> statement to import anything in the <code>lib</code> directory without prefacing it with "lib", anything else is imported from root.
For example:
* to import lib/aiko/net.py, you would use <code>import aiko.net</code>
* to import examples/showcase.py, you would use <code>import examples.showcase</code>

Because the aiko configuration files are, themselves, just python, you can also do <code>import configuration.main.settings</code> where the file is in /configuration/main.py but it contains a datastructure called 'settings'.

== Software development ==

=== MQTT ===

See [[Swagbadge2021_MQTT]]

=== Aiko ===
The Aiko Engine is what runs after boot (FreeRTOS, then microPython). Aiko provides a framework for developing applications, by providing higher level abstractions over the basic hardware, events, messaging and other conveniences. Basically, a lot of house keeping that you'd end up writing yourself. After boot, there are two background threads, one looking after Wi-Fi connectivity and the other looking after MQTT connectivity.
There are also three event handlers: MQTT keep-alive, firmware upgrader and the work-in-progress SwagBadge application handler.

<pre>
>>> aiko.event.event_list.print()
<function swagbadge_handler at 0x3ffe6c70> every 5000 next 23099
<function upgrade_handler at 0x3ffedfa0> every 5000 next 23099
<function mqtt_ping_handler at 0x3ffe9820> every 60000 next 73672
</pre>
That last handler, which every 5 seconds is updating the title bar "LCA2021" <--> "SwagBadge" (see https://github.com/geekscape/aiko_engine_mp/blob/master/applications/swagbadge.py ).

You can stop a handler, like this (this will stop the top bar status updater):
<pre>
>>> import applications.swagbadge
>>> aiko.event.remove_timer_handler(application.swagbadge_handler)
</pre>

=== Replacing the swagbadge application with your own ===

Edit configuration/main.py and set "application": "application/yourcode"

=== Pushing new code ===
Occasionally you might find that the updated source code that you just used the mpfshell "put" command to transfer isn't properly stored on the ESP32 microPython flash filesystem. After rebooting, you might see unexpected errors. A simple way to check is to use the mpfshell "cat" command to check that the file was completely transferred.

The safest way to update code is to perform a reboot after transferring all the files. Doing a soft-reboot using Control-D doesn't take long, i.e it is faster and easier than doing a hard-reboot with the reset button. The good thing about a reboot (microPython interpreter restart) is that there is no confusion about the complete state of your system, i.e what references have been held onto from your older source code that might still be running in a thread or as an event handler (via the Aiko Engine framework).

You can also delete all running modules:
<pre>
import sys
sys.modules.clear()
</pre>

More details in https://spectrum.chat/lca2021-swagbadge/software/safe-software-updates~ba541e3c-d8a2-41a8-ac47-71d87696de2d

=== Reboot to shell / Force runaway code to stop ===

It's possible to write code that will leave your badge unresponsive. Rebooting just reruns the same bad code. What to do?

* Place a finger on each of the bottom slider pads, either side of the microprocessor.
* Trigger a restart by using the button on the back of the badge, or Ctrl-D in repl (if you can get into repl)

The badge will restart but not autorun any code, just drop you back at the repl prompt. From there you can <code>put</code> bugfixed code back onto the device.

See https://github.com/geekscape/aiko_engine_mp/blob/a5b5593d37509df64a3dcb4cdc3d13a411152d82/main.py#L20

== Hardware reference ==

=== OLED screens ===

==== via MQTT ====

* '''(oled:clear)''' : clears both screens
* '''(oled:log Hello World!)''' : writes a message along the bottom of the screens, scrolling up whatever is there out of the way
* '''(oled:pixel x y)''' : lights a pixel at that spot
* '''(oled:text x y This is a test!)''' : Puts some text at the position x,y. It will be displayed over the top of whatever's there.

==== via API ====

On the badge, by default the two oleds work as a single long screen, with text split across both of them. You can access a specific oled and use the underlying functions to write to them

Library
* '''from aiko import oled''' # make the oled functions available for use within your code

Globals
* '''[] oled.oleds''' # an array of oleds, letting you address them separately if you choose
* '''int oled.fg/oled.bg''' # get/set fg and bg colours (0 or 1)
* '''int oled.font_size''' # helpful to work out how much space a line of text will take up
* '''boolean oled.lock_title''' # true/false. True means the display always shows the title. False means it'll be wiped once the display is cleared.

Functions
* '''oled.initialise()''' # uses configuration.oled.settings by default, normally already invoked by the base swagbadge handler
* '''oled.oleds_clear(colour)''' # pass in oled.bg or oled.fg for easy set. Wipes the display
* '''oled.log(text)''' # scroll up text to insert a new line at the bottom of the display
* '''oled.text(text, x, y, colour)''' # add text at the position x,y in the colour specified. Note: does not clear the contents at this spot first.
* '''oled.oleds_show()''' # refresh the display with the latest text/image additions
* '''oled.set_title(text)''' # set the title text
* '''oled.write_title()''' # write the title text

Coming soon - a way to easily write images to an oled.

=== Screen buttons ===

If you push (gently!) on the screens, you'll discover they double as buttons: there's a small switch under each OLED that is pressed when you push down on the screen.

{{Note|'''Warning''': Push on the '''middle''' of the screen, not the edge. This will minimise the risk of bending... and breaking... the screen.}}

The left screen button is pin 16. The right screen button is pin 17.

==== via API ====

<pre>
from machine import Pin

button_left = Pin(16, Pin.IN, Pin.PULL_UP)
button_right = Pin(17, Pin.IN, Pin.PULL_UP)

pressed = not(button_left.value())
</pre>

The button sends "1" when it's ''not'' being pressed, and "0" when it is. This is counterintuitive to most of us, so I recommend inverting the value when reading it.

=== Sliders ===

The sliders operate via capacitive touch. You can use them to detect if someone has their finger on the circular pads at either end (which let you treat them like buttons), or you can detect the position of the finger along the slider by checking the relative values as the capacitance changes.

The left slider is on pins 12 (bottom) and 15 (top), right slider is on pins 14 (bottom) and 27 (top).

More info from MicroPython about [http://docs.micropython.org/en/latest/esp32/quickref.html?highlight=touchpad#capacitive-touch capacitive touch].

<pre>
from machine import Pin, TouchPad
import aiko.common

bottom_left = TouchPad(Pin(12))
top_left = TouchPad(Pin(15))
bottom_right = TouchPad(Pin(14))
top_right = TouchPad(Pin(27))

# is this button pressed?
# the commons library returns true/false
pressed_bottom_left = common.touch_pins_check([bottom_left])

# check where we are along the slider
# the 'read' functions return an integer of the 'strength' of the
# capacitance. As you move your finger between the endpoints,
#the relative value of the difference between them will change.
slider_left = bottom_left.read() - bottom_left.read()
</pre>

Micropython functions
* '''touchpad.read()''' - gives you the current value of the sensor. It will be large when not touched (over 1000) and smaller when touched.
Aiko functions
* '''common.touch_pins_check(touchpad_array)''' - Returns true if ''all'' the touchpad sensors listed are being touched, false otherwise.

=== SAOs (simple addons) ===

Swagbadge2021 SoftwareDev

2021-01-16T23:22:17Z

Marcmerlin:

{{DISPLAYTITLE:Badge Software Development}}

Want to write your own programs to run on your badge? This page gives a brief overview of the software architecture, an example of a program, and a reference guide on how to access the hardware.

<div style="float:right">
__TOC__
</div>

== Background ==
The badge runs [https://micropython.org MicroPython] (written by [http://dpgeorge.net/ Damien George] from Melbourne!) and has the [https://github.com/geekscape/aiko_engine_mp Aiko framework] (written by OHMC's [https://twitter.com/geekscape Andy Gelme]) loaded on it.

MicroPython gives you libraries to access the ESP32 microprocessor functionality. Things like: reading and writing to specific pins on the processor or performing operating system functions such as accessing the file system).

Aiko gives you convenience libraries for driving the badge hardware like the OLED screens, as well as running threads to keep your badge connected to wifi, a connection to the MQTT server, the emergency-stop function to prevent runaway code, and an automatic upgrade function so we can ship upgrades to your device without you having to wrangle git.

== Sample code ==

This code writes "Hello world" to one screen, while displaying the status of the wifi, MQTT connection, button presses and slider status on the left hand screen.

It demonstrates how to use the Aiko event loop to periodically poll for hardware state, as well as how to access some of the features of the badge.

You can find more example code in the '''examples''' directory of the [https://github.com/geekscape/aiko_engine_mp/tree/master/examples Aiko repository] on github.

<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Example code: use "expand" to view</div>
<div class="mw-collapsible-content">
<nowiki>
# examples/helloworld.py
#
# Writes a message to the oled and displays some state info
#
# Usage
# ~~~~~
# import examples.helloworld as helloworld
# from examples.helloworld import run
# run()
#

from machine import Pin, TouchPad
import aiko.event as event
import aiko.oled as oled

title = "Hello!"

import configuration.main

# Buttons: underneath the screens
button_right = Pin(17, Pin.IN, Pin.PULL_UP)
button_left = Pin(16, Pin.IN, Pin.PULL_UP)

# Clean out the whole line that was there before
# Write some new text and show it
def oled_write_line(oled_target, x, y, text):
oled_target.fill_rect(0,y,oled.width, oled.font_size, oled.bg)
oled_target.text(text, x, y)
oled_target.show()

def status():
sliders = touch_slider_handler()
oledL = oled.oleds[0]
oledR = oled.oleds[1]
oled.write_line(oledR, 1, 10, "Hello world!")
oled_write_line(oledL, 1, 10, "Wifi: "+str(net.is_connected()))
oled_write_line(oledL, 1, 20, "MQTT: "+str(mqtt.is_connected()))
oled_write_line(oledL, 1, 30, " "+str(int(not(buttonL.value())))+" Button "+str(int(not(buttonR.value()))))

# Check on the status of the badge hardware and display that every 500ms
def run():
oled.oleds_clear(oled.bg)
oled.set_title(title)
event.add_timer_handler(status, 500)
try:
event.loop()
finally:
event.remove_timer_handler(statusbar)
</nowiki>
</div></div>

== Architecture of a Swagbadge application ==

An application runs when the Aiko framework is also running, so you can rely on having all the badge services available.

An application is designed to be triggered when the badge is rebooted (either via pushing the button on the back, or via using ^D in the repl). The badge knows which application to run by the state of the <code>configuration\main.py</code> file.

The framework will call your application's '''initialise()''' function. The framework is running an event loop, so the initialise function is the place to add in event handlers to respond to actions you take on the badge.

{{Note|Note: Refreshing the OLEDs is reasonably intense on the microprocessor. If you have too many event loops triggering too often and/or too much screen activity, you can starve the badge of resources. This can produce wifi dropouts, or non-responsiveness. If you have a lot of screen activity, consider using a buffer or recording state and just doing a screen update periodically}}

== Software reference ==

=== MicroPython environment ===

[https://micropython.org MicroPython docs]

==== Special files ====

There are two special files which are run automatically by MicroPython if they exist on the filesystem: <code>boot.py</code> and <code>main.py</code>.

* '''boot.py''': This file is run first on power up/reset. We don't modify it from what MicroPython ships with, but it's important to know it exists (and not to delete it), and is interesting to look into it to see what it does.
* '''main.py''': This is run after boot.py so if you want something to automatically happen on boot/reset, this is where to put it. We use this to start up the Aiko framework, initialise the hardware (such as the network and mqtt) and start up any application that is configured inside <code>configuration/main.py</code>

==== Directory structure ====

What's on the processor? Where does it live?

* <code>main.py</code>, <code>boot.py</code> - files run on bootup
* <code>lib</code> - code in here is aiko framework code and automatically in the micropython 'path'.
** <code>aiko</code> - the aiko framework
* <code>applications</code> - programs to run automatically on bootup. Must have an initialise function
* <code>configuration</code> - control the config of aiko using files in here
* <code>examples</code> - sample code!

You can't edit the files directly on the processor (there's no editing tooling): you edit a copy of it on your computer, then use mpfshell to <code>put</code> it onto the badge.

For micropython purposes, you can use the <code>import</code> statement to import anything in the <code>lib</code> directory without prefacing it with "lib", anything else is imported from root.
For example:
* to import lib/aiko/net.py, you would use <code>import aiko.net</code>
* to import examples/showcase.py, you would use <code>import examples.showcase</code>

Because the aiko configuration files are, themselves, just python, you can also do <code>import configuration.main.settings</code> where the file is in /configuration/main.py but it contains a datastructure called 'settings'.

== Software development ==

=== MQTT ===

See [[Link Swagbadge2021_MQTT]]

=== Aiko ===
The Aiko Engine is what runs after boot (FreeRTOS, then microPython). Aiko provides a framework for developing applications, by providing higher level abstractions over the basic hardware, events, messaging and other conveniences. Basically, a lot of house keeping that you'd end up writing yourself. After boot, there are two background threads, one looking after Wi-Fi connectivity and the other looking after MQTT connectivity.
There are also three event handlers: MQTT keep-alive, firmware upgrader and the work-in-progress SwagBadge application handler.

<pre>
>>> aiko.event.event_list.print()
<function swagbadge_handler at 0x3ffe6c70> every 5000 next 23099
<function upgrade_handler at 0x3ffedfa0> every 5000 next 23099
<function mqtt_ping_handler at 0x3ffe9820> every 60000 next 73672
</pre>
That last handler, which every 5 seconds is updating the title bar "LCA2021" <--> "SwagBadge" (see https://github.com/geekscape/aiko_engine_mp/blob/master/applications/swagbadge.py ).

You can stop a handler, like this (this will stop the top bar status updater):
<pre>
>>> import applications.swagbadge
>>> aiko.event.remove_timer_handler(application.swagbadge_handler)
</pre>

=== Replacing the swagbadge application with your own ===

Edit configuration/main.py and set "application": "application/yourcode"

=== Pushing new code ===
Occasionally you might find that the updated source code that you just used the mpfshell "put" command to transfer isn't properly stored on the ESP32 microPython flash filesystem. After rebooting, you might see unexpected errors. A simple way to check is to use the mpfshell "cat" command to check that the file was completely transferred.

The safest way to update code is to perform a reboot after transferring all the files. Doing a soft-reboot using Control-D doesn't take long, i.e it is faster and easier than doing a hard-reboot with the reset button. The good thing about a reboot (microPython interpreter restart) is that there is no confusion about the complete state of your system, i.e what references have been held onto from your older source code that might still be running in a thread or as an event handler (via the Aiko Engine framework).

You can also delete all running modules:
<pre>
import sys
sys.modules.clear()
</pre>

More details in https://spectrum.chat/lca2021-swagbadge/software/safe-software-updates~ba541e3c-d8a2-41a8-ac47-71d87696de2d

=== Reboot to shell / Force runaway code to stop ===

It's possible to write code that will leave your badge unresponsive. Rebooting just reruns the same bad code. What to do?

* Place a finger on each of the bottom slider pads, either side of the microprocessor.
* Trigger a restart by using the button on the back of the badge, or Ctrl-D in repl (if you can get into repl)

The badge will restart but not autorun any code, just drop you back at the repl prompt. From there you can <code>put</code> bugfixed code back onto the device.

See https://github.com/geekscape/aiko_engine_mp/blob/a5b5593d37509df64a3dcb4cdc3d13a411152d82/main.py#L20

== Hardware reference ==

=== OLED screens ===

==== via MQTT ====

* '''(oled:clear)''' : clears both screens
* '''(oled:log Hello World!)''' : writes a message along the bottom of the screens, scrolling up whatever is there out of the way
* '''(oled:pixel x y)''' : lights a pixel at that spot
* '''(oled:text x y This is a test!)''' : Puts some text at the position x,y. It will be displayed over the top of whatever's there.

==== via API ====

On the badge, by default the two oleds work as a single long screen, with text split across both of them. You can access a specific oled and use the underlying functions to write to them

Library
* '''from aiko import oled''' # make the oled functions available for use within your code

Globals
* '''[] oled.oleds''' # an array of oleds, letting you address them separately if you choose
* '''int oled.fg/oled.bg''' # get/set fg and bg colours (0 or 1)
* '''int oled.font_size''' # helpful to work out how much space a line of text will take up
* '''boolean oled.lock_title''' # true/false. True means the display always shows the title. False means it'll be wiped once the display is cleared.

Functions
* '''oled.initialise()''' # uses configuration.oled.settings by default, normally already invoked by the base swagbadge handler
* '''oled.oleds_clear(colour)''' # pass in oled.bg or oled.fg for easy set. Wipes the display
* '''oled.log(text)''' # scroll up text to insert a new line at the bottom of the display
* '''oled.text(text, x, y, colour)''' # add text at the position x,y in the colour specified. Note: does not clear the contents at this spot first.
* '''oled.oleds_show()''' # refresh the display with the latest text/image additions
* '''oled.set_title(text)''' # set the title text
* '''oled.write_title()''' # write the title text

Coming soon - a way to easily write images to an oled.

=== Screen buttons ===

If you push (gently!) on the screens, you'll discover they double as buttons: there's a small switch under each OLED that is pressed when you push down on the screen.

{{Note|'''Warning''': Push on the '''middle''' of the screen, not the edge. This will minimise the risk of bending... and breaking... the screen.}}

The left screen button is pin 16. The right screen button is pin 17.

==== via API ====

<pre>
from machine import Pin

button_left = Pin(16, Pin.IN, Pin.PULL_UP)
button_right = Pin(17, Pin.IN, Pin.PULL_UP)

pressed = not(button_left.value())
</pre>

The button sends "1" when it's ''not'' being pressed, and "0" when it is. This is counterintuitive to most of us, so I recommend inverting the value when reading it.

=== Sliders ===

The sliders operate via capacitive touch. You can use them to detect if someone has their finger on the circular pads at either end (which let you treat them like buttons), or you can detect the position of the finger along the slider by checking the relative values as the capacitance changes.

The left slider is on pins 12 (bottom) and 15 (top), right slider is on pins 14 (bottom) and 27 (top).

More info from MicroPython about [http://docs.micropython.org/en/latest/esp32/quickref.html?highlight=touchpad#capacitive-touch capacitive touch].

<pre>
from machine import Pin, TouchPad
import aiko.common

bottom_left = TouchPad(Pin(12))
top_left = TouchPad(Pin(15))
bottom_right = TouchPad(Pin(14))
top_right = TouchPad(Pin(27))

# is this button pressed?
# the commons library returns true/false
pressed_bottom_left = common.touch_pins_check([bottom_left])

# check where we are along the slider
# the 'read' functions return an integer of the 'strength' of the
# capacitance. As you move your finger between the endpoints,
#the relative value of the difference between them will change.
slider_left = bottom_left.read() - bottom_left.read()
</pre>

Micropython functions
* '''touchpad.read()''' - gives you the current value of the sensor. It will be large when not touched (over 1000) and smaller when touched.
Aiko functions
* '''common.touch_pins_check(touchpad_array)''' - Returns true if ''all'' the touchpad sensors listed are being touched, false otherwise.

=== SAOs (simple addons) ===

Swagbadge2021 UpdatingSoftware

2021-01-16T23:21:05Z

Marcmerlin: /* Software development */

= Updating the software framework =

Swagbadge owners might want to update the software framework (Aiko). Dagbadge owners will need to put the framework onto their badge before they can use it.

Here's how to do that!

== Requirements ==

* #swagbadge or #dagbadge or any ESP32 with an OLED screen
* Micro-USB cable
* Linux, Mac OS or Linux system running Python 3
* Command line tools: git

== Setting up your Windows 10 system for connecting to badge hardware ==

How to find your serial COM port on Windows:
* Use the Device Manager.
* Under the "Ports" category, 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.

Windows 10 may automatically discover your #swagbadge USB hardware and automatically install the correct USB serial hardware driver, or if nothing still shows up, you might need to update your USB drivers for supporting the USB hardware CP210x on your #swagbadge, please follow these instructions:
* Download the CP210x drivers from [https://www.silabs.com/developers/usb-to-uart-bridge-vcp-drivers Silicon Labs Windows Universal Driver]
* Unpack the zip file
* Follow the Silicon Labs instructions for [https://www.silabs.com/documents/public/application-notes/AN335.pdf INF only install] (Section 5 on page 9)

By this point, you have know the serial COM port that your #swagbadge is connected to, e.g COM4

== Setting up your Mac OS system for connecting to #swagbadge hardware ==

How to find your serial COM port on OS X:

$ ls /dev/tty.usb*

Unless you have lot of dev boards (or maybe a phone) plugged in you should just see a single filename there.
Use this (without the `/dev/` prefix) when using the `open` command in `mpfshell`

To get a working `mpfshell` install a recent version of Python (Python3.8 is known to work) using a installed DMG.
Then create a *venv* and install the necessary tools using pip.
For example:

$ mkdir swag
$ cd swag
$ python3.8 -m venv env
$ ./env/bin/pip install esptool mpfshell

You can then run `mpfshell` to connect:

$ ./env/bin/mpfshell
mpfs [/]> open <your device node as found previously>

== Setting up your Linux system for connecting to #swagbadge hardware ==
[Link other instructions here]

== Setting up your Windows 10 system for installing #swagbadge firmware ==

* Install [https://docs.conda.io/en/latest/miniconda.html Miniconda3] to create a specific Python development environment. (Note we are using Python3 not Python2)
* Create specific Python 3 environment for playing around with your #swagbadge
** Start an Anaconda Powershell Prompt (aka Windows Terminal)
** <code>conda create --yes -n swagbadge python=3</code>
** <code>conda activate swagbadge</code>
* Your command prompt should now look like: <code>(swagbadge) C:\Users\[Username]></code>

* Install some python tools to let us prepare and communicate with the badge
** <code>pip install esptool mpfshell</code>

* To test that the required tools are installed, trying running the following commands
** <code>esptool</code> # Should show you help on running the esptool
** <code>mpfshell</code> # Should show three lines of output
*** <code>exit</code> # To exit mpfshell

== Download #swagbadge (Aiko Engine) firmware ==

Within your Anaconda Prompt session, change directory to where you’d like the #swagbadge software to be downloaded, for example:
* <code>cd $HOME/software</code>

Download #swagbadge firmware:
* <code>git clone https://github.com/geekscape/aiko_engine_mp.git</code> # NOTE: this URL will change once we're live
* <code>cd aiko_engine_mp</code>

Install MicroPython
* Create a directory to hold the MicroPython firmware, such as aiko_engine_mp/firmware/
* <code>mkdir firmware</code>
* Using your web browser, download: [http://micropython.org/resources/firmware/esp32-idf4-20200902-v1.13.bin esp32-idf4-20200902-v1.13.bin] (mouse right button click → [Save As …] saving the MicroPython firmware in the firmware directory you just made.
** The [http://micropython.org/download/ MicroPython download list] has a link to a bunch of firmware drivers, we are using the one for the esp32 device, with the latest 1.4 generic

Erase #swagbadge LoLin-Lite ESP32 flash memory
* <code>esptool --chip esp32 --port COM3 erase_flash</code> # adjust the port to suit.
* You’ll know it’s worked, if the output finishes with “Hard resetting via RTS pin…”

Install microPython on the badge
* <code>esptool --chip esp32 --port COM3 --baud 460800 write_flash -z 0x1000 firmware\esp32-idf4-20200902-v1.13.bin</code> #adjust port and firmware location if necessary
* You’ll know it’s worked, if the output finishes with “Hard resetting via RTS pin…”

Test that the software is installed correctly by using mpfshell
* <code>mpfshell -o COM3</code> # Adjust port to suit
* If it has made a connection to your badge, you will see it say
<nowiki>Connected to esp32
** Micropython File Shell v0.9.1, sw@kaltpost.de **
-- Running on Python 3.8 using PySerial 3.4 --
mpfs [/]> </nowiki>

== Using mpfshell ==

mpfshell has two functions: it lets you put files on/off the device, and it can give you a python shell to execute code on the device.
* Getting files on/off the device is a bit like commandline ftp
** ls - looks at the files on your micropython device
** lls - looks at the files on your local computer in the current directory
** put - puts a file to the device
** cat - shows you the contents of the file
** help() - gives you more information on the commands
** repl - opens up the python shell on the badge

Note: To get out of repl, use Ctrl-Q (on Windows) which drops you back into mpfshell

A little program to say hello world!
* <code> >>> print("hello world")</code>
* Output: <code>hello world</code>

A little program to turn the blue light on the board on and off (this is on the underside of the Swagbadge, visible through a circular cutout)
<nowiki>>>> import machine
>>> pin22=machine.Pin(22, machine.Pin.OUT, machine.Pin.PULL_UP)
>>> pin22.value(0)
>>> pin22.value(1)</nowiki>

== Saving your private key ==

Use mpfshell to get the file: `configuration/keys.db`.

== Putting the Aiko framework onto the device, using mpfshell ==
* <code>mpfshell COM5 -s scripts\aiko.mpf</code> #run from within the aiko_framework_mp directory

=== Windows only: Patch mpfshell ===

''Note!'' mpfshell needs a patch applied to let it run a script under Windows.

* Inside <code>C:/users/USERNAME/Miniconda2/envs/swagbadge/Lib/site-packages/mp</code>
* edit <code>mpfshell.py</code>
* Search for <code>elif args.script is not None:</code>, around line 796
* between that line and the next, insert two lines. It should look like:
<nowiki>
elif args.script is not None:

if platform.system() == "Windows": #INSERT THIS LINE
mpfs.use_rawinput = True #INSERT THIS LINE

f = open(args.script, "r")
</nowiki>
* Python is very particular about spacing. The rest of the code uses 4 spaces for indents so follow suit.

= Software development =

See [[Swagbadge2021_SoftwareDev]]

Swagbadge2021 SoftwareDev

2021-01-16T23:20:10Z

Marcmerlin:

{{DISPLAYTITLE:Badge Software Development}}

Want to write your own programs to run on your badge? This page gives a brief overview of the software architecture, an example of a program, and a reference guide on how to access the hardware.

<div style="float:right">
__TOC__
</div>

== Background ==
The badge runs [https://micropython.org MicroPython] (written by [http://dpgeorge.net/ Damien George] from Melbourne!) and has the [https://github.com/geekscape/aiko_engine_mp Aiko framework] (written by OHMC's [https://twitter.com/geekscape Andy Gelme]) loaded on it.

MicroPython gives you libraries to access the ESP32 microprocessor functionality. Things like: reading and writing to specific pins on the processor or performing operating system functions such as accessing the file system).

Aiko gives you convenience libraries for driving the badge hardware like the OLED screens, as well as running threads to keep your badge connected to wifi, a connection to the MQTT server, the emergency-stop function to prevent runaway code, and an automatic upgrade function so we can ship upgrades to your device without you having to wrangle git.

== Sample code ==

This code writes "Hello world" to one screen, while displaying the status of the wifi, MQTT connection, button presses and slider status on the left hand screen.

It demonstrates how to use the Aiko event loop to periodically poll for hardware state, as well as how to access some of the features of the badge.

You can find more example code in the '''examples''' directory of the [https://github.com/geekscape/aiko_engine_mp/tree/master/examples Aiko repository] on github.

<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Example code: use "expand" to view</div>
<div class="mw-collapsible-content">
<nowiki>
# examples/helloworld.py
#
# Writes a message to the oled and displays some state info
#
# Usage
# ~~~~~
# import examples.helloworld as helloworld
# from examples.helloworld import run
# run()
#

from machine import Pin, TouchPad
import aiko.event as event
import aiko.oled as oled

title = "Hello!"

import configuration.main

# Buttons: underneath the screens
button_right = Pin(17, Pin.IN, Pin.PULL_UP)
button_left = Pin(16, Pin.IN, Pin.PULL_UP)

# Clean out the whole line that was there before
# Write some new text and show it
def oled_write_line(oled_target, x, y, text):
oled_target.fill_rect(0,y,oled.width, oled.font_size, oled.bg)
oled_target.text(text, x, y)
oled_target.show()

def status():
sliders = touch_slider_handler()
oledL = oled.oleds[0]
oledR = oled.oleds[1]
oled.write_line(oledR, 1, 10, "Hello world!")
oled_write_line(oledL, 1, 10, "Wifi: "+str(net.is_connected()))
oled_write_line(oledL, 1, 20, "MQTT: "+str(mqtt.is_connected()))
oled_write_line(oledL, 1, 30, " "+str(int(not(buttonL.value())))+" Button "+str(int(not(buttonR.value()))))

# Check on the status of the badge hardware and display that every 500ms
def run():
oled.oleds_clear(oled.bg)
oled.set_title(title)
event.add_timer_handler(status, 500)
try:
event.loop()
finally:
event.remove_timer_handler(statusbar)
</nowiki>
</div></div>

== Architecture of a Swagbadge application ==

An application runs when the Aiko framework is also running, so you can rely on having all the badge services available.

An application is designed to be triggered when the badge is rebooted (either via pushing the button on the back, or via using ^D in the repl). The badge knows which application to run by the state of the <code>configuration\main.py</code> file.

The framework will call your application's '''initialise()''' function. The framework is running an event loop, so the initialise function is the place to add in event handlers to respond to actions you take on the badge.

{{Note|Note: Refreshing the OLEDs is reasonably intense on the microprocessor. If you have too many event loops triggering too often and/or too much screen activity, you can starve the badge of resources. This can produce wifi dropouts, or non-responsiveness. If you have a lot of screen activity, consider using a buffer or recording state and just doing a screen update periodically}}

== Software reference ==

=== MicroPython environment ===

[https://micropython.org MicroPython docs]

==== Special files ====

There are two special files which are run automatically by MicroPython if they exist on the filesystem: <code>boot.py</code> and <code>main.py</code>.

* '''boot.py''': This file is run first on power up/reset. We don't modify it from what MicroPython ships with, but it's important to know it exists (and not to delete it), and is interesting to look into it to see what it does.
* '''main.py''': This is run after boot.py so if you want something to automatically happen on boot/reset, this is where to put it. We use this to start up the Aiko framework, initialise the hardware (such as the network and mqtt) and start up any application that is configured inside <code>configuration/main.py</code>

==== Directory structure ====

What's on the processor? Where does it live?

* <code>main.py</code>, <code>boot.py</code> - files run on bootup
* <code>lib</code> - code in here is aiko framework code and automatically in the micropython 'path'.
** <code>aiko</code> - the aiko framework
* <code>applications</code> - programs to run automatically on bootup. Must have an initialise function
* <code>configuration</code> - control the config of aiko using files in here
* <code>examples</code> - sample code!

You can't edit the files directly on the processor (there's no editing tooling): you edit a copy of it on your computer, then use mpfshell to <code>put</code> it onto the badge.

For micropython purposes, you can use the <code>import</code> statement to import anything in the <code>lib</code> directory without prefacing it with "lib", anything else is imported from root.
For example:
* to import lib/aiko/net.py, you would use <code>import aiko.net</code>
* to import examples/showcase.py, you would use <code>import examples.showcase</code>

Because the aiko configuration files are, themselves, just python, you can also do <code>import configuration.main.settings</code> where the file is in /configuration/main.py but it contains a datastructure called 'settings'.

=== MQTT ===

See [[Link Swagbadge2021_MQTT]]

=== Aiko ===
The Aiko Engine is what runs after boot (FreeRTOS, then microPython). Aiko provides a framework for developing applications, by providing higher level abstractions over the basic hardware, events, messaging and other conveniences. Basically, a lot of house keeping that you'd end up writing yourself. After boot, there are two background threads, one looking after Wi-Fi connectivity and the other looking after MQTT connectivity.
There are also three event handlers: MQTT keep-alive, firmware upgrader and the work-in-progress SwagBadge application handler.

<pre>
>>> aiko.event.event_list.print()
<function swagbadge_handler at 0x3ffe6c70> every 5000 next 23099
<function upgrade_handler at 0x3ffedfa0> every 5000 next 23099
<function mqtt_ping_handler at 0x3ffe9820> every 60000 next 73672
</pre>
That last handler, which every 5 seconds is updating the title bar "LCA2021" <--> "SwagBadge" (see https://github.com/geekscape/aiko_engine_mp/blob/master/applications/swagbadge.py ).

You can stop a handler, like this (this will stop the top bar status updater):
<pre>
>>> import applications.swagbadge
>>> aiko.event.remove_timer_handler(application.swagbadge_handler)
</pre>

=== Replacing the swagbadge application with your own ===

Edit configuration/main.py and set "application": "application/yourcode"

=== Pushing new code ===
Occasionally you might find that the updated source code that you just used the mpfshell "put" command to transfer isn't properly stored on the ESP32 microPython flash filesystem. After rebooting, you might see unexpected errors. A simple way to check is to use the mpfshell "cat" command to check that the file was completely transferred.

The safest way to update code is to perform a reboot after transferring all the files. Doing a soft-reboot using Control-D doesn't take long, i.e it is faster and easier than doing a hard-reboot with the reset button. The good thing about a reboot (microPython interpreter restart) is that there is no confusion about the complete state of your system, i.e what references have been held onto from your older source code that might still be running in a thread or as an event handler (via the Aiko Engine framework).

You can also delete all running modules:
<pre>
import sys
sys.modules.clear()
</pre>

More details in https://spectrum.chat/lca2021-swagbadge/software/safe-software-updates~ba541e3c-d8a2-41a8-ac47-71d87696de2d

=== Reboot to shell / Force runaway code to stop ===

It's possible to write code that will leave your badge unresponsive. Rebooting just reruns the same bad code. What to do?

* Place a finger on each of the bottom slider pads, either side of the microprocessor.
* Trigger a restart by using the button on the back of the badge, or Ctrl-D in repl (if you can get into repl)

The badge will restart but not autorun any code, just drop you back at the repl prompt. From there you can <code>put</code> bugfixed code back onto the device.

See https://github.com/geekscape/aiko_engine_mp/blob/a5b5593d37509df64a3dcb4cdc3d13a411152d82/main.py#L20

== Hardware reference ==

=== OLED screens ===

==== via MQTT ====

* '''(oled:clear)''' : clears both screens
* '''(oled:log Hello World!)''' : writes a message along the bottom of the screens, scrolling up whatever is there out of the way
* '''(oled:pixel x y)''' : lights a pixel at that spot
* '''(oled:text x y This is a test!)''' : Puts some text at the position x,y. It will be displayed over the top of whatever's there.

==== via API ====

On the badge, by default the two oleds work as a single long screen, with text split across both of them. You can access a specific oled and use the underlying functions to write to them

Library
* '''from aiko import oled''' # make the oled functions available for use within your code

Globals
* '''[] oled.oleds''' # an array of oleds, letting you address them separately if you choose
* '''int oled.fg/oled.bg''' # get/set fg and bg colours (0 or 1)
* '''int oled.font_size''' # helpful to work out how much space a line of text will take up
* '''boolean oled.lock_title''' # true/false. True means the display always shows the title. False means it'll be wiped once the display is cleared.

Functions
* '''oled.initialise()''' # uses configuration.oled.settings by default, normally already invoked by the base swagbadge handler
* '''oled.oleds_clear(colour)''' # pass in oled.bg or oled.fg for easy set. Wipes the display
* '''oled.log(text)''' # scroll up text to insert a new line at the bottom of the display
* '''oled.text(text, x, y, colour)''' # add text at the position x,y in the colour specified. Note: does not clear the contents at this spot first.
* '''oled.oleds_show()''' # refresh the display with the latest text/image additions
* '''oled.set_title(text)''' # set the title text
* '''oled.write_title()''' # write the title text

Coming soon - a way to easily write images to an oled.

=== Screen buttons ===

If you push (gently!) on the screens, you'll discover they double as buttons: there's a small switch under each OLED that is pressed when you push down on the screen.

{{Note|'''Warning''': Push on the '''middle''' of the screen, not the edge. This will minimise the risk of bending... and breaking... the screen.}}

The left screen button is pin 16. The right screen button is pin 17.

==== via API ====

<pre>
from machine import Pin

button_left = Pin(16, Pin.IN, Pin.PULL_UP)
button_right = Pin(17, Pin.IN, Pin.PULL_UP)

pressed = not(button_left.value())
</pre>

The button sends "1" when it's ''not'' being pressed, and "0" when it is. This is counterintuitive to most of us, so I recommend inverting the value when reading it.

=== Sliders ===

The sliders operate via capacitive touch. You can use them to detect if someone has their finger on the circular pads at either end (which let you treat them like buttons), or you can detect the position of the finger along the slider by checking the relative values as the capacitance changes.

The left slider is on pins 12 (bottom) and 15 (top), right slider is on pins 14 (bottom) and 27 (top).

More info from MicroPython about [http://docs.micropython.org/en/latest/esp32/quickref.html?highlight=touchpad#capacitive-touch capacitive touch].

<pre>
from machine import Pin, TouchPad
import aiko.common

bottom_left = TouchPad(Pin(12))
top_left = TouchPad(Pin(15))
bottom_right = TouchPad(Pin(14))
top_right = TouchPad(Pin(27))

# is this button pressed?
# the commons library returns true/false
pressed_bottom_left = common.touch_pins_check([bottom_left])

# check where we are along the slider
# the 'read' functions return an integer of the 'strength' of the
# capacitance. As you move your finger between the endpoints,
#the relative value of the difference between them will change.
slider_left = bottom_left.read() - bottom_left.read()
</pre>

Micropython functions
* '''touchpad.read()''' - gives you the current value of the sensor. It will be large when not touched (over 1000) and smaller when touched.
Aiko functions
* '''common.touch_pins_check(touchpad_array)''' - Returns true if ''all'' the touchpad sensors listed are being touched, false otherwise.

=== SAOs (simple addons) ===

Swagbadge2021 GettingStarted

2021-01-16T23:13:44Z

Marcmerlin: /* Hardware pinout */

= 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. ==
* 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.
* 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 ==

'''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.

=== Getting the device on your wifi - wireless ===

* 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 2.4GHz network: it is not compatible with 5GHz WiFi.''
* 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.

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 setting up via the wifi AP (access point) doesn't work, you can put a configuration file onto the badge.
* 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 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: <code>mpfshell -o COM3</code>
* <code>put configuration/net.py configuration/net.py</code>
* 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.

On bootup you should now see...

= 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 [[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-schematic.pdf
<pre>
- GPIO0 : left breakout pin4
- GPIO2 : left breakout pin3

- 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
- GPIO14/27: slider #2
- GPIO16: left switch (under screen #1)
- GPIO17: right switch (under screen #2)

- GPIO18: SAO3 pin3 + LB pin7
- GPIO23: SAO3 pin4

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

- GPIO25: SAO4 pin4 + RB pin6
- GPIO26: SAO4 pin3 + RB pin7

- 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 pin3
- GPIO35: right breakout pin3
</pre>

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

* [[Swagbadge2021_UpdatingSoftware|Updating the Software]]
* [[Swagbadge2021_SoftwareDev|Writing your own badge programs]]

Swagbadge2021 UpdatingSoftware

2021-01-16T22:07:55Z

Marcmerlin:

= Updating the software framework =

Swagbadge owners might want to update the software framework (Aiko). Dagbadge owners will need to put the framework onto their badge before they can use it.

Here's how to do that!

== Requirements ==

* #swagbadge or #dagbadge or any ESP32 with an OLED screen
* Micro-USB cable
* Linux, Mac OS or Linux system running Python 3
* Command line tools: git

== Setting up your Windows 10 system for connecting to badge hardware ==

How to find your serial COM port on Windows:
* Use the Device Manager.
* Under the "Ports" category, 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.

Windows 10 may automatically discover your #swagbadge USB hardware and automatically install the correct USB serial hardware driver, or if nothing still shows up, you might need to update your USB drivers for supporting the USB hardware CP210x on your #swagbadge, please follow these instructions:
* Download the CP210x drivers from [https://www.silabs.com/developers/usb-to-uart-bridge-vcp-drivers Silicon Labs Windows Universal Driver]
* Unpack the zip file
* Follow the Silicon Labs instructions for [https://www.silabs.com/documents/public/application-notes/AN335.pdf INF only install] (Section 5 on page 9)

By this point, you have know the serial COM port that your #swagbadge is connected to, e.g COM4

== Setting up your Mac OS system for connecting to #swagbadge hardware ==

How to find your serial COM port on OS X:

$ ls /dev/tty.usb*

Unless you have lot of dev boards (or maybe a phone) plugged in you should just see a single filename there.
Use this (without the `/dev/` prefix) when using the `open` command in `mpfshell`

To get a working `mpfshell` install a recent version of Python (Python3.8 is known to work) using a installed DMG.
Then create a *venv* and install the necessary tools using pip.
For example:

$ mkdir swag
$ cd swag
$ python3.8 -m venv env
$ ./env/bin/pip install esptool mpfshell

You can then run `mpfshell` to connect:

$ ./env/bin/mpfshell
mpfs [/]> open <your device node as found previously>

== Setting up your Linux system for connecting to #swagbadge hardware ==
[Link other instructions here]

== Setting up your Windows 10 system for installing #swagbadge firmware ==

* Install [https://docs.conda.io/en/latest/miniconda.html Miniconda3] to create a specific Python development environment. (Note we are using Python3 not Python2)
* Create specific Python 3 environment for playing around with your #swagbadge
** Start an Anaconda Powershell Prompt (aka Windows Terminal)
** <code>conda create --yes -n swagbadge python=3</code>
** <code>conda activate swagbadge</code>
* Your command prompt should now look like: <code>(swagbadge) C:\Users\[Username]></code>

* Install some python tools to let us prepare and communicate with the badge
** <code>pip install esptool mpfshell</code>

* To test that the required tools are installed, trying running the following commands
** <code>esptool</code> # Should show you help on running the esptool
** <code>mpfshell</code> # Should show three lines of output
*** <code>exit</code> # To exit mpfshell

== Download #swagbadge (Aiko Engine) firmware ==

Within your Anaconda Prompt session, change directory to where you’d like the #swagbadge software to be downloaded, for example:
* <code>cd $HOME/software</code>

Download #swagbadge firmware:
* <code>git clone https://github.com/geekscape/aiko_engine_mp.git</code> # NOTE: this URL will change once we're live
* <code>cd aiko_engine_mp</code>

Install MicroPython
* Create a directory to hold the MicroPython firmware, such as aiko_engine_mp/firmware/
* <code>mkdir firmware</code>
* Using your web browser, download: [http://micropython.org/resources/firmware/esp32-idf4-20200902-v1.13.bin esp32-idf4-20200902-v1.13.bin] (mouse right button click → [Save As …] saving the MicroPython firmware in the firmware directory you just made.
** The [http://micropython.org/download/ MicroPython download list] has a link to a bunch of firmware drivers, we are using the one for the esp32 device, with the latest 1.4 generic

Erase #swagbadge LoLin-Lite ESP32 flash memory
* <code>esptool --chip esp32 --port COM3 erase_flash</code> # adjust the port to suit.
* You’ll know it’s worked, if the output finishes with “Hard resetting via RTS pin…”

Install microPython on the badge
* <code>esptool --chip esp32 --port COM3 --baud 460800 write_flash -z 0x1000 firmware\esp32-idf4-20200902-v1.13.bin</code> #adjust port and firmware location if necessary
* You’ll know it’s worked, if the output finishes with “Hard resetting via RTS pin…”

Test that the software is installed correctly by using mpfshell
* <code>mpfshell -o COM3</code> # Adjust port to suit
* If it has made a connection to your badge, you will see it say
<nowiki>Connected to esp32
** Micropython File Shell v0.9.1, sw@kaltpost.de **
-- Running on Python 3.8 using PySerial 3.4 --
mpfs [/]> </nowiki>

== Using mpfshell ==

mpfshell has two functions: it lets you put files on/off the device, and it can give you a python shell to execute code on the device.
* Getting files on/off the device is a bit like commandline ftp
** ls - looks at the files on your micropython device
** lls - looks at the files on your local computer in the current directory
** put - puts a file to the device
** cat - shows you the contents of the file
** help() - gives you more information on the commands
** repl - opens up the python shell on the badge

Note: To get out of repl, use Ctrl-Q (on Windows) which drops you back into mpfshell

A little program to say hello world!
* <code> >>> print("hello world")</code>
* Output: <code>hello world</code>

A little program to turn the blue light on the board on and off (this is on the underside of the Swagbadge, visible through a circular cutout)
<nowiki>>>> import machine
>>> pin22=machine.Pin(22, machine.Pin.OUT, machine.Pin.PULL_UP)
>>> pin22.value(0)
>>> pin22.value(1)</nowiki>

== Saving your private key ==

Use mpfshell to get the file: `configuration/keys.db`.

== Putting the Aiko framework onto the device, using mpfshell ==
* <code>mpfshell COM5 -s scripts\aiko.mpf</code> #run from within the aiko_framework_mp directory

=== Windows only: Patch mpfshell ===

''Note!'' mpfshell needs a patch applied to let it run a script under Windows.

* Inside <code>C:/users/USERNAME/Miniconda2/envs/swagbadge/Lib/site-packages/mp</code>
* edit <code>mpfshell.py</code>
* Search for <code>elif args.script is not None:</code>, around line 796
* between that line and the next, insert two lines. It should look like:
<nowiki>
elif args.script is not None:

if platform.system() == "Windows": #INSERT THIS LINE
mpfs.use_rawinput = True #INSERT THIS LINE

f = open(args.script, "r")
</nowiki>
* Python is very particular about spacing. The rest of the code uses 4 spaces for indents so follow suit.

= Software development =

== Aiko ==
The Aiko Engine is what runs after boot (FreeRTOS, then microPython). Aiko provides a framework for developing applications, by providing higher level abstractions over the basic hardware, events, messaging and other conveniences. Basically, a lot of house keeping that you'd end up writing yourself. After boot, there are two background threads, one looking after Wi-Fi connectivity and the other looking after MQTT connectivity.
There are also three event handlers: MQTT keep-alive, firmware upgrader and the work-in-progress SwagBadge application handler.

<pre>
>>> aiko.event.event_list.print()
<function swagbadge_handler at 0x3ffe6c70> every 5000 next 23099
<function upgrade_handler at 0x3ffedfa0> every 5000 next 23099
<function mqtt_ping_handler at 0x3ffe9820> every 60000 next 73672
</pre>
That last handler, which every 5 seconds is updating the title bar "LCA2021" <--> "SwagBadge" (see https://github.com/geekscape/aiko_engine_mp/blob/master/applications/swagbadge.py ).

You can stop a handler, like this (this will stop the top bar status updater):
<pre>
>>> import applications.swagbadge
>>> aiko.event.remove_timer_handler(application.swagbadge_handler)
</pre>

== Replacing the swagbadge application with your own ==

Edit configuration/main.py and set "application": "application/yourcode"

== Pushing new code ==
Occasionally you might find that the updated source code that you just used the mpfshell "put" command to transfer isn't properly stored on the ESP32 microPython flash filesystem. After rebooting, you might see unexpected errors. A simple way to check is to use the mpfshell "cat" command to check that the file was completely transferred.

The safest way to update code is to perform a reboot after transferring all the files. Doing a soft-reboot using Control-D doesn't take long, i.e it is faster and easier than doing a hard-reboot with the reset button. The good thing about a reboot (microPython interpreter restart) is that there is no confusion about the complete state of your system, i.e what references have been held onto from your older source code that might still be running in a thread or as an event handler (via the Aiko Engine framework).

You can also delete all running modules:
<pre>
import sys
sys.modules.clear()
</pre>

More details in https://spectrum.chat/lca2021-swagbadge/software/safe-software-updates~ba541e3c-d8a2-41a8-ac47-71d87696de2d

== Reboot to shell / Force runaway code to stop ==

It's possible to write code that will leave your badge unresponsive. Rebooting just reruns the same bad code. What to do?

* Place a finger on each of the bottom slider pads, either side of the microprocessor.
* Trigger a restart by using the button on the back of the badge, or Ctrl-D in repl (if you can get into repl)

The badge will restart but not autorun any code, just drop you back at the repl prompt. From there you can <code>put</code> bugfixed code back onto the device.

See https://github.com/geekscape/aiko_engine_mp/blob/a5b5593d37509df64a3dcb4cdc3d13a411152d82/main.py#L20

Swagbadge2021 GettingStarted

2021-01-16T06:15:54Z

Marcmerlin: /* Hardware pinout */

= 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. ==
* 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.
* 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 ==

'''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.

=== Getting the device on your wifi - wireless ===

* 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 2.4GHz network: it is not compatible with 5GHz WiFi.''
* 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.

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 setting up via the wifi AP (access point) doesn't work, you can put a configuration file onto the badge.
* 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 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: <code>mpfshell -o COM3</code>
* <code>put configuration/net.py configuration/net.py</code>
* 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.

On bootup you should now see...

= 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 [[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-schematic.pdf
<pre>
- GPIO0 : left breakout pin4
- GPIO2 : left breakout pin3

- 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
- GPIO14/27: slider #2
- GPIO16: left switch (under screen #1)
- GPIO17: right switch (under screen #2)

- GPIO18: SAO3 pin3 + LB pin7
- GPIO23: SAO3 pin4

- GPIO19: SAO1 pin4
- GPIO22: SAO1 pin3

- GPIO25: SAO4 pin4 + RB pin3
- GPIO26: SAO4 pin3 + RB pin4

- GPIO32: SAO2 pin3 + RB pin4
- GPIO33: SAO2 pin4 + RB pin3

- GPIO34: right breakout pin3
- GPIO35: right breakout pin3
</pre>

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

* [[Swagbadge2021_UpdatingSoftware|Updating the Software]]
* [[Swagbadge2021_SoftwareDev|Writing your own badge programs]]

Swagbadge2021 GettingStarted

2021-01-16T02:14:23Z

Marcmerlin: /* Running example code */

Swagbadge2021 MQTT

2021-01-15T20:26:26Z

Marcmerlin: /* Making your badge perform */

= Controlling your badge over MQTT =

== About the LCA Swagbadge MQTT server ==

The badges have MQTT configured to talk to a dedicated server hosted by Andy Gelme, one of the OHMC organisers. We have done this for security and privacy reasons, and because it gives us an Australian server so it's faster.

This server is at <code>101.181.46.180</code>, the configuration for which is held on the badge at [https://github.com/geekscape/aiko_engine_mp/blob/master/configuration/mqtt.py configuration/mqtt.py]. The server has some special features:
* The ''upgrade/'' topic path prefix is public read: only Jon and Andy can update it.
* The ''aiko/'' topic path prefix is public read/write
* We have some server monitoring to look for things snooping for all the channels, or who aren't using aiko/on a badge, and mitigations in the event a badge goes beserk and starts a spamming DOS attack.

You are welcome to change which MQTT server your badge uses, by updating the mqtt.py configuration file. Some publicly hosted alternatives are provided (commented out) in the config.

== Making your badge perform ==

The easiest thing to do is send messages to show up on your screens.

# Install an mqtt client on your machine
# Connect to the mqtt server (if you forget what it is, the IP address is shown on bootup)
# Using your badge's topic (public/esp32_your_badge_id/0/in) send it a message

Messages are usually in the form of <code>(component:command arguments)</code>.

<code>
mosquitto_sub -h 101.181.46.180 -t public/esp32_id/0 & << does this receive anything?

mosquitto_pub -h 101.181.46.180 -t public/esp32_id/0/in -m "(oled:clear)"

mosquitto_pub -h 101.181.46.180 -t public/esp32_id/0/in -m "(oled:pixel 64 32)"

mosquitto_pub -h 101.181.46.180 -t public/esp32_id/0/in -m "(oled:text 0 50 Hello World)"
</code>

=== OLED messages ===
;(oled:clear)
: clears both screens
;(oled:log Hello World!)
: writes a message along the bottom of the screens, scrolling up whatever is there out of the way
; (oled:pixel x y)
: lights a pixel at that spot
; (oled:text x y This is a test !)
: Puts some text at the position x,y. It will be displayed over the top of whatever's there.

If you'd like to make your application MQTT aware, take a look at the [https://github.com/geekscape/aiko_engine_mp/blob/master/lib/aiko/oled.py oled code].

SwagBadge2021

2021-01-15T06:08:07Z

Marcmerlin: /* Getting started */

= Swagbadge for [https://lca2021.linux.org.au LCA2021]: Welcome! =

== Status, About us, Contact us ==
* [https://spectrum.chat/lca2021-swagbadge Swagbadge/Dagbadge spectrum forums]: talk to the team, get help!
* '''[[SwagBadge2021 Status, blog and timeline]]: Read for regular project updates and history'''
* [https://twitter.com/swagbadge2021 Twitter @swagbadge]: Follow for project notifications. HashTags: ''#swagbadge, #lca2021''
* [https://diyodemag.com/columns/swagbadge_dagbadge_badge_ohmc_linux_conference DIYODE magazine issue 41, December 2020 article] on the Swagbadge

== Getting started ==
* [https://spectrum.chat/lca2021-swagbadge SwagBadge Spectrum chat]: Chat system where the SwagBadge team hang out to help you with your badge
* [[Swagbadge2021_Newcomers|Newcomers guide]]: Read our guide if you haven't done much hardware before and need more fundamentals before diving in
* [[Swagbadge2021_GettingStarted|Getting started guide: Swagbadge]]: Your Swagbadge has arrived. What next?
* [[Swagbadge2021_SoftwareDev|SoftwareDev]]: Badge Software Development
* [[Swagbadge2021_MQTT|MQTT]]: Talking via MQTT
* [[Swagbadge2021_SoftwareDev|SoftwareDev]]: Badge Software Development
* [[SwagBadge2021 FAQ]]: Frequently Asked Questions

== Resources ==
* [https://github.com/CCHS-Melbourne/Swag-Badge GitHub repository: #swagbadge hardware]
* [https://github.com/geekscape/aiko_engine_mp GitHub repository: Aiko Engine for microPython]: Not yet updated for #swagbadge

== Announcements ==

'''Today (2020-10-04), we are publicly announcing the [https://lca2021.linux.org.au LCA2021] #swagbadge project''' and beginning the process of opening up our hardware and software development processes. The next couple of weeks will be a bit of a spectator sport whilst we put in place mechanisms for technical collaboration and contributions. We warmly welcome you to join in, get an early start on LCA2021 and enjoy the ride ! '''We'll be listening for questions and feedback sent to [https://twitter.com/swagbadge2021 Twitter @swagbadge]'''

Note: Whilst this project is supported by [https://lca2021.linux.org.au LCA2021], the OHMC team are not an official part of the LCA2021 organizing committee. Of course, we'll be in close communication with them. Also, this project will be covered by a [https://lca2021.linux.org.au/attend/code-of-conduct Code Of Conduct] (perhaps with some hardware hacking caveats). The OHMC team supports and encourages inclusion and diversity in hardware / software hacking, please help us do better !

[[File:Swag badge render 2020-09-30.jpg|360px|LCA2021 swag badge 3D render 2020-09-30]] Recent 3D render 2020-09-30

----

=== LCA2021 #swagbadge announcement ===

A limited number of '''LCA2021 Swag Badge''' electronic badges will be produced for the [https://lca2021.linux.org.au on-line LCA2021] conference, which will be distributed to conference attendees. The LCA2021 Swag Badge is being specially developed and tailored for the conference.

* ''Note 0: This is just our current understanding of how the LCA2021 #swagbadge will be made available ... and is subject to change by LCA2021 organizing committee''
* ''Note 1: The #swagbadge will be only available to Australian participants, due to the cost and delay of shipping internationally''
* ''Note 2: If you are outside of Australia or miss out on a #swagbadge, then you might want to seriously consider acquiring a [[Swagbadge2021_Dagbadge|Dagbadge]]''
* ''Note 3: The Open Hardware Miniconf is ON! [https://linux.conf.au/programme/miniconfs/open-hardware/ Submit your talk proposals today]. Deadline is Dec 18th.''

No ordinary conference badge, this one is full of extensible, open hardware, ready to be loaded up with whatever software and custom hardware add-ons takes your fancy !

The Open Hardware Mini-Conference (OHMC) team are putting together a badge that will be:

* Approachable for newcomers, e.g runs Python and doesn't require any special IDE (for embedded device development)
* Custom-designed, super slick PCB
* Powered by an ESP32 which gives you Wi-Fi and Bluetooth connectivity
* Not one, but two delightful OLED screens
* ... which double as pressable buttons
* Ready for development with the latest [http://micropython.org microPython] installed
* Supported by an open-sourced embedded network framework, the [https://github.com/geekscape/aiko_engine_mp Aiko Engine for microPython]
* With a number of [[Swagbadge2021_SAO|SAO connectors]] so you can extend and add on your own hardware components

We aim to post the #swagbadges prior to Christmas so they will be available before [https://lca2021.linux.org.au on-line LCA2021] begins.

But wait, there's more ! In the spirit of LCA, we want the capabilities of the badge to be truly open. We'll be following up with more information about how you can join in to build out ideas for doing wonderful, magnificent, incredible... stuff ... '''<your idea here>''' ... using the [[Swagbadge2021_SAO|SAO connectors]].

Follow along and join in with the OHMC team as we prepare, plan, design and build your badges. We'll be posting regular updates here on this Wiki.

[[File:Swag badge mechanical 2020-09-30.jpg|360px|LCA2021 swag badge mechanical layout 2020-09-30]] Mechanical layout 2020-09-30

[[Swagbadge2021 Backstory]]

Swagbadge2021 GettingStarted

2021-01-15T05:27:31Z

Marcmerlin:

SwagBadge2021 FAQ

2021-01-15T00:59:43Z

Marcmerlin: /* #swagbadge for LCA2021: Frequently Asked Questions */

=== #swagbadge for [https://lca2021.linux.org.au LCA2021]: Frequently Asked Questions ===

'''* Q: I'm outside of Australia, how can I acquire #swagbadge hardware?'''

A: Right now, even the OHMC team doesn't have a #swagbadge, because the project development is still in progress. However, we've deliberately chosen readily available parts, i.e ESP32 Lolin32, 0.96" OLED screens and buttons, so that it is inexpensive and easy for anyone to acquire parts for participating in the development process along with us. This also means that for those people we can't ship to, due to cost and time constraints, there is still an option for you to not miss out. We will be providing a [https://en.wikipedia.org/wiki/Bill_of_materials BoM] soon that includes links for on-line purchasing of the parts. This D.I.Y option is known as the #dagbadge !

'''* Q: What powers the badge? Can I run it off a battery?'''

You can plug a micro USB cable into the badge to provide power. We haven't provided one in the kits on the basis that everyone probably has plenty lying around at home already, and if not, they're easy and cheap to get hold of.

It is possible to power the badge using a battery: the LOLIN32 has a JST header where a small 1S LiPo can be plugged in, but you'll need to provide the battery (and connect it to the badge) yourself. (Places like [https://hobbyking.com/en_us Hobby King] sell them, but the shipping isn't cheap.)

'''* Q: Who is the team behind the Swagbadge?'''

The core team this year for OHMC is:
* [https://twitter.com/jonoxer Jon Oxer]
* [https://twitter.com/geekscape Andy Gelme]
* Andrew Nielsen
* [https://twitter.com/mage0r John Spencer]
* [https://twitter.com/nye_nicola Nicola Nye]
with help in all sorts of ways from many other individuals.

'''* Q: I need more help!'''

Head over to https://spectrum.chat/lca2021-swagbadge .
All sorts of helpful and knowledgeable folk hang out there.

OHMC2019 Software instructions

2019-01-24T04:14:16Z

Marcmerlin: /* Neopixels */

== Overview ==

From a software perspective, the DonkeyCar (Raspberry Pi) is self-contained ... driving, data acquisition (for training) and ultimately self-driving are all performed with on-board software. The provided micro-SD card already has all the required software pre-installed, as well as two pre-training A.I / Machine Learning models. The DonkeyCar software includes a web-server that provides a web interface that works on both desktop and mobile web browsers (great for driving).

Your laptop will be required to perform training of the Neural Network ... using the data acquired on the DonkeyCar. This means that Python software will need to be installed, e.g TensorFlow (Machine Learning framework).

== Software installation: Laptop / Desktop ==

[http://docs.donkeycar.com/guide/install_software Extensive DonkeyCar documentation]

* apt-get install -y virtualenv # Note: You may be using a different software installer
* mkvirtualenv donkeycar -p python3
* pip install tensorflow==1.8.0 # Note: Probably requires Python 3.5 or 3.6. People are having problems with Python 3.7
(if you get errors, you can try (re-) installing pip: python -m pip install --upgrade pip )

On debian, if virtualenv isn't there, try this instead
* virtualenv donkeycar -p python3
* cd donkeycar
* export PATH=`pwd`/bin:$PATH
* pip install tensorflow==1.8.0

Then proceed:

* git clone https://github.com/autorope/donkeycar
* pip install -e ./donkeycar

Note: You can manually install Python 3.6 as follows, but then you can't use mkvirtualenv ...

* yum install python36
* python3.6 -m venv ~/virtualenvs/donkeycar
* source ~/virtualenvs/donkeycar/bin/activate

== Software installation: Raspberry Pi ==

'''Your DonkeyCar (Raspberry Pi) is already pre-installed. This section is for reference only.
'''

[http://docs.donkeycar.com/guide/install_software/#get-the-raspberry-pi-working Extensive DonkeyCar documentation]

* sysctl -w net.ipv6.conf.all.disable_ipv6=1 # Reconnect via ssh afterwards
* sysctl -w net.ipv6.conf.default.disable_ipv6=1

* apt-get update
* apt-get upgrade
* apt-get install -y vim git mosquitto-clients
* apt-get install -y virtualenv build-essential python3-dev gfortran libhdf5-dev libatlas-base-dev libopenjp2-7-dev libtiff5

* apt-get install -y i2c-tools
* i2cdetect -y 1
0 1 2 3 4 5 6 7 8 9 a b c d e f
00: -- -- -- -- -- -- -- -- -- -- -- -- --
10: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
20: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
30: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
40: 40 -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
50: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
60: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
70: 70 -- -- -- -- -- -- --

* mv env env.donkeycar
* virtualenv env -p python3
* pip install tensorflow==1.8.0
* pip install adafruit-pca9685
* pip install picamera

== Finding your car on the network ==

Your DonkeyCar (Raspberry Pi) has been pre-configured to connect to the LCA2019 network. But, which IP address ?

Every car has a unique hostname, from ''ohmc_01'' to ''ohmc_32''. The micro-SD card adapter is labeled with your car name.

However, that still isn't enough to find your car.

So, there is a ''cron'' job that every minute sends an MQTT message to ''test.mosquitto.org'' with your car's name, IP address and a timestamp.

Install an MQTT client, as follows ...

* apt-get install mosquitto-clients

Use the following command to read the MQTT messages ...

* mosquitto_sub -h test.mosquitto.org -t 'ohmc/#' -v

ohmc/ohmc_01 10.193.2.69 Mon 11 Jun 07:08:01 UTC 2018

== Driving the car manually ==

'''Caution: Put your car "on blocks" (wheels off the ground) the first time you try driving it'''

[http://docs.donkeycar.com/guide/get_driving Extensive DonkeyCar documentation]

IP_ADDRESS=xxx.xxx.xxx.xxx # Found as above

* ssh pi@$IP_ADDRESS # Note: Raspberry Pi default username: ''pi'' and password: ''raspberry''
* cd ohmc_car
* python manage.py drive

loading config file: /home/pi/play/roba_car/config.py
config loaded
PiCamera loaded.. .warming camera
Starting Donkey Server...
You can now go to http://xxx.xxx.xxx.xxx:8887 to drive your car.

With a desktop web browser, the user interface provides a virtual joystick (right-hand frame) that you can use to drive the car ... altering the steering and throttle values.

The mobile web browser, the user interface allows you to drive by tilting the phone left-right for steering and forwards-backwards for throttle. For safety, you must press the [Start Vehicle] / [Stop Vehicle] toggle button to enable control.

== rPi reboots and Auto-starting donkeycar without logging in ==

If your rPi reboots when you're driving, check the following things:
# did you swap the servo wires between steering and power. Turn the ESC off, unplug one servo wire, turn the ESC back on (little toggle switch), and test steering. Make sure that steering does not activate the wheel motors.
# is your battery low? are you accelerating too quickly?
Because the battery has a high internal resistance, if you demand a lot of power too quickly, the voltage on the battery drops enough that the rPi gets below its critical voltage (when you add the voltage drop from the voltage converter), and the rPi reboots.

To restart donkey server automatically, do the following:
* Add this to /etc/rc.local:
su - pi -c 'cd ~/ohmc_car; python manage.py drive &>/tmp/out' &
* move 'source ~/env/bin/activate' from ~/.bashrc to ~/.profile

== Steering and throttle calibration ==

To save time at the workshop, you won't need to calibrate your car's steering and/or throttle.

However, you may get better results and can perform calibration when you have time ... [http://docs.donkeycar.com/guide/calibrate by following the DonkeyCar instructions]

== Data acquisition for the Neural Network ==

Once you are driving your car confidently around a track ... it is time to acquire training data for the Neural Network. DonkeyCar operates at 10 frames per second, capturing a 160x120 image, along with steering angle and throttle value. This is all stored in the ''$HOME/ohmc_car/tub/'' directory.

Before training, it is a good idea to clean out previous data. Don't just remove all the files in the ''tub/'' directory ! The ''tub/meta.json'' file is important.

[http://docs.donkeycar.com/guide/train_autopilot Extensive DonkeyCar documentation]

Perform the same commands as for manual driving ...

* ssh pi@$IP_ADDRESS
* cd ohmc_car
* python manage.py drive

Then via the web browser press the [Start Recording] button ... drive the car around a track ... then press the [Stop Recording] button.

It is recommended that you collect between 5K and 20K frames. At 10 frames per second, that is between 500 and 2,000 seconds of driving. Make sure that you drive clockwise and anti-clockwise.

You will need to type this command just once on your DonkeyCar (Raspberry Pi)to provide a directory on your laptop for your training data ...

* rsync -av pi@<car_ip>:ohmc_car .

When finished acquisition, then transfer the data from the DonkeyCar (Raspberry Pi) to your laptop / desktop for training the Neural Network.

* rsync -av pi@<car_ip>:ohmc_car/tub ohmc_car/tub_$DATE

== Training the Neural Network ==

Once training data has been copied to your laptop / desktop, you can begin training the Neural Network.

[http://docs.donkeycar.com/guide/train_autopilot Extensive DonkeyCar documentation]

Run these commands on your laptop / desktop to train the Neural Network ...

* workon donkeycar # For those who have set-up a virtualenv
* cd ohmc_car
* python manage.py train --tub $HOME/ohmc_car/tub_$DATE --model ./models/model_$DATE.hdf5

using donkey version: 2.5.7 ...
loading config file: /Users/andyg/play/ai/roba_car/config.py
config loaded
tub_names ./tub_2019-01-15c
train: 5740, validation: 1436
steps_per_epoch 44
Epoch 1/100
2019-01-21 13:08:49.507048: I tensorflow/core/platform/cpu_feature_guard.cc:140] Your CPU supports instructions that this TensorFlow binary was not compiled to use: AVX2 FMA
43/44 [============================>.] - ETA: 0s - loss: 58.5130 - angle_out_loss: 30.3421 - throttle_out_loss: 86.6839
Epoch 00001: val_loss improved from inf to 0.19699, saving model to ./models/roba0_2019-01-16c.hdf5
44/44 [==============================] - 38s 874ms/step - loss: 57.1887 - angle_out_loss: 29.6601 - throttle_out_loss: 84.7172 - val_loss: 0.1970 - val_angle_out_loss: 0.3230 - val_throttle_out_loss: 0.0710

On a modern laptop, each epoch will take around 30 seconds to complete. For up-to 100 epochs. Typically, you can expect around 20 to 40 epochs before the Neural Network stop learning. That is around 10 to 20 minutes of training time.

The training command creates the Neural Network weights that represent what your DonkeyCar has "learned".

When training has completed, copy the trained model back to your DonkeyCar (Raspberry Pi)

* scp $USERNAME@$HOSTNAME:ohmc_car/models/model_$DATE.hdf5 models

== Self-driving ... the ultimate goal ==

Once your trained model has been copied back onto the DonkeyCar (Raspberry Pi), your car can be self-driven as follow ...

* python manage.py drive --model ~/ohmc_car/models/models/model_$DATE.hdf5

This works similar to the manual driving mode with the addition of a trained model that can either ...

1) User: Manual control of both steering and throttle

2) Local Angle: Automatically control the steering angle

3) Local pilot: Automatically control both the steering angle and throttle amount

The web browser provides a drop-down menu to select between these options.

It is recommended to just start with Local Angle ... and control the throttle manually with the "i" key (faster) and "k" key (slower).

== Neopixels ==

On the car, do this: pip install rpi_ws281x adafruit-circuitpython-neopixel --trusted-host pypi.org --trusted-host files.pythonhosted.org --trusted-host www.piwheels.org

The details come from here: https://learn.adafruit.com/neopixels-on-raspberry-pi/overview

<pre>
(env) pi@ohmc_24:~/ohmc_car$ diff -u manage.py.orig manage.py
--- manage.py.orig 2018-06-11 08:14:34.079999106 +0000
+++ manage.py 2018-06-11 08:37:05.959999560 +0000
@@ -122,6 +122,9 @@
tub = TubWriter(path=cfg.TUB_PATH, inputs=inputs, types=types)
V.add(tub, inputs=inputs, run_condition='recording')

+ pixels[0] = (32, 64, 128)
+ pixels[1] = (0, 255, 0)
+
# run the vehicle
V.start(rate_hz=cfg.DRIVE_LOOP_HZ,
max_loop_count=cfg.MAX_LOOPS)
@@ -169,6 +172,13 @@
cfg = dk.load_config()

if args['drive']:
+ # Neopixels
+ # https://learn.adafruit.com/neopixels-on-raspberry-pi/python-usage
+ import board
+ import neopixel
+ pixels = neopixel.NeoPixel(board.D18, 2)
+ pixels[0] = (0, 0, 0)
+ pixels[1] = (0, 64, 0)
drive(cfg, model_path=args['--model'], use_chaos=args['--chaos'])
</pre>

Then, you need to run as root for neopixels to work:
<pre>
sudo /home/pi/env/bin/python manage.py drive
--model=/home/pi/ohmc_car/models/large_track.hdf5
</pre>

== Neopixels v2 ==

* Get https://gist.github.com/marcmerlin/a3bba2231a3371266e595aa0e6028b77
* Save under /home/pi/ and /etc/rc.local
* Apply manage.py.diff to /home/pi/ohmc_car/manage.py
* Reboot and both the led server and the car software should start
* You can force an led pattern or color like so
<pre>
(env) pi@ohmc_24:~/ohmc_car$ echo -n rainbow > /tmp/leds
(env) pi@ohmc_24:~/ohmc_car$ echo -n b > /tmp/leds
(env) pi@ohmc_24:~/ohmc_car$ echo -n cylon > /tmp/leds
</pre>
* Reboot and both the led server

OHMC2019 Software instructions

2019-01-21T09:06:26Z

Marcmerlin: Added neopixel info

== Overview ==

From a software perspective, the DonkeyCar (Raspberry Pi) is self-contained ... driving, data acquisition (for training) and ultimately self-driving are all performed with on-board software. The provided micro-SD card already has all the required software pre-installed, as well as two pre-training A.I / Machine Learning models. The DonkeyCar software includes a web-server that provides a web interface that works on both desktop and mobile web browsers (great for driving).

Your laptop will be required to perform training of the Neural Network ... using the data acquired on the DonkeyCar. This means that Python software will need to be installed, e.g TensorFlow (Machine Learning framework).

== Software installation: Laptop / Desktop ==

[http://docs.donkeycar.com/guide/install_software Extensive DonkeyCar documentation]

* apt-get install -y virtualenv # Note: You may be using a different software installer
* mkvirtualenv donkeycar -p python3
* pip install tensorflow==1.8.0 # Note: Probably requires Python 3.5 or 3.6. People are having problems with Python 3.7
(if you get errors, you can try (re-) installing pip: python -m pip install --upgrade pip )

On debian, if virtualenv isn't there, try this instead
* virtualenv donkeycar -p python3
* cd donkeycar
* export PATH=`pwd`/bin:$PATH
* pip install tensorflow==1.8.0

Then proceed:

* git clone https://github.com/autorope/donkeycar
* pip install -e ./donkeycar

Note: You can manually install Python 3.6 as follows, but then you can't use mkvirtualenv ...

* yum install python36
* python3.6 -m venv ~/virtualenvs/donkeycar
* source ~/virtualenvs/donkeycar/bin/activate

== Software installation: Raspberry Pi ==

'''Your DonkeyCar (Raspberry Pi) is already pre-installed. This section is for reference only.
'''

[http://docs.donkeycar.com/guide/install_software/#get-the-raspberry-pi-working Extensive DonkeyCar documentation]

* sysctl -w net.ipv6.conf.all.disable_ipv6=1 # Reconnect via ssh afterwards
* sysctl -w net.ipv6.conf.default.disable_ipv6=1

* apt-get update
* apt-get upgrade
* apt-get install -y vim git mosquitto-clients
* apt-get install -y virtualenv build-essential python3-dev gfortran libhdf5-dev libatlas-base-dev libopenjp2-7-dev libtiff5

* apt-get install -y i2c-tools
* i2cdetect -y 1
0 1 2 3 4 5 6 7 8 9 a b c d e f
00: -- -- -- -- -- -- -- -- -- -- -- -- --
10: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
20: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
30: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
40: 40 -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
50: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
60: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
70: 70 -- -- -- -- -- -- --

* mv env env.donkeycar
* virtualenv env -p python3
* pip install tensorflow==1.8.0
* pip install adafruit-pca9685
* pip install picamera

== Finding your car on the network ==

Your DonkeyCar (Raspberry Pi) has been pre-configured to connect to the LCA2019 network. But, which IP address ?

Every car has a unique hostname, from ''ohmc_01'' to ''ohmc_32''. The micro-SD card adapter is labeled with your car name.

However, that still isn't enough to find your car.

So, there is a ''cron'' job that every minute sends an MQTT message to ''test.mosquitto.org'' with your car's name, IP address and a timestamp.

Install an MQTT client, as follows ...

* apt-get install mosquitto-clients

Use the following command to read the MQTT messages ...

* mosquitto_sub -h test.mosquitto.org -t 'ohmc/#' -v

ohmc/ohmc_01 10.193.2.69 Mon 11 Jun 07:08:01 UTC 2018

== Driving the car manually ==

'''Caution: Put your car "on blocks" (wheels off the ground) the first time you try driving it'''

[http://docs.donkeycar.com/guide/get_driving Extensive DonkeyCar documentation]

IP_ADDRESS=xxx.xxx.xxx.xxx # Found as above

* ssh pi@$IP_ADDRESS # Note: Raspberry Pi default username: ''pi'' and password: ''raspberry''
* cd ohmc_car
* python manage.py drive

loading config file: /home/pi/play/roba_car/config.py
config loaded
PiCamera loaded.. .warming camera
Starting Donkey Server...
You can now go to http://xxx.xxx.xxx.xxx:8887 to drive your car.

With a desktop web browser, the user interface provides a virtual joystick (right-hand frame) that you can use to drive the car ... altering the steering and throttle values.

The mobile web browser, the user interface allows you to drive by tilting the phone left-right for steering and forwards-backwards for throttle. For safety, you must press the [Start Vehicle] / [Stop Vehicle] toggle button to enable control.

== rPi reboots and Auto-starting donkeycar without logging in ==

If your rPi reboots when you're driving, check the following things:
# did you swap the servo wires between steering and power. Turn the ESC off, unplug one servo wire, turn the ESC back on (little toggle switch), and test steering. Make sure that steering does not activate the wheel motors.
# is your battery low? are you accelerating too quickly?
Because the battery has a high internal resistance, if you demand a lot of power too quickly, the voltage on the battery drops enough that the rPi gets below its critical voltage (when you add the voltage drop from the voltage converter), and the rPi reboots.

To restart donkey server automatically, do the following:
* Add this to /etc/rc.local:
su - pi -c 'cd ~/ohmc_car; python manage.py drive &>/tmp/out' &
* move 'source ~/env/bin/activate' from ~/.bashrc to ~/.profile

== Steering and throttle calibration ==

To save time at the workshop, you won't need to calibrate your car's steering and/or throttle.

However, you may get better results and can perform calibration when you have time ... [http://docs.donkeycar.com/guide/calibrate by following the DonkeyCar instructions]

== Data acquisition for the Neural Network ==

Once you are driving your car confidently around a track ... it is time to acquire training data for the Neural Network. DonkeyCar operates at 10 frames per second, capturing a 160x120 image, along with steering angle and throttle value. This is all stored in the ''$HOME/ohmc_car/tub/'' directory.

Before training, it is a good idea to clean out previous data. Don't just remove all the files in the ''tub/'' directory ! The ''tub/meta.json'' file is important.

[http://docs.donkeycar.com/guide/train_autopilot Extensive DonkeyCar documentation]

Perform the same commands as for manual driving ...

* ssh pi@$IP_ADDRESS
* cd ohmc_car
* python manage.py drive

Then via the web browser press the [Start Recording] button ... drive the car around a track ... then press the [Stop Recording] button.

It is recommended that you collect between 5K and 20K frames. At 10 frames per second, that is between 500 and 2,000 seconds of driving. Make sure that you drive clockwise and anti-clockwise.

You will need to type this command just once on your DonkeyCar (Raspberry Pi)to provide a directory on your laptop for your training data ...

* rsync -av pi@<car_ip>:ohmc_car .

When finished acquisition, then transfer the data from the DonkeyCar (Raspberry Pi) to your laptop / desktop for training the Neural Network.

* rsync -av pi@<car_ip>:ohmc_car/tub ohmc_car/tub_$DATE

== Training the Neural Network ==

Once training data has been copied to your laptop / desktop, you can begin training the Neural Network.

[http://docs.donkeycar.com/guide/train_autopilot Extensive DonkeyCar documentation]

Run these commands on your laptop / desktop to train the Neural Network ...

* workon donkeycar # For those who have set-up a virtualenv
* cd ohmc_car
* python manage.py train --tub $HOME/ohmc_car/tub_$DATE --model ./models/model_$DATE.hdf5

using donkey version: 2.5.7 ...
loading config file: /Users/andyg/play/ai/roba_car/config.py
config loaded
tub_names ./tub_2019-01-15c
train: 5740, validation: 1436
steps_per_epoch 44
Epoch 1/100
2019-01-21 13:08:49.507048: I tensorflow/core/platform/cpu_feature_guard.cc:140] Your CPU supports instructions that this TensorFlow binary was not compiled to use: AVX2 FMA
43/44 [============================>.] - ETA: 0s - loss: 58.5130 - angle_out_loss: 30.3421 - throttle_out_loss: 86.6839
Epoch 00001: val_loss improved from inf to 0.19699, saving model to ./models/roba0_2019-01-16c.hdf5
44/44 [==============================] - 38s 874ms/step - loss: 57.1887 - angle_out_loss: 29.6601 - throttle_out_loss: 84.7172 - val_loss: 0.1970 - val_angle_out_loss: 0.3230 - val_throttle_out_loss: 0.0710

On a modern laptop, each epoch will take around 30 seconds to complete. For up-to 100 epochs. Typically, you can expect around 20 to 40 epochs before the Neural Network stop learning. That is around 10 to 20 minutes of training time.

The training command creates the Neural Network weights that represent what your DonkeyCar has "learned".

When training has completed, copy the trained model back to your DonkeyCar (Raspberry Pi)

* scp $USERNAME@$HOSTNAME:ohmc_car/models/model_$DATE.hdf5 models

== Self-driving ... the ultimate goal ==

Once your trained model has been copied back onto the DonkeyCar (Raspberry Pi), your car can be self-driven as follow ...

* python manage.py drive --model ~/ohmc_car/models/models/model_$DATE.hdf5

This works similar to the manual driving mode with the addition of a trained model that can either ...

1) User: Manual control of both steering and throttle

2) Local Angle: Automatically control the steering angle

3) Local pilot: Automatically control both the steering angle and throttle amount

The web browser provides a drop-down menu to select between these options.

It is recommended to just start with Local Angle ... and control the throttle manually with the "i" key (faster) and "k" key (slower).

== Neopixels ==

On the car, do this: pip install rpi_ws281x adafruit-circuitpython-neopixel --trusted-host pypi.org --trusted-host files.pythonhosted.org --trusted-host www.piwheels.org

The details come from here: https://learn.adafruit.com/neopixels-on-raspberry-pi/overview

<pre>
(env) pi@ohmc_24:~/ohmc_car$ diff -u manage.py.orig manage.py
--- manage.py.orig 2018-06-11 08:14:34.079999106 +0000
+++ manage.py 2018-06-11 08:37:05.959999560 +0000
@@ -122,6 +122,9 @@
tub = TubWriter(path=cfg.TUB_PATH, inputs=inputs, types=types)
V.add(tub, inputs=inputs, run_condition='recording')

+ pixels[0] = (32, 64, 128)
+ pixels[1] = (0, 255, 0)
+
# run the vehicle
V.start(rate_hz=cfg.DRIVE_LOOP_HZ,
max_loop_count=cfg.MAX_LOOPS)
@@ -169,6 +172,13 @@
cfg = dk.load_config()

if args['drive']:
+ # Neopixels
+ # https://learn.adafruit.com/neopixels-on-raspberry-pi/python-usage
+ import board
+ import neopixel
+ pixels = neopixel.NeoPixel(board.D18, 2)
+ pixels[0] = (0, 0, 0)
+ pixels[1] = (0, 64, 0)
drive(cfg, model_path=args['--model'], use_chaos=args['--chaos'])
</pre>

Then, you need to run as root for neopixels to work:
<pre>
sudo /home/pi/env/bin/python manage.py drive --model=/home/pi/ohmc_car/models/large_track.hdf5
</pre>

OHMC2019 Software instructions

2019-01-21T08:50:39Z

Marcmerlin: improve security of data retrieval from car

OHMC2019 Software instructions

2019-01-21T07:30:25Z

Marcmerlin: work around mkvirtualenv not being there

== Overview ==

From a software perspective, the DonkeyCar (Raspberry Pi) is self-contained ... driving, data acquisition (for training) and ultimately self-driving are all performed with on-board software. The provided micro-SD card already has all the required software pre-installed, as well as two pre-training A.I / Machine Learning models. The DonkeyCar software includes a web-server that provides a web interface that works on both desktop and mobile web browsers (great for driving).

Your laptop will be required to perform training of the Neural Network ... using the data acquired on the DonkeyCar. This means that Python software will need to be installed, e.g TensorFlow (Machine Learning framework).

== Software installation: Laptop / Desktop ==

[http://docs.donkeycar.com/guide/install_software Extensive DonkeyCar documentation]

* apt-get install -y virtualenv # Note: You may be using a different software installer
* mkvirtualenv donkeycar -p python3
* pip install tensorflow==1.8.0 # Note: Probably requires Python 3.5 or 3.6. People are having problems with Python 3.7
(if you get errors, you can try (re-) installing pip: python -m pip install --upgrade pip )

On debian, if virtualenv isn't there, try this instead
* virtualenv donkeycar -p python3
* cd donkeycar
* export PATH=`pwd`/bin:$PATH
* pip install tensorflow==1.8.0

Then proceed:

* git clone https://github.com/autorope/donkeycar
* pip install -e ./donkeycar

Note: You can manually install Python 3.6 as follows, but then you can't use mkvirtualenv ...

* yum install python36
* python3.6 -m venv ~/virtualenvs/donkeycar
* source ~/virtualenvs/donkeycar/bin/activate

== Software installation: Raspberry Pi ==

'''Your DonkeyCar (Raspberry Pi) is already pre-installed. This section is for reference only.
'''

[http://docs.donkeycar.com/guide/install_software/#get-the-raspberry-pi-working Extensive DonkeyCar documentation]

* sysctl -w net.ipv6.conf.all.disable_ipv6=1 # Reconnect via ssh afterwards
* sysctl -w net.ipv6.conf.default.disable_ipv6=1

* apt-get update
* apt-get upgrade
* apt-get install -y vim git mosquitto-clients
* apt-get install -y virtualenv build-essential python3-dev gfortran libhdf5-dev libatlas-base-dev libopenjp2-7-dev libtiff5

* apt-get install -y i2c-tools
* i2cdetect -y 1
0 1 2 3 4 5 6 7 8 9 a b c d e f
00: -- -- -- -- -- -- -- -- -- -- -- -- --
10: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
20: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
30: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
40: 40 -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
50: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
60: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
70: 70 -- -- -- -- -- -- --

* mv env env.donkeycar
* virtualenv env -p python3
* pip install tensorflow==1.8.0
* pip install adafruit-pca9685
* pip install picamera

== Finding your car on the network ==

Your DonkeyCar (Raspberry Pi) has been pre-configured to connect to the LCA2019 network. But, which IP address ?

Every car has a unique hostname, from ''ohmc_01'' to ''ohmc_32''. The micro-SD card adapter is labeled with your car name.

However, that still isn't enough to find your car.

So, there is a ''cron'' job that every minute sends an MQTT message to ''test.mosquitto.org'' with your car's name, IP address and a timestamp.

Install an MQTT client, as follows ...

* apt-get install mosquitto-clients

Use the following command to read the MQTT messages ...

* mosquitto_sub -h test.mosquitto.org -t 'ohmc/#' -v

ohmc/ohmc_01 10.193.2.69 Mon 11 Jun 07:08:01 UTC 2018

== Driving the car manually ==

'''Caution: Put your car "on blocks" (wheels off the ground) the first time you try driving it'''

[http://docs.donkeycar.com/guide/get_driving Extensive DonkeyCar documentation]

IP_ADDRESS=xxx.xxx.xxx.xxx # Found as above

* ssh pi@$IP_ADDRESS # Note: Raspberry Pi default username: ''pi'' and password: ''raspberry''
* cd ohmc_car
* python manage.py drive

loading config file: /home/pi/play/roba_car/config.py
config loaded
PiCamera loaded.. .warming camera
Starting Donkey Server...
You can now go to http://xxx.xxx.xxx.xxx:8887 to drive your car.

With a desktop web browser, the user interface provides a virtual joystick (right-hand frame) that you can use to drive the car ... altering the steering and throttle values.

The mobile web browser, the user interface allows you to drive by tilting the phone left-right for steering and forwards-backwards for throttle. For safety, you must press the [Start Vehicle] / [Stop Vehicle] toggle button to enable control.

== rPi reboots and Auto-starting donkeycar without logging in ==

If your rPi reboots when you're driving, check the following things:
# did you swap the servo wires between steering and power. Turn the ESC off, unplug one servo wire, turn the ESC back on (little toggle switch), and test steering. Make sure that steering does not activate the wheel motors.
# is your battery low? are you accelerating too quickly?
Because the battery has a high internal resistance, if you demand a lot of power too quickly, the voltage on the battery drops enough that the rPi gets below its critical voltage (when you add the voltage drop from the voltage converter), and the rPi reboots.

To restart donkey server automatically, do the following:
* Add this to /etc/rc.local:
su - pi -c 'cd ~/ohmc_car; python manage.py drive &>/tmp/out' &
* move 'source ~/env/bin/activate' from ~/.bashrc to ~/.profile

== Steering and throttle calibration ==

To save time at the workshop, you won't need to calibrate your car's steering and/or throttle.

However, you may get better results and can perform calibration when you have time ... [http://docs.donkeycar.com/guide/calibrate by following the DonkeyCar instructions]

== Data acquisition for the Neural Network ==

Once you are driving your car confidently around a track ... it is time to acquire training data for the Neural Network. DonkeyCar operates at 10 frames per second, capturing a 160x120 image, along with steering angle and throttle value. This is all stored in the ''$HOME/ohmc_car/tub/'' directory.

Before training, it is a good idea to clean out previous data. Don't just remove all the files in the ''tub/'' directory ! The ''tub/meta.json'' file is important.

[http://docs.donkeycar.com/guide/train_autopilot Extensive DonkeyCar documentation]

Perform the same commands as for manual driving ...

* ssh pi@$IP_ADDRESS
* cd ohmc_car
* python manage.py drive

Then via the web browser press the [Start Recording] button ... drive the car around a track ... then press the [Stop Recording] button.

It is recommended that you collect between 5K and 20K frames. At 10 frames per second, that is between 500 and 2,000 seconds of driving. Make sure that you drive clockwise and anti-clockwise.

You will need to type this command just once on your DonkeyCar (Raspberry Pi)to provide a directory on your laptop for your training data ...

* scp -pr ohmc_car $USERNAME@$HOSTNAME:

When finished acquisition, then transfer the data from the DonkeyCar (Raspberry Pi) to your laptop / desktop for training the Neural Network.

* scp -pr tub $USERNAME@$HOSTNAME:ohmc_car/tub_$DATE

== Training the Neural Network ==

Once training data has been copied to your laptop / desktop, you can begin training the Neural Network.

[http://docs.donkeycar.com/guide/train_autopilot Extensive DonkeyCar documentation]

Run these commands on your laptop / desktop to train the Neural Network ...

* workon donkeycar # For those who have set-up a virtualenv
* cd ohmc_car
* python manage.py train --tub $HOME/ohmc_car/tub_$DATE --model ./models/model_$DATE.hdf5

using donkey version: 2.5.7 ...
loading config file: /Users/andyg/play/ai/roba_car/config.py
config loaded
tub_names ./tub_2019-01-15c
train: 5740, validation: 1436
steps_per_epoch 44
Epoch 1/100
2019-01-21 13:08:49.507048: I tensorflow/core/platform/cpu_feature_guard.cc:140] Your CPU supports instructions that this TensorFlow binary was not compiled to use: AVX2 FMA
43/44 [============================>.] - ETA: 0s - loss: 58.5130 - angle_out_loss: 30.3421 - throttle_out_loss: 86.6839
Epoch 00001: val_loss improved from inf to 0.19699, saving model to ./models/roba0_2019-01-16c.hdf5
44/44 [==============================] - 38s 874ms/step - loss: 57.1887 - angle_out_loss: 29.6601 - throttle_out_loss: 84.7172 - val_loss: 0.1970 - val_angle_out_loss: 0.3230 - val_throttle_out_loss: 0.0710

On a modern laptop, each epoch will take around 30 seconds to complete. For up-to 100 epochs. Typically, you can expect around 20 to 40 epochs before the Neural Network stop learning. That is around 10 to 20 minutes of training time.

The training command creates the Neural Network weights that represent what your DonkeyCar has "learned".

When training has completed, copy the trained model back to your DonkeyCar (Raspberry Pi)

* scp $USERNAME@$HOSTNAME:ohmc_car/models/model_$DATE.hdf5 models

== Self-driving ... the ultimate goal ==

Once your trained model has been copied back onto the DonkeyCar (Raspberry Pi), your car can be self-driven as follow ...

* python manage.py drive --model ~/ohmc_car/models/models/model_$DATE.hdf5

This works similar to the manual driving mode with the addition of a trained model that can either ...

1) User: Manual control of both steering and throttle

2) Local Angle: Automatically control the steering angle

3) Local pilot: Automatically control both the steering angle and throttle amount

The web browser provides a drop-down menu to select between these options.

It is recommended to just start with Local Angle ... and control the throttle manually with the "i" key (faster) and "k" key (slower).

OHMC2019 Software instructions

2019-01-21T06:11:42Z

Marcmerlin: Added info on how to deal with rPi reboots

== Overview ==

From a software perspective, the DonkeyCar (Raspberry Pi) is self-contained ... driving, data acquisition (for training) and ultimately self-driving are all performed with on-board software. The provided micro-SD card already has all the required software pre-installed, as well as two pre-training A.I / Machine Learning models. The DonkeyCar software includes a web-server that provides a web interface that works on both desktop and mobile web browsers (great for driving).

Your laptop will be required to perform training of the Neural Network ... using the data acquired on the DonkeyCar. This means that Python software will need to be installed, e.g TensorFlow (Machine Learning framework).

== Software installation: Laptop / Desktop ==

[http://docs.donkeycar.com/guide/install_software Extensive DonkeyCar documentation]

* apt-get install -y virtualenv # Note: You may be using a different software installer
* mkvirtualenv donkeycar -p python3
* pip install tensorflow==1.8.0 # Note: Probably requires Python 3.5 or 3.6. People are having problems with Python 3.7
(if you get errors, you can try (re-) installing pip: python -m pip install --upgrade pip )

* cd $HOME
* git clone https://github.com/autorope/donkeycar
* pip install -e ./donkeycar

Note: You can manually install Python 3.6 as follows, but then you can't use mkvirtualenv ...

* yum install python36
* python3.6 -m venv ~/virtualenvs/donkeycar
* source ~/virtualenvs/donkeycar/bin/activate

== Software installation: Raspberry Pi ==

'''Your DonkeyCar (Raspberry Pi) is already pre-installed. This section is for reference only.
'''

[http://docs.donkeycar.com/guide/install_software/#get-the-raspberry-pi-working Extensive DonkeyCar documentation]

* sysctl -w net.ipv6.conf.all.disable_ipv6=1 # Reconnect via ssh afterwards
* sysctl -w net.ipv6.conf.default.disable_ipv6=1

* apt-get update
* apt-get upgrade
* apt-get install -y vim git mosquitto-clients
* apt-get install -y virtualenv build-essential python3-dev gfortran libhdf5-dev libatlas-base-dev libopenjp2-7-dev libtiff5

* apt-get install -y i2c-tools
* i2cdetect -y 1
0 1 2 3 4 5 6 7 8 9 a b c d e f
00: -- -- -- -- -- -- -- -- -- -- -- -- --
10: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
20: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
30: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
40: 40 -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
50: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
60: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
70: 70 -- -- -- -- -- -- --

* mv env env.donkeycar
* virtualenv env -p python3
* pip install tensorflow==1.8.0
* pip install adafruit-pca9685
* pip install picamera

== Finding your car on the network ==

Your DonkeyCar (Raspberry Pi) has been pre-configured to connect to the LCA2019 network. But, which IP address ?

Every car has a unique hostname, from ''ohmc_01'' to ''ohmc_32''. The micro-SD card adapter is labeled with your car name.

However, that still isn't enough to find your car.

So, there is a ''cron'' job that every minute sends an MQTT message to ''test.mosquitto.org'' with your car's name, IP address and a timestamp.

Install an MQTT client, as follows ...

* apt-get install mosquitto-clients

Use the following command to read the MQTT messages ...

* mosquitto_sub -h test.mosquitto.org -t 'ohmc/#' -v

ohmc/ohmc_01 10.193.2.69 Mon 11 Jun 07:08:01 UTC 2018

== Driving the car manually ==

'''Caution: Put your car "on blocks" (wheels off the ground) the first time you try driving it'''

[http://docs.donkeycar.com/guide/get_driving Extensive DonkeyCar documentation]

IP_ADDRESS=xxx.xxx.xxx.xxx # Found as above

* ssh pi@$IP_ADDRESS # Note: Raspberry Pi default username: ''pi'' and password: ''raspberry''
* cd ohmc_car
* python manage.py drive

loading config file: /home/pi/play/roba_car/config.py
config loaded
PiCamera loaded.. .warming camera
Starting Donkey Server...
You can now go to http://xxx.xxx.xxx.xxx:8887 to drive your car.

With a desktop web browser, the user interface provides a virtual joystick (right-hand frame) that you can use to drive the car ... altering the steering and throttle values.

The mobile web browser, the user interface allows you to drive by tilting the phone left-right for steering and forwards-backwards for throttle. For safety, you must press the [Start Vehicle] / [Stop Vehicle] toggle button to enable control.

== rPi reboots and Auto-starting donkeycar without logging in ==

If your rPi reboots when you're driving, check the following things:
# did you swap the servo wires between steering and power. Turn the ESC off, unplug one servo wire, turn the ESC back on (little toggle switch), and test steering. Make sure that steering does not activate the wheel motors.
# is your battery low? are you accelerating too quickly?
Because the battery has a high internal resistance, if you demand a lot of power too quickly, the voltage on the battery drops enough that the rPi gets below its critical voltage (when you add the voltage drop from the voltage converter), and the rPi reboots.

To restart donkey server automatically, do the following:
* Add this to /etc/rc.local:
su - pi -c 'cd ~/ohmc_car; python manage.py drive &>/tmp/out' &
* move 'source ~/env/bin/activate' from ~/.bashrc to ~/.profile

== Steering and throttle calibration ==

To save time at the workshop, you won't need to calibrate your car's steering and/or throttle.

However, you may get better results and can perform calibration when you have time ... [http://docs.donkeycar.com/guide/calibrate by following the DonkeyCar instructions]

== Data acquisition for the Neural Network ==

Once you are driving your car confidently around a track ... it is time to acquire training data for the Neural Network. DonkeyCar operates at 10 frames per second, capturing a 160x120 image, along with steering angle and throttle value. This is all stored in the ''$HOME/ohmc_car/tub/'' directory.

Before training, it is a good idea to clean out previous data. Don't just remove all the files in the ''tub/'' directory ! The ''tub/meta.json'' file is important.

[http://docs.donkeycar.com/guide/train_autopilot Extensive DonkeyCar documentation]

Perform the same commands as for manual driving ...

* ssh pi@$IP_ADDRESS
* cd ohmc_car
* python manage.py drive

Then via the web browser press the [Start Recording] button ... drive the car around a track ... then press the [Stop Recording] button.

It is recommended that you collect between 5K and 20K frames. At 10 frames per second, that is between 500 and 2,000 seconds of driving. Make sure that you drive clockwise and anti-clockwise.

You will need to type this command just once on your DonkeyCar (Raspberry Pi)to provide a directory on your laptop for your training data ...

* scp -pr ohmc_car $USERNAME@$HOSTNAME:

When finished acquisition, then transfer the data from the DonkeyCar (Raspberry Pi) to your laptop / desktop for training the Neural Network.

* scp -pr tub $USERNAME@$HOSTNAME:ohmc_car/tub_$DATE

== Training the Neural Network ==

Once training data has been copied to your laptop / desktop, you can begin training the Neural Network.

[http://docs.donkeycar.com/guide/train_autopilot Extensive DonkeyCar documentation]

Run these commands on your laptop / desktop to train the Neural Network ...

* workon donkeycar # For those who have set-up a virtualenv
* cd ohmc_car
* python manage.py train --tub $HOME/ohmc_car/tub_$DATE --model ./models/model_$DATE.hdf5

using donkey version: 2.5.7 ...
loading config file: /Users/andyg/play/ai/roba_car/config.py
config loaded
tub_names ./tub_2019-01-15c
train: 5740, validation: 1436
steps_per_epoch 44
Epoch 1/100
2019-01-21 13:08:49.507048: I tensorflow/core/platform/cpu_feature_guard.cc:140] Your CPU supports instructions that this TensorFlow binary was not compiled to use: AVX2 FMA
43/44 [============================>.] - ETA: 0s - loss: 58.5130 - angle_out_loss: 30.3421 - throttle_out_loss: 86.6839
Epoch 00001: val_loss improved from inf to 0.19699, saving model to ./models/roba0_2019-01-16c.hdf5
44/44 [==============================] - 38s 874ms/step - loss: 57.1887 - angle_out_loss: 29.6601 - throttle_out_loss: 84.7172 - val_loss: 0.1970 - val_angle_out_loss: 0.3230 - val_throttle_out_loss: 0.0710

On a modern laptop, each epoch will take around 30 seconds to complete. For up-to 100 epochs. Typically, you can expect around 20 to 40 epochs before the Neural Network stop learning. That is around 10 to 20 minutes of training time.

The training command creates the Neural Network weights that represent what your DonkeyCar has "learned".

When training has completed, copy the trained model back to your DonkeyCar (Raspberry Pi)

* scp $USERNAME@$HOSTNAME:ohmc_car/models/model_$DATE.hdf5 models

== Self-driving ... the ultimate goal ==

Once your trained model has been copied back onto the DonkeyCar (Raspberry Pi), your car can be self-driven as follow ...

* python manage.py drive --model ~/ohmc_car/models/models/model_$DATE.hdf5

This works similar to the manual driving mode with the addition of a trained model that can either ...

1) User: Manual control of both steering and throttle

2) Local Angle: Automatically control the steering angle

3) Local pilot: Automatically control both the steering angle and throttle amount

The web browser provides a drop-down menu to select between these options.

It is recommended to just start with Local Angle ... and control the throttle manually with the "i" key (faster) and "k" key (slower).

OHMC2019 Software instructions

2019-01-20T23:07:16Z

Marcmerlin:

Pebble V2.0 Instructions

2012-01-27T08:03:49Z

Marcmerlin:

== Hardware Overview ==

* Arduino Uno compatible, with ATmega328 and ATmega8U2 carrying the appropriate bootloaders.
* Boost-converter power supply for portable battery operation at battery voltages between 2.4-4.5 volts.
* RGB LED with each of the 3 LEDs independently programmable, including PWM capability.
* Standard HD44780 20x4 alphanumeric LCD display.
* Support for a low cost Nintendo DS style 4-wire resistive touchscreen (not included in the kit for LCA2012)
* Support for an XBee 802.15.4 radio module or any other "Bee"-compatible module that operates at 3.3V and talks to a serial UART (not included in the kit for LCA2012)
* Two general-purpose open-collector low-side-switching output transistors for controlling external devices such as relays.
* Rotary encoder for user input.
* Temperature sensor (MCP9701) and light sensor (TEMT6000).

==Getting Started==

Here's a basic guide to assembling a Pebble (Mk. 2) kit. In your kit, all the SMD components are pre-soldered on the board, the ATmega8U2 USB-to-serial circuit on the board has been pre-tested and the ATmega8U2 flashed appropriately, and the ATmega328 microcontroller has been pre-flashed with an appropriate Arduino Uno compatible bootloader.

Now, let's start assembling the through-hole components on the board. Don't worry, it's all pretty easy to assemble.

[[File:IMAG0615.jpg]]

== Kit Assembly (only the through-hole components)==

=== Terminal Blocks, Electrolytic Capacitors, Trimpot===

We will start by installing the 2-pin screw terminal block for the battery connection, in the upper left of the board. Make sure that the holes where the wires are inserted into the terminals face out towards the outside edge of the board. The sloped face need to face outwards. Next, we will also insert and solder the two 220 uF electrolytic capacitors in the upper left of the board. The capacitors are polarised, they need to be inserted into the board with the negative lead (the one marked with a stripe down the length of the capacitor body) inserted into the hole marked "-", and the positive lead (which should be longer) inserted into the hole marked "+".

The 10uH inductor is a large round cotton reel shaped component. It is not polarised. You will find that you are not able to mount it flush with the board, so just push it down firmly until it won't go any lower.

[[File:IMAG0619.jpg]]

We will also fit the shorting jumper onto the two-pin header at this stage.

The trimpot is used to adjust the LCD display contrast and is mounted in one way. Insert and solder the trimpot onto the board. It can only be inserted one way.

[[File:IMAG0624.jpg]]

=== Headers ===

Insert and solder the two 6-pin ISP programming headers, which have 2 rows of three pins. The ISP programming headers make a very snug fit into their holes on the PCB, and you may need to use some sort of tool (The end of the handle of a screwdriver or cutters) to apply firm pressure to press these fully down into place.

Insert and solder the 16-pin male header strip which connects to the LCD display.

Insert and solder the pair of 8-pin female header strips and the pair of 6-pin female header strips that are used to mate with Arduino "shields". The female headers don't always sit straight in the holes, so make sure you hold them straight while you solder just one of the pins to start with. Then you can adjust the alignment of the headers before soldering the rest of the pins.

[[File:IMAG0628.jpg]]

=== RGB LED ===

The RGB LED is a rounded, milky-coloured part with 4 long leads coming out one end.

'''Note: The RGB LED must be inserted the correct way, with the flat side of the LED corresponding to the silkscreen marking. One of the LED pins is longer than the others, and one of the holes in the PCB has a square pad. The long lead goes into the square pad.'''

If you have any doubt about the orientation of the RGB LED please ask for help. Soldering it in only takes a moment, but getting it back out again can be extremely difficult!

The four leads of the RGB LED will need to kind of splay out on an angle as you insert the LED onto the board, so it will end up sitting up approximately 5 mm off the board and it will not sit completely flush with the board. After ensuring that you have it oriented correctly, insert and solder in the RGB LED.

=== DIP Socket ===
Insert and solder the 28-pin DIP socket for the AVR microcontroller.

'''The IC socket should be inserted so that the pin-1 indicator notch on the socket corresponds to the silkscreen marking, with the notch to the right if you're holding the PCB as shown below.'''

[[File:IMAG0631.jpg]]

=== MCP9701 Temperature Sensor and 2N2222 Transistors ===

In the bottom right hand corner you will find three semi-circular shapes on the silscreen, which are for one MCP9701 temperature sensors and two 2N2222 transistors. All three parts are in "TO-92" packages, and look absolutely identical.

'''Careful! Don't get them mixed up and put the parts in the wrong spots. They are not interchangeable.'''

The only way to tell them apart is by looking at the extremely small printing on the face of the part. If you have trouble reading them, don't guess. There are magnifying glasses at the front of the room. To help ensure that you don't get them confused, it could be a good idea to separate out the MCP9701 and put the two P2N2222 transistors back in the bag or parts tray until you're ready to fit them.

The MCP9701 is mounted facing the bottom edge near the mounting hole, in the location labelled "Temp". Insert it and gently push it down until the body is about 5 to 8mm clear of the PCB. The leads will need to splay out a little to fit. Solder it in place carefully, doing each joint quickly and then letting the part cool down for a few seconds before doing the next one.

Insert and solder the two transistors in the same way.

==== Xbee Headers ====
It can be easier to hold the XBee header sockets in if you have an XBee module handy, by inserting the sockets onto the pins of the XBee module first and then inserting this assembly into the holes on the board. If you don't have an XBee module and don't intend to fit one, you can simply leave those headers off the board.

=== Rotary Encoder===
Now we'll also insert and solder the rotary encoder. It should "snap" into place on the board as its mechanical mounting tabs are inserted into the PCB. The tabs can be tricky to clip in though and you need to be careful not to bend the thin leads while wrestling with the mounting tabs. You may find it helpful to get the part fully aligned and then use a tiny screwdriver or similar to push the tabs sideways until they clip in.

=== LCD Module Header===
Unpack the LCD module and solder a 16-way pin male header onto its connection pads, with the header on the bottom of the PCB. The LCD connects to the Pebble via a ribbon cable (also supplied) so you can mount the display separately. When plugging them all together, make sure that pin 1 on the header on the PCB connects via the cable to pin 1 on the header on the LCD. One way to check is to hold the LCD directly over the PCB as if it was going to mount over the top of it, in which case the pins on the two sets of headers will naturally align correctly.

=== ATmega328P Microcontroller ===
'''Warning: the MCU is a static-sensitive part. Minimise your handling of the pins once it has been removed from its protective anti-static foam.'''

The orientation of the MCU is critical. Pin 1 is noted by a notch at one end of the IC. It may be hidden by the sticker but should be revealed by pushing the sticker back a little. Ask if you are not sure. You will find that the legs of the IC may not line up correctly with holes in the socket. Please do not force it as that trick never works. Instead use a flat surface such as the workbench to push the legs in a little bit and then repeat for the other side. The trick is to be "firm, but not brutal" - it can take a reasonable amount of force to bend all the pins straight, but it's easy to overdo it and fold them over. Once again, please ask for help with this step if unsure.

[[File:IMAG0638.jpg]]

===Testing===

Plug in the USB cable (which we've included for you) into a PC and into the Pebble board, and the blue power LED should light, and the new USB device should be recognized by the OS. If the power LED does not light, you '''did''' install the jumper to short out the USB power disconnection header, right? (Note that the power switch doesn't do anything except when battery power is used. If USB power is connected, then it is "always on".)

At this stage, you should be able to talk to the board from the PC. It's completely compatible with the Arduino Uno, but we re-used the same firmware used on the Freetronics Eleven, so it identifies itself as a Freetronics Eleven.

If your PC is running Windows, you'll need to [http://www.freetronics.com/pages/installing-the-usb-driver-file-for-windows install the driver] if you've never used an Arduino Uno or compatible device on your PC before. If you're running Linux or Mac OSX etc, then it should just work without any effort.

You'll also need to have the Arduino IDE installed, of course. Select "Arduino Uno" as the target hardware type, select the right (virtual) serial port for the Arduino IDE to talk to, and you should be all ready to upload programs.

If you want to use the LCD, you’ll need to attach the LCD display. This is done by making sure that your LCD display has a 16-pin header soldered onto it, and connecting the 16-wire ribbon cable to both the LCD display and the LCD header on the main board, making sure that '''pin 1 on the Pebble board is connected to pin 1 on the LCD display'''.

===Demo Software===

If you want test code, you can look at [http://marc.merlins.org/perso/arduino/post_2012-01-24_Much-Improved-Pebble-v2-Aiko-Demo-Code.html Marc MERLIN's page with a full test for most of the Pebble v2's hardware] (note the few example standalone programs that do not use Aiko at the end of that page, and hosted on https://github.com/marcmerlin/pebble_v2_demos ).

Marc's code was based on Andy's original work on github: https://github.com/geekscape/aiko_pebble_v2 .

===Hardware Features===

* Arduino Uno compatible, with ATmega328 and ATmega8U2 carrying the appropriate bootloaders.
* Boost-converter power supply for portable battery operation at battery voltages between 2.4-4.5 volts.
* RGB LED with each of the 3 LEDs independently programmable, including PWM capability.
* Standard HD44780 20x4 alphanumeric LCD display.
* Support for a low cost Nintendo DS style 4-wire resistive touchscreen.
* Support for an XBee 802.15.4 radio module or any other "Bee"-compatible module that operates at 3.3V and talks to a serial UART.
* Two general-purpose open-collector low-side-switching output transistors for controlling external devices such as relays.
* Rotary encoder for user input.
* Temperature sensor (MCP9701) and light sensor (TEMT6000).

===Battery power===

Now, if you want to use portable power without just being limited to USB use, let’s look at power options.

After you've programmed the board with some code, if you want to use an alternative power source away from your PC, you can either use battery power or you can provide regulated 5.0 V DC power to the USB socket via a standard USB cable - for example by using one of those common 5.0V mains switchmode plugpacks with a "dumb" USB connector for power output.

The battery voltage input must be within the range of about 2.4 - 4.5 V for correct operation. '''Thou shall not ever exceed 5 volts''', into either of the power supply inputs, on this device.

You can use two standard alkaline or NiCd or NiMH cells in series, for a voltage supply of 3.0 V (or 2.4 V if you’re using 1.2 V NiMH cells), or you can use 3.6-4.5 V from a set of three cells in series. The latter will provide an improvement in battery life. The 2.4 V you will get from two NiMH cells is OK, but it is towards the lower end of the operational voltage window.

You can use common “AA” or “AAA” cells, however the larger types such as “C” or “D” cells will provide greater charge capacity and a greater runtime. You could also use a 3.7 V lithium-polymer cell, where a small, lightweight battery with high energy density is desired. (Note that there is no battery holder included with the kit and you can add your own separately if you want to use battery power.)

Make sure that the positive and negative wires from the battery holder are connected to the terminal block on the board with the correct polarity, as marked on the silkscreen, and ensure that charged batteries are inserted into the battery holder with the correct polarity. With the batteries installed and wired up, you should then be able to turn on the power switch on the board, and the power LED should light up. (The on-board power switch has no effect if USB power is connected.) If you’re using a battery holder which has a built-in power switch then this power switch must also be turned on.

There is no battery charging electronics built into the device - to recharge your batteries they must be disconnected and recharged externally.

===Semi-permanent solder jumpers===

SJ1 is normally closed, this is for automatic reset of the AVR, controlled by the USB UART interface, during programming. Cut it to disable auto-reset.<br>
SJ2 connects the USB shield to ground. This is normally closed and should never normally need to be opened.<br>
SJ3 is normally open. This is for the DFU programming of the ATmega16U2 and should never need to be closed.<br>
SJ4 is normally closed, and this connects the high side of the two low-side-switching open collector output transistors to +5V. Disconnect it if you want to use an external higher-voltage power supply for these circuits.

Pebble V2.0 Instructions

2012-01-27T07:58:37Z

Marcmerlin: /* Testing */

== Hardware Overview ==

* Arduino Uno compatible, with ATmega328 and ATmega8U2 carrying the appropriate bootloaders.
* Boost-converter power supply for portable battery operation at battery voltages between 2.4-4.5 volts.
* RGB LED with each of the 3 LEDs independently programmable, including PWM capability.
* Standard HD44780 20x4 alphanumeric LCD display.
* Support for a low cost Nintendo DS style 4-wire resistive touchscreen (not included in the kit for LCA2012)
* Support for an XBee 802.15.4 radio module or any other "Bee"-compatible module that operates at 3.3V and talks to a serial UART (not included in the kit for LCA2012)
* Two general-purpose open-collector low-side-switching output transistors for controlling external devices such as relays.
* Rotary encoder for user input.
* Temperature sensor (MCP9701) and light sensor (TEMT6000).

==Getting Started==

Here's a basic guide to assembling a Pebble (Mk. 2) kit. In your kit, all the SMD components are pre-soldered on the board, the ATmega8U2 USB-to-serial circuit on the board has been pre-tested and the ATmega8U2 flashed appropriately, and the ATmega328 microcontroller has been pre-flashed with an appropriate Arduino Uno compatible bootloader.

Now, let's start assembling the through-hole components on the board. Don't worry, it's all pretty easy to assemble.

[[File:IMAG0615.jpg]]

== Kit Assembly (only the through-hole components)==

=== Terminal Blocks, Electrolytic Capacitors, Trimpot===

We will start by installing the 2-pin screw terminal block for the battery connection, in the upper left of the board. Make sure that the holes where the wires are inserted into the terminals face out towards the outside edge of the board. The sloped face need to face outwards. Next, we will also insert and solder the two 220 uF electrolytic capacitors in the upper left of the board. The capacitors are polarised, they need to be inserted into the board with the negative lead (the one marked with a stripe down the length of the capacitor body) inserted into the hole marked "-", and the positive lead (which should be longer) inserted into the hole marked "+".

The 10uH inductor is a large round cotton reel shaped component. It is not polarised. You will find that you are not able to mount it flush with the board, so just push it down firmly until it won't go any lower.

[[File:IMAG0619.jpg]]

We will also fit the shorting jumper onto the two-pin header at this stage.

The trimpot is used to adjust the LCD display contrast and is mounted in one way. Insert and solder the trimpot onto the board. It can only be inserted one way.

[[File:IMAG0624.jpg]]

=== Headers ===

Insert and solder the two 6-pin ISP programming headers, which have 2 rows of three pins. The ISP programming headers make a very snug fit into their holes on the PCB, and you may need to use some sort of tool (The end of the handle of a screwdriver or cutters) to apply firm pressure to press these fully down into place.

Insert and solder the 16-pin male header strip which connects to the LCD display.

Insert and solder the pair of 8-pin female header strips and the pair of 6-pin female header strips that are used to mate with Arduino "shields". The female headers don't always sit straight in the holes, so make sure you hold them straight while you solder just one of the pins to start with. Then you can adjust the alignment of the headers before soldering the rest of the pins.

[[File:IMAG0628.jpg]]

=== RGB LED ===

The RGB LED is a rounded, milky-coloured part with 4 long leads coming out one end.

'''Note: The RGB LED must be inserted the correct way, with the flat side of the LED corresponding to the silkscreen marking. One of the LED pins is longer than the others, and one of the holes in the PCB has a square pad. The long lead goes into the square pad.'''

If you have any doubt about the orientation of the RGB LED please ask for help. Soldering it in only takes a moment, but getting it back out again can be extremely difficult!

The four leads of the RGB LED will need to kind of splay out on an angle as you insert the LED onto the board, so it will end up sitting up approximately 5 mm off the board and it will not sit completely flush with the board. After ensuring that you have it oriented correctly, insert and solder in the RGB LED.

=== DIP Socket ===
Insert and solder the 28-pin DIP socket for the AVR microcontroller.

'''The IC socket should be inserted so that the pin-1 indicator notch on the socket corresponds to the silkscreen marking, with the notch to the right if you're holding the PCB as shown below.'''

[[File:IMAG0631.jpg]]

=== MCP9701 Temperature Sensor and 2N2222 Transistors ===

In the bottom right hand corner you will find three semi-circular shapes on the silscreen, which are for one MCP9701 temperature sensors and two 2N2222 transistors. All three parts are in "TO-92" packages, and look absolutely identical.

'''Careful! Don't get them mixed up and put the parts in the wrong spots. They are not interchangeable.'''

The only way to tell them apart is by looking at the extremely small printing on the face of the part. If you have trouble reading them, don't guess. There are magnifying glasses at the front of the room. To help ensure that you don't get them confused, it could be a good idea to separate out the MCP9701 and put the two P2N2222 transistors back in the bag or parts tray until you're ready to fit them.

The MCP9701 is mounted facing the bottom edge near the mounting hole, in the location labelled "Temp". Insert it and gently push it down until the body is about 5 to 8mm clear of the PCB. The leads will need to splay out a little to fit. Solder it in place carefully, doing each joint quickly and then letting the part cool down for a few seconds before doing the next one.

Insert and solder the two transistors in the same way.

==== Xbee Headers ====
It can be easier to hold the XBee header sockets in if you have an XBee module handy, by inserting the sockets onto the pins of the XBee module first and then inserting this assembly into the holes on the board. If you don't have an XBee module and don't intend to fit one, you can simply leave those headers off the board.

=== Rotary Encoder===
Now we'll also insert and solder the rotary encoder. It should "snap" into place on the board as its mechanical mounting tabs are inserted into the PCB. The tabs can be tricky to clip in though and you need to be careful not to bend the thin leads while wrestling with the mounting tabs. You may find it helpful to get the part fully aligned and then use a tiny screwdriver or similar to push the tabs sideways until they clip in.

=== LCD Module Header===
Unpack the LCD module and solder a 16-way pin male header onto its connection pads, with the header on the bottom of the PCB. The LCD connects to the Pebble via a ribbon cable (also supplied) so you can mount the display separately. When plugging them all together, make sure that pin 1 on the header on the PCB connects via the cable to pin 1 on the header on the LCD. One way to check is to hold the LCD directly over the PCB as if it was going to mount over the top of it, in which case the pins on the two sets of headers will naturally align correctly.

=== ATmega328P Microcontroller ===
'''Warning: the MCU is a static-sensitive part. Minimise your handling of the pins once it has been removed from its protective anti-static foam.'''

The orientation of the MCU is critical. Pin 1 is noted by a notch at one end of the IC. It may be hidden by the sticker but should be revealed by pushing the sticker back a little. Ask if you are not sure. You will find that the legs of the IC may not line up correctly with holes in the socket. Please do not force it as that trick never works. Instead use a flat surface such as the workbench to push the legs in a little bit and then repeat for the other side. The trick is to be "firm, but not brutal" - it can take a reasonable amount of force to bend all the pins straight, but it's easy to overdo it and fold them over. Once again, please ask for help with this step if unsure.

[[File:IMAG0638.jpg]]

===Testing===

Plug in the USB cable (which we've included for you) into a PC and into the Pebble board, and the blue power LED should light, and the new USB device should be recognized by the OS. If the power LED does not light, you '''did''' install the jumper to short out the USB power disconnection header, right? (Note that the power switch doesn't do anything except when battery power is used. If USB power is connected, then it is "always on".)

At this stage, you should be able to talk to the board from the PC. It's completely compatible with the Arduino Uno, but we re-used the same firmware used on the Freetronics Eleven, so it identifies itself as a Freetronics Eleven.

If your PC is running Windows, you'll need to [http://www.freetronics.com/pages/installing-the-usb-driver-file-for-windows install the driver] if you've never used an Arduino Uno or compatible device on your PC before. If you're running Linux or Mac OSX etc, then it should just work without any effort.

You'll also need to have the Arduino IDE installed, of course. Select "Arduino Uno" as the target hardware type, select the right (virtual) serial port for the Arduino IDE to talk to, and you should be all ready to upload programs.

If you want to use the LCD, you’ll need to attach the LCD display. This is done by making sure that your LCD display has a 16-pin header soldered onto it, and connecting the 16-wire ribbon cable to both the LCD display and the LCD header on the main board, making sure that '''pin 1 on the Pebble board is connected to pin 1 on the LCD display'''.

If you want test code, you can look at [http://marc.merlins.org/perso/arduino/post_2012-01-24_Much-Improved-Pebble-v2-Aiko-Demo-Code.html Marc MERLIN's page with a full test for most of the Pebble v2's hardware] (note the few example standalone programs that do not use Aiko at the end of that page, and hosted on https://github.com/marcmerlin/pebble_v2_demos )

===Hardware Features===

* Arduino Uno compatible, with ATmega328 and ATmega8U2 carrying the appropriate bootloaders.
* Boost-converter power supply for portable battery operation at battery voltages between 2.4-4.5 volts.
* RGB LED with each of the 3 LEDs independently programmable, including PWM capability.
* Standard HD44780 20x4 alphanumeric LCD display.
* Support for a low cost Nintendo DS style 4-wire resistive touchscreen.
* Support for an XBee 802.15.4 radio module or any other "Bee"-compatible module that operates at 3.3V and talks to a serial UART.
* Two general-purpose open-collector low-side-switching output transistors for controlling external devices such as relays.
* Rotary encoder for user input.
* Temperature sensor (MCP9701) and light sensor (TEMT6000).

===Battery power===

Now, if you want to use portable power without just being limited to USB use, let’s look at power options.

After you've programmed the board with some code, if you want to use an alternative power source away from your PC, you can either use battery power or you can provide regulated 5.0 V DC power to the USB socket via a standard USB cable - for example by using one of those common 5.0V mains switchmode plugpacks with a "dumb" USB connector for power output.

The battery voltage input must be within the range of about 2.4 - 4.5 V for correct operation. '''Thou shall not ever exceed 5 volts''', into either of the power supply inputs, on this device.

You can use two standard alkaline or NiCd or NiMH cells in series, for a voltage supply of 3.0 V (or 2.4 V if you’re using 1.2 V NiMH cells), or you can use 3.6-4.5 V from a set of three cells in series. The latter will provide an improvement in battery life. The 2.4 V you will get from two NiMH cells is OK, but it is towards the lower end of the operational voltage window.

You can use common “AA” or “AAA” cells, however the larger types such as “C” or “D” cells will provide greater charge capacity and a greater runtime. You could also use a 3.7 V lithium-polymer cell, where a small, lightweight battery with high energy density is desired. (Note that there is no battery holder included with the kit and you can add your own separately if you want to use battery power.)

Make sure that the positive and negative wires from the battery holder are connected to the terminal block on the board with the correct polarity, as marked on the silkscreen, and ensure that charged batteries are inserted into the battery holder with the correct polarity. With the batteries installed and wired up, you should then be able to turn on the power switch on the board, and the power LED should light up. (The on-board power switch has no effect if USB power is connected.) If you’re using a battery holder which has a built-in power switch then this power switch must also be turned on.

There is no battery charging electronics built into the device - to recharge your batteries they must be disconnected and recharged externally.

===Semi-permanent solder jumpers===

SJ1 is normally closed, this is for automatic reset of the AVR, controlled by the USB UART interface, during programming. Cut it to disable auto-reset.<br>
SJ2 connects the USB shield to ground. This is normally closed and should never normally need to be opened.<br>
SJ3 is normally open. This is for the DFU programming of the ATmega16U2 and should never need to be closed.<br>
SJ4 is normally closed, and this connects the high side of the two low-side-switching open collector output transistors to +5V. Disconnect it if you want to use an external higher-voltage power supply for these circuits.