MAGFest Swadges

ESP8266 Firmware for the MAGFest 2017 swadges. See more at http://magbadge.me/

We hope to some day make them badges, but until we get the proper approvals, they will stay the swadges they are.

General Features

The swadges (swag-badges) are wifi-interconnected human-interface battery-operated devices. They've got lights, buttons and all check in to our server whenever they can find a MAGFest wifi connection. This means we can monitor your swadge's health, what wifi connections are around it, button presses and send it colors. If you go to a main stage concert, the swadges will be controlled in unison by the light show maestro. The rest swadge's features will be unlocked over the course of the fest. Come to the "Get to know your wifi swadge panel" to learn more about your swadge, games that are upcoming and available --- and to hear the back story of how these devices came to be.

By the way! If it is too far from the main wifi networks, all lights turn dim red and it goes to sleep for a while so you don't need to pull the batteries out overnight. Also, you can hold the LEFT button while powering it on, it turns into a flashlight. If you're inclined to tinkering, the badges have a 'development' mode built in, but you'll have to go to the forge or the swadge panel to learn more.

Startup Button Features

Remove power, press button, apply power. This can be done by pressing the button you want to select, and popping a battery down on its spring in the back. This will cause the ESP to reboot and the button to be detected on startup. You can easily reboot the ESP by bumping the battery to one side to make it disconnect and reconnect.

Right = Enter serial programming mode on startup where you can use the 4-pin connector to load new firmware on the badge.
Left = Turn magbadge into magtorch. Disables all wifi functionality.
Up or Start = Disable deep sleep. This will cause the badge to still work in concerts even if there is a failure of the infrastructure.
Select = Make badge enter AP mode (Will be called "MAGBADGE") where you can connect to it and use it as a rudimentry development platform. If you wanna do some hacking!

Protocol

All communication is performed either by raw 802.11n packet access and/or once connected to a network, UDP packets. Packets by default are sent specifically to 10.201.0.10, port 8000. If there are specifically solicited packets, they will return from whence they came, so you do not need to be 10.201.0.10. Under normal circumstances, though, the badge only connects to this server.

Status updates are sent to the server, responded to and/or 802.11n broadcasted whenever:

Badge connects to network
Every 10 seconds
Upon request (Send badge a 0x01 message)
Every time a user clicks a button.

	//PROTOCOL:
	//Bytes [0..5 MAC] ->
	// MAC from the server is ignored.
	//Starting at byte 6.

	//packets are sent to 10.201.0.2, UDP port 8000
	//Packets can come from anywhere.
	//Packets send packets to device on port 8001

	//Badge Status Update, sent at connect, after 10 seconds, upon request and button click.
	//  TO BADGE 0x11: Request status update.
	//  FROM BADGE 0x01: [Version] [RSSI] [BSSID of currently connected AP x6] [GPIO State] [Last button event, 0 if no events, 1-8 for button] [was last button event down] [Average LED power] [system 3.3v 2bytes] [status update count 2bytes] [heap free 2bytes] [sleep performance ratio] [0, reserved] [current time 4bytes]
	//  NOTE: On badge code
	//  Version 0: What is in packet.
	//  Version 3: MAGStock 2018: Average LED power is # of leds; Code 0x13 is allowed.


	//Control WS2812Bs on badge.
	//    TO BADGE 0x02: [MAtch] [Mask] [Reserved, 0]   [GRB GRB GRB GRB ...]  NOTE: For raw packets, only 4 LEDs may be controlled.
	//		if (! ((mymac[5] ^ data[7])&data[8]) )

	//Glow LED to porportion of RSSI
	//    TO BADGE 0x03: [min RSSI] [max RSSI] [LED intensity]

	//Initiate SSID SCAN
	//    TO BADGE 0x04: (no parameters, ONLY UDP can control this!)
	//  FROM BADGE 0x05: [scan_timestamp (4 bytes)] [stations count in this message] [ [BSSIDx6bytes] [RSSI] [Channel] ]

	//Rainbow effect
	//    TO BADGE 0x07: [Reserved, 0] [Reserved, 0] [Reserved, 0] [Run time, MSB] [Run Time, LSB] [rainbow speed] [rainbow intensity] [rainbow offset per led]    Run time in ms.

	//Device configure
	//    TO BADGE 0x08: [requested update 1/0] [disable_push 1/0] [disable raw broadcast 1/0] [raw broadcast rate, recommended 0x1a]

	//Force deep sleep (UDP only)
	//    TO PADGE 0x09: [sleep ms MSB (4 bytes)] [0xaa, must be 0xaa]
	
	//Read LEDs
	//	To swadge: 0x13
	//	From Swadge: 0x14 [number of leds] [led data]

Pinouts

The 4-pin programming header pinout is pin 1 (Bottom) up: GND / RX / TX / VCC. When programming do not connect batteries and VCC at the same time.

To enter programming mode, press and hold right, and remove and reapply power. This can be easily done by popping the battery to the side.

The GPIO buttons are:

Bit 0: RIGHT = GPIO0
Bit 1: DOWN = GPIO2
Bit 2: LEFT = GPIO12
Bit 3: UP = GPIO13
Bit 4: SELECT = GPIO14
Bit 5: START = GPIO15
Bit 6: B = GPIO4
Bit 7: A = GPIO5

Building Source

This project is based heavily on esp82xx. Please read its general build instructions at https://github.com/cnlohr/esp82xx .

cnlohr / swadges2017