Difference between revisions of "Main Page"

From Badge team
Jump to navigation Jump to search
(15 intermediate revisions by 3 users not shown)
Line 1: Line 1:
=Introduction=
+
== TODO Introduction ==
On this page you'll find all the hints, tips, datasheets, secret codes and assorted stuff you'll need to hack the SHA2017 Badge!
+
[[File:Badge Selection.png|frame|right]]
 +
Welcome to badge.team wiki for all info on [https://badge.team badge.team] compatible badges :)
  
=Before the event=
+
=== Badges ===
 +
[[SHA2017Badge]] at [https://sha2017.org/ Still Hacking Anyway] August 2017
  
You can try out some micropython using the [[Projects:Badge/Emulator|Badge Emulator]]
+
[[Disobey2019Badge]] at [https://disobey.fi/ Disobey] January 2019
  
=Getting started!=
+
[[HackerHotel2019Badge]] to be released at [https://hackerhotel.nl/ Hacker Hotel] February 2019
  
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!
+
Your badge? Join us on [http://webchat.freenode.net/?channels=%23badgeteam%2C%23badgeteam-dev&uio=d4 IRC] or [https://t.me/joinchat/AMG-ZhQQ9cE1KAAbQozy5Q Telegram]!
  
Just got your badge and want to get going?
+
== Why badge.team ==
* [[Projects:Badge/Documentation/Assembly|Unpacking and assembling]]
 
* [[Projects:Badge/Documentation/First boot|Booting the badge for the first time and general use]]
 
* [[Projects:Badge/Documentation#Software|Getting the development software on your computer]]
 
* [[Projects:Badge/Documentation/Troubleshooting Hardware|Troubleshooting hardware]]
 
  
=Safe mode=
+
[[LTS|Long-term support]] on event badges [[LTS#aftercare|#aftercare]]
  
If you can no longer boot your badge due to accidental or malicious software on your badge, don't panic. Recent firmware has a Safe Mode, which you can use to uninstall broken or malicious software. Press the Reset button (on the back) while holding the Start button (on the front). Keep holding the Start button while the badge boots up. It should be obvious that it is now in safe mode. Installed software will not be able to start services or execute any code until started from the launcher. The badge will not go to sleep. This will drain the battery, so only use it for as long as you need to in order to remove the problem application. Then press the Reset button once again (without holding the Start button) to return to normal operation.
+
It's sad to see these things become e-waste in no-time.
  
If this doesn't work, you may not have recent enough firmware. In which case, go to the Badge Bar and use our automated reflashing station (which will lose all your applications and settings) and then update to the latest firmware over the air. If you can't get to the Badge Bar or you have left the event already, follow the instructions further down on how to check out the firmware from github and reflash it yourself.
+
== Who are badge.team ==
  
=Hardware=
+
This is not a complete or ordered list, feel free to add yourself if you think you belong to our merry band of badge hackers :)
==Components==
 
*[[Projects:Badge/Documentation/E-Ink]], the DKE Group DEPG0290B1
 
*[[Projects:Badge/Documentation/ESP32]], the Espressif ESP32 Wroom
 
*[[Projects:Badge/Documentation/MPR121]], the MPR121 Touch Sensor and GPIO expander
 
*[[Projects:Badge/Documentation/EyeSore]], the blinky LEDs you can add
 
*[[Projects:Badge/Documentation/Power]], the power management and battery charging
 
*[[Projects:Badge/Documentation/Battery]], the battery
 
* Silicon Labs CP2102 USB2Serial
 
** Requires driver under macOS, found at the [https://www.silabs.com/products/development-tools/software/usb-to-uart-bridge-vcp-drivers Silicon Labs website]
 
  
==Design==
+
* [[User:Sebastius|Sebastian Oort]]
 
+
* [[User:AnneJan|Anne Jan Brouwer]]
==Add-Ons==
+
* Bas van Sisseren
* Screenprotector?
+
* Renze Nikolai
* 3D printable case
+
* Markus Bechtold
* Laser cut case
+
* Jeroen Domburg
 
+
* Niek Blankers
==Expansion Boards==
+
* Tom Clement
[https://github.com/SHA2017-badge/Scarves Repository of scarves]
+
* Arnout Engelen
* Proto-board
+
* Mendel Mobach
* At-least one more project in the works . .
+
* Thomas Roos
{| class="wikitable"
+
* Kliment
|-
 
! colspan="6" | Expansion port
 
|-
 
| GND || LED_POWER || IO_33 || IO_16 || IO_17 || I2C_SCL
 
|-
 
| 3V3_SWITCHED || GND || IO_12 || IO_4 || LED_DATA_OUT || I2C_SDA
 
|}
 
 
 
* USB? https://github.com/SHA2017-badge/PCB/issues/1
 
 
 
==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)
 
 
 
=Software=
 
 
 
Currently we have two flash-able [https://github.com/SHA2017-badge/Firmware Firmware] flavours .  .
 
* Pure C
 
* [[Projects:Badge/MicroPython]] enabled
 
 
 
We also have an [[Projects:Badge/Emulator|Emulator]] to try out some code before you put it on your badge.
 
 
 
== Building ==
 
 
 
TLDR: Clone https://github.com/SHA2017-badge/Firmware and follow the instructions there to flash a new version.
 
 
 
=== Prerequisites ===
 
 
 
You'll need some tooling, on Debian systems this should be sufficient:
 
<nowiki>sudo apt-get install libncurses5-dev flex bison gperf</nowiki>
 
 
 
Cloning and setting up your environment:
 
<nowiki>git clone https://github.com/SHA2017-badge/Firmware.git
 
cd Firmware
 
git submodule update --init --recursive
 
source set_env.sh
 
make defconfig</nowiki>
 
 
 
Optionally change configuration:
 
<nowiki>make menuconfig</nowiki>
 
 
 
=== Compiling and flashing the Pure C Firmware ===
 
<nowiki>make flash</nowiki>
 
 
 
=== Compiling and flashing the Miropython Firmware ===
 
<nowiki>make
 
cd micropython/mpy-cross
 
make
 
cd ../esp32
 
make deploy
 
cd ../..</nowiki>
 
 
 
=== Interacting with the badge ===
 
 
 
You can use your favourite serial terminal client or user the builtin monitor.
 
<nowiki>make monitor</nowiki>
 
 
 
''Close using CTRL + ]''
 
 
 
An alternative is to use screen.
 
<nowiki>screen /dev/ttyUSB0 115200</nowiki>
 
 
 
''Close using CTRL + a :quit''
 
 
 
On MacOS-based systems you might need to install an USB to UART bridge VCP driver from https://www.silabs.com/products/development-tools/software/usb-to-uart-bridge-vcp-drivers first before you can connect to the badge:
 
<nowiki>screen /dev/tty.SLAB_USBtoUART 115200</nowiki>
 
''Close using CTRL + a :quit''
 
 
 
=== Installing on non Debian-based systems ===
 
 
 
For specific issues read the ESP-IDF  [http://esp-idf.readthedocs.io/en/latest/get-started/windows-setup.html Windows Setup Guide] [http://esp-idf.readthedocs.io/en/latest/get-started/macos-setup.html Mac OS Setup Guide] or [http://esp-idf.readthedocs.io/en/latest/get-started/linux-setup.html Linux Setup Guide]
 
 
 
=== Compiling and using the Badge Emulator ===
 
 
 
To use the emulater, you must first build it:
 
<nowiki>cd micropython/unix
 
make</nowiki>
 
 
 
To get an interactive shell:
 
<nowiki>./micropython</nowiki>
 
 
 
To start a .py file:
 
<nowiki>./micropython <filename>.py</nowiki>
 
 
 
=== Using Micropthon ===
 
 
 
Connect to the badge with a micro USB cable and use your favourite serial client, we recommend https://github.com/wendlers/mpfshell. To switch to a 'clean' environment without sleep timers, open the micropython REPL by entering 'repl' on the mpfshell shell and execute 'import shell'.
 
 
 
We have some higher level api's available . . currently a fast moving target 😁
 
 
 
This example code displays some graphics and text.
 
 
 
You can enter the program below, line by line on the serial client.
 
Or you can create a file named '''__init__.py''', and follow the upload instructions below.
 
<nowiki>import badge
 
import ugfx
 
 
 
badge.init()
 
ugfx.init()
 
 
 
ugfx.clear(ugfx.BLACK)
 
 
 
ugfx.thickline(1, 1, 100, 100, ugfx.WHITE, 10, 5)
 
ugfx.box(30, 30, 50, 50, ugfx.WHITE)
 
 
 
ugfx.string(150, 25, "STILL", "Roboto_BlackItalic24", ugfx.WHITE)
 
ugfx.string(130, 50, "Hacking", "PermanentMarker22", ugfx.WHITE)
 
len = ugfx.get_string_width("Hacking", "PermanentMarker22")
 
ugfx.line(130, 72, 144 + len, 72, ugfx.WHITE)
 
ugfx.line(140 + len, 52, 140 + len, 70, ugfx.WHITE)
 
ugfx.string(140, 75, "Anyway", "Roboto_BlackItalic24", ugfx.WHITE)
 
 
 
ugfx.flush()
 
</nowiki>
 
 
 
People are running into problems with ampy, https://github.com/wendlers/mpfshell appears to work better currently.
 
 
 
The tool to upload your file to the badge is [https://github.com/adafruit/ampy Adafruit-Ampy]
 
<nowiki>pip3 install adafruit-ampy</nowiki>
 
 
 
Then execute the following line to run the file on the badge, remembering to first switch to an empty environment with 'import shell'
 
<nowiki>ampy -p /dev/ttyUSB0 run __init__.py</nowiki>
 
 
 
Read more at the [https://wiki.sha2017.org/w/Projects:Badge/MicroPython MicroPython and modules] page.
 
 
 
=== Display ===
 
 
 
To talk to the e-ink display, the high-level [http://api.ugfx.io/ uGFX] library that comes with the firmware is the easiest way to get started. A more low-level API is available under [https://github.com/SHA2017-badge/Firmware/blob/master/components/badge/badge_eink.h components/badge/badge_eink.h] if you need it (e.g. for advanced hacks like greyscale imagery).
 
 
 
=== Creating your first app ===
 
Publishing apps can be done on the hatchery at http://badge.sha2017.org
 
 
 
Your app has to contain a file called "__init__.py". This is the file that is opened whenever someone starts your app from the launcher.
 
 
 
It is possible to use a separate file as your main application by putting "from <APP_NAME> import <FILE_NAME>" where you replace spaces with underscores (_). For example "my awesome program.py" becomes "my_awesome_program".
 
 
 
Should you want to run background tasks while the user is not using the badge you can add a file called "service.py" to your app. More information about services can be found in the next section.
 
 
 
=== Services ===
 
 
 
==== What is a service? ====
 
A service is a small program bundled with an app which allows apps to execute background tasks while the badge shows the splash / home screen.
 
 
 
==== How can I create a service? ====
 
A service is a small program included with an app as a separate Python file, from which a couple of functions are executed. The file should be called “service.py” and it should be bundled with your app files. Please do not put any globally placed code in this file. Instead place you code in functions!
 
 
 
To use services you also need a service descriptor called "service.json". This is an example for such a file:
 
 
 
<code>{
 
  "apiVersion":2,
 
  "wifi": {
 
    "setup":false,
 
    "loop":false
 
  },
 
  "rtc": false,
 
  "loop": true,
 
  "draw": false
 
}
 
</code>
 
 
 
Fields:
 
- apiVersion: always set this to 2, other values will cause badges to ignore your service
 
- wifi(setup/loop): set to true if you only want your service to run whenever wifi is available
 
- rtc: set to true if your app needs the RTC to be configured (set to the correct date/time)
 
- loop: set to true to enable execution of a loop() task (you can also add your own tasks to the scheduler, see the "virtual timers" section
 
- draw: set to true to include your service in the draw loop
 
 
 
==== What does a service script look like? ====
 
Each service script contains three functions: setup, loop and draw. Each of this functions is called by the splash application at different moments.
 
 
 
===== void setup( void ) =====
 
The setup function is called directly after wakeup and is to be used to initialize the service.
 
 
 
===== next loop() =====
 
The loop function of your service is ran as a task in the "virtual timer" scheduler. The return value of this function determines the time until the next time it executes (in milliseconds). The function may be called sooner than the chosen time though.
 
 
 
About sleeping:
 
Please keep in mind that the badge should sleep as much as possible to avoid draining the battery. Any value less than 30000 causes the badge to stay awake. For apps that don't need to stay awake we suggest sleeping at least 5 minutes to allow the background updates to function correctly.
 
 
 
===== [next, height] draw( y, sleep=2 ) =====
 
This function is called just before the screen is updated and allows your service to add information or widgets to the homescreen. The x and y coordinates provided to you are the location of the bottom-left corner of the location designated to your service. You may use the full width of the screen. The return value should be set to the amount of pixels used by your information string or widget. The next widget will be drawn upwards from coordinate (x+height, 0).
 
 
 
Should you decide not to use the location appointed to you then please return 0. Also note that conflicts between multiple services can occur if you place your content at an arbitrary place on the screen. Because of this I suggest you to never do that. Unless of course the purpose of your app is overriding existing elements like the nickname.
 
 
 
The "next" return value should be set to the amount of milliseconds before a redraw is needed. This is at least 1000ms and may in some cases be more than your chosen value.
 
 
 
The sleep argument, if present, must have a default value set. Otherwise it will not work on older firmware. It will be True if this draw is just before going to sleep, or False otherwise. Older firmware does not supply this argument.
 
 
 
=== NVS settings ===
 
{| class="wikitable"
 
! style="font-weight: bold;" | Category
 
! style="font-weight: bold;" | Key
 
! style="font-weight: bold;" | Type
 
! style="font-weight: bold;" | Allowed values
 
! style="font-weight: bold;" | Default value
 
! style="font-weight: bold;" | Description
 
|-
 
| badge
 
| wifi.ssid
 
| String
 
|
 
| SHA2017-insecure
 
| SSID of WiFi network
 
|-
 
| badge
 
| wifi.password
 
| String
 
|
 
|
 
| Password of WiFi network
 
|-
 
| badge
 
| setup.state
 
| u8
 
| 0, 1 and 2
 
| 0
 
| Setup state:
 
0 = Setup not completed
 
1 = Setup completed, show sponsors
 
2 = Setup completed
 
|-
 
| owner
 
| name
 
| String
 
|
 
|
 
| Nickname shown on the splash screen
 
|-
 
| splash
 
| header.invert
 
| u8
 
| 0 and 1
 
| 0
 
| Invert color of header
 
|-
 
| splash
 
| header.hws
 
| u8
 
| 0 and 1
 
| 0
 
| Hide header while sleeping
 
|-
 
| splash
 
| header.hbws
 
| u8
 
| 0 and 1
 
| 0
 
| Hide battery while sleeping
 
|-
 
| splash
 
| sleep.duration
 
| u8
 
| 30 - 255
 
| 60
 
| Duration of deep sleep between wakeups in seconds
 
|-
 
| batt
 
| vmin
 
| u16
 
|
 
| 3500
 
| Battery voltage when empty in mV
 
|-
 
| batt
 
| vmax
 
| u16
 
|
 
| 4100
 
| Battery voltage when full in mV
 
|-
 
| splash
 
| bat.volt.drop
 
| u16
 
|
 
| 5200
 
| Since we are measuring the voltage of the LiPo after a polyfuse, we need to calibrate the battery readings a bit that the splash screen shows. Offsets from 5200 will result in offsets in the splash. This should automatically calibrate when the badge stops charging.
 
|-
 
| splash
 
| ntp.timeout
 
| u8
 
|
 
| 40
 
| Amount of times the badge will try to connect to the WiFi network to set the RTC
 
|-
 
| splash
 
| bpp.count
 
| u8
 
|
 
| 5
 
| Amount of wakeups from deepsleep that will trigger the BPP system to be started
 
|-
 
| splash
 
| timer.interval
 
| u16
 
|
 
| 500
 
| Interval of service loop timer in ms
 
|-
 
| splash
 
| timer.amount
 
| u8
 
|
 
| 10
 
| Amount of times the timer loop will execute before the badge goes back to sleep
 
|-
 
|
 
|
 
|
 
|
 
|
 
|
 
|}
 
 
 
== Links ==
 
 
 
* How to blink a LED with the Arduino IDE on the SHA2017 badge: https://github.com/zoobab/sha2017badge-arduino-blinkled
 

Revision as of 11:10, 9 February 2019

TODO Introduction

Badge Selection.png

Welcome to badge.team wiki for all info on badge.team compatible badges :)

Badges

SHA2017Badge at Still Hacking Anyway August 2017

Disobey2019Badge at Disobey January 2019

HackerHotel2019Badge to be released at Hacker Hotel February 2019

Your badge? Join us on IRC or Telegram!

Why badge.team

Long-term support on event badges #aftercare

It's sad to see these things become e-waste in no-time.

Who are badge.team

This is not a complete or ordered list, feel free to add yourself if you think you belong to our merry band of badge hackers :)

  • Sebastian Oort
  • Anne Jan Brouwer
  • Bas van Sisseren
  • Renze Nikolai
  • Markus Bechtold
  • Jeroen Domburg
  • Niek Blankers
  • Tom Clement
  • Arnout Engelen
  • Mendel Mobach
  • Thomas Roos
  • Kliment