This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

SHA2017

SHA2017

On this page you’ll find all the hints, tips, datasheets, secret codes and assorted stuff you’ll need to hack the SHA2017 Badge!

Badge presentation

Please see the talk (slides) we gave during SHA for a nice overview on how we managed to pull this project off.

The team

The SHA2017 badge would not have been possible without the help of these amazing volunteers.

Team leads: Niek Blankers, Sebastian Oort

  • Markus Bechtold: hardware
  • Anne Jan Brouwer
  • Bas van Sisseren: epaper display driver, software
  • Gavan Fantom
  • Jeroen Domburg
  • Niek Blankers
  • Sebastian Oort
  • Renze Nicolai
  • Arnout Engelen

1 - Getting started

Please remember the badge project is a huge volunteer effort - please approach it as a hacker, not as a consumer :). Lots of things can still be improved, and your help is much appreciated! This still holds true August 2019!

Unpacking and assembling

WiFi setup

You can configure the WiFi network by starting the WiFi setup app on your badge.

By default the badge will try to connect to an open network called “SHA2017-insecure”.

OTA update

The first thing to do after starting up the badge for the first time is do an OTA (Over The Air) update. This will make a connection with the hatchery and download the latest available version of the badge software.

Booting the badge for the first time and general use

When booting for the first time the badge will still be on the (now very old) firmware that it came with out of the box. Following the steps below allows you to easily get to the latest-greatest firmware we have to offer.

Nickname configuration

After the badge starts for the first time you will be prompted to enter your nickname. You can do so by selecting keys on the on-screen keyboard and pressing A to press the selected key.

Once you are done you can press the select button to switch to the OK/CANCEL buttons. The OK button is selected by default. Press A to click on the on-screen OK button.

If you don’t enter a nickname you will instantly skip the sponsor reel and drop into the menu!

Configuring WiFi

When you first enter the main menu the badge will try to connect to the SHA2017 network. Wait for the WiFi connection to fail and press START to enter the app launcher.

Select the “WiFi setup” app, pick your network from the list and enter the password.

Then wait (again) for the main menu to do it’s thing and press START to open the launcher again.

This time select “OTA update” or “Firmware update” from the menu. This will start the upgrade process.

Connecting to your computer

When connected to your computer using the USB connection of your badge you can access a handy menu system to configure your badge as well as a full Python prompt. Connecting to your computer allows you to see what’s going on inside the software of your badge, allowing you to debug your app, test new code snippets, upload files and load new or custom firmware.

To get started install the driver, download a terminal emulation program of your choice (for Windows we recommend either TeraTerm or Putty) and connect to your badge at 115200 baud. After waking up your badge from sleep mode you should be presented with a menu.

menu

For more information on the serial console of your badge please have a look at the USB-serial connection article of the App development section.

And now?

Congratulations! You should now be on our new platform firmware. Note that not everything works yet and that you might experience some problems.

Having problems? We have a troubleshooting page just for that.

Want to start developing apps? check out out App development section.

2 - Driver installation

The SHA2017 badge uses a Silicon Labs CP2102 USB to serial converter for communication with your computer.

You can find the driver for this chip on the Silicon Labs website.

The badge expects you to connect to it at 115200 baud. Note that the badge will not respond when in sleep mode. After connecting over USB be sure to wake the badge up either by touching one of the touch buttons or by pressing the RESET button on the back.

3 - Hardware

Components

E-ink display: the DKE Group DEPG0290B1

The DKE Group DEPG0290B1 is used on the SHA Badge.

Datasheet: DEPG0290B01V3.0.pdf

In case you want to build a SHA2017 badge yourself or in case you broke the display that came with your badge back in 2017 you might have noticed that the display is hard to come by so we also support a pinout compatible alternative: the GDEH029A1. For this alternative display to function you need to set a flag in the non-volitile memory of your badge. Go to the shell of your device and type in the following command to switch the display type: import machine;machine.nvs_set_u8('system','eink.dev.type',1). To reset your badge to the default DEPG0290B1 type display enter the following command: import machine;machine.nvs_set_u8('system','eink.dev.type',2).

The datasheet does a very good job explaining how to initialize the display and get it to picture something. The LUT is explained in the section below, because THAT isn’t really documented at all…

Look Up Table (LUT)

The LUT is a small ‘program’ the display executes each time you refresh the display. It is arranged in two sections of 35 bytes. The first half configures voltages (TBD). The second half is the program.

  // Voltages and other settings? Timing?
   0xA0,	0x90,	0x50,	0x0,	0x0,	0x0,	0x0,
   0x50,	0x90,	0xA0,	0x0,	0x0,	0x0,	0x0,
   0xA0,	0x90,	0x50,	0x0,	0x0,	0x0,	0x0,
   0x50,	0x90,	0xA0,	0x0,	0x0,	0x0,	0x0,
   0x00,	0x00,	0x00,	0x0,	0x0,	0x0,	0x0,

   // Update program
   //
   // Top three lines are the main program (bottom 4 have unknown function)
   // Line 1: Negative image
   // Line 2: White/Black flashing
   // Line 3: Positive image
   //
   // Line construction
   // First two bytes denote Intensity (range 0x00 to 0x0F)
   // Second two bytes denote lenght of each 'pulse' (range 0x00 to 0xFF)
   // Last byte denotes number of repeats (0 = line runs 1 time, range 0x00 to 0xFF)
   // If you don't want a line to do anything, set all bytes to 0x0.
   // This way you can make a quick update cycle between two screens.
   // Maybe not as pretty/crisp but nice and fast is also awesome!

   // Negative image
   // first two bytes negative image, length white pulse (0-FF), length black pulse (0-FF), last byte repeats

   0xF,	0xF,	0x0,	0x0,	0x0,

   // White or black flash
   // white flash intensity, black flash intensity, length white pulse (0-FF), length black pulse (0-FF), repeats

   0xF,	0xF,	0x0,	0x0,	0x02,

   // Positive image
   // first byte or second byte positive image (don't know why you need both), rest same as above

   0xF,	0xF,	0x0,	0x0,	0x0,

   // Unknown what lines below actually do.
   // They seem to be programs to, but have no visible effect on dislay.
   0x0,	0x0,	0x0,	0x0,	0x0,
   0x0,	0x0,	0x0,	0x0,	0x0,
   0x0,	0x0,	0x0,	0x0,	0x0,
   0x0,	0x0,	0x0,	0x0,	0x0,

Microcontroller: the Espressif ESP32 Wroom module

The SHA2017Badge uses a Special ESP-WROOM-32 module with a 128 Mbit flash

ESP32 is a series of low cost, low power system on a chip microcontrollers with integrated Wi-Fi & dual-mode Bluetooth. The ESP32 series employs a Tensilica Xtensa LX6 microprocessor in both dual-core and single-core variations. ESP32 is created and developed by Espressif Systems, a Shanghai-based Chinese company, and is manufactured by TSMC using their 40 nm process. It is a successor to the ESP8266 microcontroller.

Features

Features of the ESP32 include the following:

  • CPU: Xtensa Dual-Core 32-bit LX6 microprocessor, operating at 160 or 240 MHz and performing at up to 600 DMIPS
  • Memory: 520 KiB SRAM
  • Wireless connectivity:
  • Wi-Fi: 802.11 b/g/n/e/i
  • Bluetooth: v4.2 BR/EDR and BLE
  • Peripheral interfaces:
  • 12-bit SAR ADC up to 18 channels
  • 2 × 8-bit DACs
  • 10 × touch sensors
  • Temperature sensor
  • 4 × SPI
  • 2 × I²S
  • 2 × I²C
  • 3 × UART
  • SD/SDIO/MMC host
  • Slave (SDIO/SPI)
  • Ethernet MAC interface with dedicated DMA and IEEE 1588 support
  • CAN bus 2.0
  • IR (TX/RX)
  • Motor PWM
  • LED PWM up to 16 channels
  • Hall effect sensor
  • Ultra low power analog pre-amplifier
  • Security:
  • IEEE 802.11 standard security features all supported, including WFA, WPA/WPA2 and WAPI
  • Secure boot
  • Flash encryption
  • 1024-bit OTP, up to 768-bit for customers
  • Cryptographic hardware acceleration: AES, SHA-2, RSA, elliptic curve cryptography (ECC), random number generator (RNG)
  • Power Management
  • Internal LDO
  • Individual power domain for RTC
  • 5uA deep sleep current
  • Wake up from GPIO interrupt, timer, ADC measurements, capacitive touch sensor interrupt

block-diagram

Touch controller: the MPR121 Touch Sensor and GPIO expander

The Freescale/NXP MPR121 serves as both the capacitive touch controller and as a GPIO expander on the badge. It is connected to the ESP32 through I2C and an interrupt line.

Documents

Connections

  • The MPR121 is connected to the ESP32 through I2C on pins IO26 (SDA) and IO27 (SCL).

  • Software pullups are not necessary, as there are two pullup resistors on the board.

  • The MPR’s interrupt pin is connected to IO25 on the ESP.

  • Its I2C slave address is 0x5A.

The MPR121 has twelve electrode connections (ELE0-11), of which eight can be used as GPIO. We are using the last four electrode connections as I/O.

ElectrodeGPIOFunction / directionConnection
ELE0-TouchA
ELE1-TouchB
ELE2-TouchStart
ELE3-TouchSelect
ELE4GPIO0TouchDown
ELE5GPIO1TouchRight
ELE6GPIO2TouchUp
ELE7GPIO3TouchLeft
ELE8GPIO4Push/pull outputVibration motor
ELE9GPIO5InputTP4056 Charge status
ELE10GPIO6Push/pull outputWS2812 / SD Card power enable
ELE11GPIO7InputSD Card detect
NOT FUNCTIONAL

Touch

The most important function of the MPR121: capacitive touch. I (Kartoffel) will describe how I was able to get it to work, though it might not be ideal and definitely needs tweaking. I left a lot of registers unexplored, and did not implement the over current detection which can halt the IC.

The basic setup steps:

  • Initialize global baseline filter (registers 0x2B to 0x40) - see AN3891 for information about the baseline system.

  • Set the touch and release thresholds for each electrode (registers 0x41 to 0x5A).

  • Set electrode sample interval (register 0x5D) - this directly influences the current consumption.

Finally, to get the MPR121 into run mode:

  • Enable the electrodes for touch detection (register 0x5E) - set this to 0x08 to enable just ELE0-ELE7 to make sure we can use the rest as GPIO.

Now the MPR is in run mode and scanning the touch electrodes.

When the state of an electrode changes the interrupt pin will go low, and the state should be read by the ESP. Register 0x0 holds the touch status of ELE0 to ELE7.

GPIO

We are using ELE8-11 (GPIO4-7) as GPIO. The MPR uses eight registers to control its GPIO pins:

RegisterFunction
0x73GPIO Control 0
0x74GPIO Control 1
0x75GPIO Data
0x76GPIO Direction
0x77GPIO Enable
0x78Data set
0x79Data clear
0x7AData toggle

In order to use the GPIO pins, we first have to initialize them:

  • Set the GPIO direction of IO4 and IO6 as output, IO5 and IO7 as input. (adress 0x76, data 0x50)

  • Set the control registers. For CMOS outputs and inputs without pullups, both of these should be set to 0 for GPIO4-7. (adress 0x73, data 0x00 and adress 0x74, data 0x00)

  • Enable GPIO4-7 by writing 0xF0 to the GPIO Enable register. (adress 0x77, data 0xF0)

Next, the two output pins can be set to HIGH, LOW, or their state can be toggled with the Data Set, Data Clear, and Data Toggle registers. The state of the input pins can be read in register 0x01.

The GPIO5 and GPIO7 inputs have external pullup resistors, so they do not need internal bias.

IRQ

The IRQ-pin is connected to the ESP32 on IO25. It is an active-low pin that triggers on a touch-event (being touched or no longer being touched) and resets upon reading the registers via I2c. That way you can easily do an interrupt in your code or choose to ignore inputs until you have time to handle them.

LEDs: the blinky LEDs you can add

There are six pads for WS2812 or SK6812 LEDs on the front. Guess what? You can add them on yourself! Why? Because adding components to the front of the board is expensive (the board has to go through the machine twice). Have no fear, at camp there are plenty of capable hackers to help you if soldering isn’t your thing.

The LEDs are powered via a mosfet switched on by ELE10 on the MPR121 (i2c adress 0x5A, write to register 0x78, data 0x40). After that, blast your favorite WS2812 or SK6812 routine through GPIO32 on the ESP32! Have fun burning your eyes!

Using our platform firmware? See the neopixel API description for more information.

import neopixel
data = [0xFF, 0xFF, 0xFF, 0xFF]*6 #Fully turn on all the LEDs
neopixel.send(bytes(data))

Expanding

More you say? You want more? Sure, The data-out from the last LED is broken out on the expansion connector.

Be careful with drawing power from this connector, you could burn out the regulator, a fuse or just drain your battery really fast!

Power and battery

  • Pin-compatible with the AMS1117, but we do not recommend that one because of its high quiescent current consumption!

Battery

The SHA2017 badge uses a lithium polymer battery.

TechnologyLithium Polymer
Capacity1000mAh
Cells1 (1S, 3.7v)
ProtectionBuilt-in: over/under voltage and over current
ConnectorJST-PH3

USB-serial: Silicon Labs CP2102

Requires driver under macOS, found at the Silicon Labs website

Add-ons

Connector pinout:

GNDLED_POWERIO_33IO_16IO_17I2C_SCL
3V3_SWITCHEDGNDIO_12IO_4LED_DATA_OUTI2C_SDA

Hacks

Weatherproofing

  • Nailpolish seems to do the trick. Switches on the back will probably be unusable after applying it…

  • Plastik70 from Kontakt Chemie works ok (cover switches, USB and SD card slot with tape before spraying it)

4 - Troubleshooting

Boot issues

When on battery

Brownout protection might be kicking in on boot, try plugging in the micro USB and press the reset button.

With USB plugged in

Try disconnecting the battery to see if that causes the problems. If the badge still does not respond try connecting using a terminal emulator to see what’s going on.

Display

Sluggish

When your display responds sluggish (more than on other badges) or is for instance unable to clear the display in one pass, check the soldering on the display connector first.

Ghosting

When you update the display too frequently without proper clearing cycles (inverted image, black screen, white screen, positive image) you may experience something that looks like it was burned in. You can recover your screen by doing the black and white flashes (LOTS of them). Also letting the display rest (without power!) seems to alleviate the issue. So expect ghosting/burn-in when you are doing animations. We do not know the long term effect of (ab)using the display like this.

Removing

Removing the display is not something we recommend. Break it at your own risk. The trick seems to be to first remove the cable from the connector on the back, pull it through the hole. Now you can carefully push and wiggle the display downward towards the buttons. If you’re lucky the glue-dots havent hardened yet and you can remove the display. Come by the badge tent for new gluedots when you’re done (limited supplies).

Touch input and LED/SD card power control (MPR121)

Touch input is not working

Check the soldering on the MP121. Reflow if necessary.

LED power not working

If your LEDs aren’t getting any power either the MPR121 or the transistor is suspect.

Buzzer motor not working

Either the MPR121 or the transistor are suspect.

Other issues

Please contact us to help you figure things out either online or by visiting us at a camp or event.