{{DISPLAYTITLE:OHMC for LCA2022: Welcome!}}

== Status, About us, Contact us ==
* OHMC talk submissions are open. [https://linux.conf.au/programme/miniconfs/open-hardware/ Submit your talk proposals today]. Deadline: September 5 2021



* [https://twitter.com/openhardware_mc Twitter @OpenHardware_mc]: Follow for project notifications. HashTags: ''#ohmc22, #lca2022''

== Getting started ==

We are looking to make the most out of [[Swagbadge2021|last year's Swagbadge]], with even more deliciousness in the form of a fabulous SAO (or two). We're looking at sound, we're looking at lights. We're looking at a DIY disco!

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

== Announcements ==

'''2021-08-06: Open Hardware mini conference is accepted''' for LCA 2022.
* We'll be listening for questions and feedback sent to [https://twitter.com/OpenHardware_mc Twitter @OpenHardware_MC]
* Want to join in on the fun? You can build your own [[Swagbadge2021_Dagbadge|Dagbadge]]

== About OHMC 2022 ==

One of the drivers of the popularity of the Open Hardware community is easy access to inexpensive and capable microcontrollers and development boards such as the Arduino and ESP32.

In 2022, for the first time at OHMC, we’re diving into the wonderful world of FPGAs… and fully embracing the LCA2022 theme of community.

Not only do FPGAs open up new capabilities for your projects, but they also help bring Open Source further down the stack closer to the silicon. It is easier than ever to run Open Source software on an Open Source processor core (RISC-V) that you can hack yourself, and install directly onto an FPGA using an Open Source FPGA development tool chain.

If you’ve never used an FPGA before, or don’t even know what it stands for, don’t worry. We’ll take you through the basics and get you started with a Simple Add-On (SAO) that can be used standalone or plugged into many different electronic conference badges. If you have an LCA2021 SwagBadge you can combine it with the LCA2022 SAO to build a musical project that will demonstrate the unique capabilities of FPGAs.

We’ll also have an updated LCA2022 SwagBadge available in case you didn’t get one last year. There will be opportunities in the months leading up to LCA2022 for you to participate in online workshops and local community events to learn about skills such as soldering, PCB design (your own SAO) and developing applications for your SwagBadge / SAOs (both 2021 and 2022 variants).

The mini-conference day will run in two distinct halves. The morning sessions will discuss the design of the LCA2022 FPGA SAO and SwagBadge applications, explaining how to use the hardware and firmware that runs on them. The afternoon sessions will be presentations about more general Open Hardware topics, with contributions by both LCA2022 attendees and the OHMC team.

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

2021-01-25T05:11:08Z

Nicola: /* Hardware reference */

{{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> - collection of programs, one of which is configured to run automatically on bootup. Each application must have an initialise() function
* <code>configuration</code> - control the behavior of Aiko by changing the "settings", e.g configuration/main.py specifies which application to run
* <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. Annunciators always are displayed.

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 (firmly but 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 aiko import button

left_screen = 16
right_screen = 17

def my_button_handler(number, state):
print("Button {}: {}".format(number, "press" if state else "release"))

button.add_button_handler(my_button_handler, [left_screen, right_screen])
aiko.button.add_touch_handler(my_button_handler, [12, 14, 15, 27])
aiko.button.remove_handler(my_button_handler)

def my_multibutton_handler(pin_numbers):
print("Multibutton {}".format(pin_numbers))
button.add_multibutton_handler(my_multibutton_handler, [12, 14])
button.add_multibutton_handler(my_multibutton_handler, [15, 27])
button.remove_handler(my_multibutton_handler)
</pre>

=== 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>
import aiko.button as button
import aiko.common as common

bottom_left = 12
top_left = 15
bottom_right = 14
top_right = 27

def my_slider_handler(number, state, value):
print("Slider {}: {} {}".format(number, state, value))
# use the map handler to give you the slider values mapped from its min-max to yours
mapped_value = int(common.map_value(value, 0, 100, 1, 5))

aiko.button.add_slider_handler(my_slider_handler, bottom_left, top_left)
aiko.button.add_slider_handler(my_slider_handler, bottom_right, top_right)
aiko.button.remove_handler(my_slider_handler)

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

Micropython functions
* '''common.touch_pins_check(touchpad_array)''' - Returns true if ''all'' the touchpad sensors listed are being touched, false otherwise.
* '''common.map_value(input, in_min, in_max, out_min, out_max)''': map an input range to an output range and convert the input value to a value in the output range.

=== SAOs (simple addons) ===

Information about [[Swagbadge2021_SAO|hardware]]

Swagbadge2021 community

2021-01-25T01:03:59Z

Nicola: /* Connective and reactive applications on the badge */

= Badge community =

== Connective and reactive applications on the badge ==

* [https://twitter.com/Techman_83/status/1352934982310744064?s=20 #lcahugs]: Light up [https://twitter.com/Techman_83 @techman_83]'s glowy lanyard every time you tag him with #lcahugs on Twitter.
* [https://twitter.com/mibus/status/1350394136910680064?s=20 IRC bridge]: Follow along with IRC chat on your badge screens from [https://twitter.com/mibus @mibus]
* [https://twitter.com/Enderboi/status/1352845142068142081?s=20 Remote handshake]: Send the right message to [https://twitter.com/Enderboi @enderboi]'s badge over MQTT and it'll trigger a 'handshake'!
* [https://twitter.com/neonsignal/status/1352855595028602882?s=20 Conference screencast to the badge]: 0.1fps to watch talks... on your badge, from [https://twitter.com/neonsignal @neonsignal]
* [https://twitter.com/FemmeOnAFarm/status/1353152499868332033 Controlling lights at home with badge sliders] from [https://twitter.com/FemmeOnAFarm @FemmeOnAFarm]
* [https://twitter.com/nye_nicola/status/1353299856027074560?s=20 Googly eyes] on screens, from [https://twitter.com/nye_nicola @nye_nicola]
* [https://twitter.com/ClaireCities/status/1353507647052365825?s=20 Eyes that follow your hand], using a SAO to detect hand movement, from [https://twitter.com/ClaireCities @ClaireCities]

== Games ==

* [https://github.com/permezel/aiko_engine_mp.git Tower of Hanoi]: via [https://github.com/permezel Permezel]

== SAO specific ==

* [https://twitter.com/MrAlexar/status/1352818426771693570?s=20 Pic of solder rocket]: Cute little rocket SAO designed by [https://twitter.com/mage0r @mage0r]
* [https://twitter.com/FemmeOnAFarm/status/1352815126613614592?s=20 Light up Tux SAO]: modified Tux SAO with leds, from [https://twitter.com/FemmeOnAFarm @FemmeOnAFarm]

== Supporting software ==

* [https://twitter.com/AlexVerrico/status/1352137353708519426?s=20 Web console]: control your badge via a web interface, from [https://twitter.com/AlexVerrico @AlexVerrico]

== Accessories ==

* [https://twitter.com/thilinag/status/1353119549252489217?s=20 3D printed protective case] from [https://twitter.com/thilinag @thilinag]
* [https://twitter.com/yaleman43381258/status/1352825379724042240?s=20 3D printed stand] from [https://twitter.com/yaleman43381258 @yaleman43381258]
* [https://twitter.com/swagbadge2021/status/1352810977855590400?s=20 Badge power] with LiPo