Open Hardware Miniconf - User contributions [en]

Swagbadge2021 UpdatingSoftware

2020-12-22T21:57:19Z

BenLeslie: /* Saving your private key */

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

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

Swagbadge2021 UpdatingSoftware

2020-12-22T21:55:07Z

BenLeslie: Add section on your private key

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

Todo

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

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

Swagbadge2021 GettingStarted

2020-12-22T21:53:58Z

BenLeslie: /* Getting the device on your wifi - commandline with mpfshell */

= 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 =
* Pre-installed things, how to access and run them.

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

= Extensions: Updating the software framework =

Between when we ship the board and when it arrives, there might be some changes to the software framework (Aiko). Here's how to update it. Or perhaps you're interested in writing your own applications?

[[Swagbadge2021_UpdatingSoftware|Updating the Software]]

Swagbadge2021 GettingStarted

2020-12-22T05:02:53Z

BenLeslie: /* My package arrived in the mail, first steps. */

= 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 2G network: it is not compatible with 5g.''
* 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 =
* Pre-installed things, how to access and run them.

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

= Extensions: Updating the software framework =

Between when we ship the board and when it arrives, there might be some changes to the software framework (Aiko). Here's how to update it. Or perhaps you're interested in writing your own applications?

[[Swagbadge2021_UpdatingSoftware|Updating the Software]]

Swagbadge2021 GettingStarted

2020-12-22T05:00:06Z

BenLeslie: /* My package arrived in the mail, first steps. */

= 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 2G network: it is not compatible with 5g.''
* 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 =
* Pre-installed things, how to access and run them.

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

= Extensions: Updating the software framework =

Between when we ship the board and when it arrives, there might be some changes to the software framework (Aiko). Here's how to update it. Or perhaps you're interested in writing your own applications?

[[Swagbadge2021_UpdatingSoftware|Updating the Software]]

Swagbadge2021 GettingStarted

2020-12-22T04:56:49Z

BenLeslie: /* My package arrived in the mail, first steps. */

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

[[File:swagbadgepackage.jpg|400px]]

* 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 2G network: it is not compatible with 5g.''
* 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 =
* Pre-installed things, how to access and run them.

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

= Extensions: Updating the software framework =

Between when we ship the board and when it arrives, there might be some changes to the software framework (Aiko). Here's how to update it. Or perhaps you're interested in writing your own applications?

[[Swagbadge2021_UpdatingSoftware|Updating the Software]]

Swagbadge2021 GettingStarted

2020-12-22T04:56:04Z

BenLeslie: /* My package arrived in the mail, first steps. */

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

[[File:swagbadgepackage.jpg]]

* 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 2G network: it is not compatible with 5g.''
* 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 =
* Pre-installed things, how to access and run them.

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

= Extensions: Updating the software framework =

Between when we ship the board and when it arrives, there might be some changes to the software framework (Aiko). Here's how to update it. Or perhaps you're interested in writing your own applications?

[[Swagbadge2021_UpdatingSoftware|Updating the Software]]

File:Swagbadgepackage.jpg

2020-12-22T04:55:56Z

BenLeslie:

Swagbadge2021 UpdatingSoftware

2020-12-22T04:46:59Z

BenLeslie: /* Setting up your Mac OS system for connecting to #swagbadge hardware */

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

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

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

Swagbadge2021 UpdatingSoftware

2020-12-22T04:42:12Z

BenLeslie: /* Setting up your Mac OS system for connecting to #swagbadge hardware */

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

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

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

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