This years annual hacker security conference known as DEFCON used a couple of NXP devices for this years electronic badge. This document is to explain how to program the device and add extra components. The badge was developed by Grand Idea Studio, with engineering help from NXP, and this presentation has details about the development of the badge. I'm the NXP systems engineer that was helping people get started with reprogramming their badge at Defcon, and wanted to create something that gives all the details on how to do that yourself.
Full schematics and firmware source code can be found at: http://www.grandideastudio.com/defcon-27-badge/
The badge has these two NXP devices:
- KL27 - MKL27Z64VDA4 - 48Mhz ARM Cortex M0+ microcontroller w/ 64KB flash (Datasheet and Reference Manual)
- NXH2261UK- Near Field Magnetic Induction (NFMI) chip for the wireless communication. Has a range on the badge of about 6 inches (15cm), but the technology can work a bit further. It's often found in high end headphones because BLE waves are disrupted by your head but these waves aren't. Also less power consumption.
Using the serial port:
There's a serial interface which prints out helpful information and there's some "secrets" available if you have a completely leveled up badge. It'll also be really helpful if you're writing new code to hack your badge for printf debugging. Note that you cannot program the board by default over the serial port. This particular chip doesn't support that, though some of our other chips do. It of course would be possible to write a serial bootloader for it, but that's definitely not beginner level.
You'll need two pieces of hardware:
1) Header Pins
3) Serial-to-USB converter
Header Pin:
You can solder on a header to the PCB footprint. Because of the quartz, the leads would need to be flat on the PCB. A Harwin M20-8770442 will fit the footprint and is what was provided at the soldering village and what you see in the photos below. You could also try creating your own header.
Serial to USB Converter:
Since almost no computer today comes with a serial port, a serial to USB converter dongle is needed. It'll have four pins: GND, Power, TX, and RX.
The DEFCON badge runs at 1.8V, but the chip itself is rated up to 3.6V, so a 3.3V dongle can be used *as long as you do not connect the power pin on the serial header*. You only need to connect GND, RX, and TX. In a production design you would not want an IO voltage above VCC, but for hacking purposes it'll work, and I've used it all week without an issue on multiple boards.
There's a lot of options. Here's a 1.8V one if you want to be extra cautious or a 3.3V one that already comes with connectors for $8. Anything that transmits at 1.8V or 3.3V will work so you may already have one, but again, just don't connect the power pin.
Software:
You'll need to install a serial terminal program like TeraTerm or Putty.
1) Plug the 3.3V or 1.8V USB converter dongle into your computer and it should enumerate as a COM port.
2) Connect the GND line on the dongle to GND on the header
3) Connect the TX pin on the dongle to the RX pin on the header
4) Connect the RX pin on the dongle to the TX pin on the header (it is not RX to RX, I spent 2 whole days tearing my hair out over that during my robotics project in college)
5) DO NOT CONNECT THE POWER PIN
5) Should look like the following when finished
6) In your serial terminal program, connect to the COM port your dongle enumerated as
7) Find the serial port settings menu (in TeraTerm it's in Setup->Serial Port from the menu bar) , and set the baud rate to 115200. The other settings should not need to be changed (8 data bits, no parity, 1 stop bit).
8) In the terminal, press enter. You should get a > prompt
9) In the terminal, press the '?' key on your keyboard, and hit enter, you'll see the menu.
10) Note that the key you press won't show up in the terminal, but just press Enter and then the command will be run
11) Hit Ctrl+x to exit interactive mode and turn back on the radio.
12) While not in interactive mode, the terminal will display the transmit packet of any badge you bring close to it.
Reprogramming Your Badge:
Hardware:
There's two pieces of hardware needed:
1) Programmer/debugger
2) Programming cable
Program Debugger:
Most any ARM Cortex M debug programmer can be used, as the KL27 chip has a ARM M0+ core. I'd recommend the LPC-Link2 as it's only $20 and can be bought directly from NXP or from most distributors (like Mouser or DIgikey). Search for "OM13054". But you could also use a J-Link, PEMicro, or others if you already have an ARM programmer.
Cable:
The DEFCON badge has the footprint for a Tag Connect TC2050-IDC-NL-050-ALL. Because this cable is meant for manufacture programming and not day-to-day debugging, if you plan on stepping through code, you'll also want to pop off the the quartz front and get some retainer clips to keep the programmer connected to the board.
If you just simply want to reprogram the board, you can just snip off the 3 long guide clips, and press the cable against the PCB while holding your hand steady for the ~5 seconds it takes to flash it each time.
Alternatively if you already have a JTAG/SWD cable and have soldering skills, you can use some fine gauge wire and hack up your own converter to your board like /u/videlen did with some true hacker soldering. However as /u/int23h pointed out, because it's using Single Wire Debug (SWD) you only need to really solder 2 of the pins, SWDIO and SWDCLK. However nRESET is also recommended as it'll let you take control of the device if it's in sleep mode (which it is most of the time). Power (which is needed so the programmer knows what voltage to send the signals at) and GND you can get from the serial header.
Software
There's three pieces of software you'll need:
1) Compiler
2) MCUXpresso SDK for the KL27
3) Badge source code
Compiler:
- Recommended Option: Latest version of MCUXpresso IDE - available for Windows, Mac, and Linux
- Second Option: Download older version of MCUXpresso IDE for Windows from the DEFCON media server
- Third Option: If you use the latest SDK, you can easily use ARM-GCC, IAR, or Keil tool chains as well.
MCUXpresso SDK:
- Recommend Option: Download latest SDK version for KL27 - includes setup for MCUXpresso IDE, ARM-GCC, IAR, and Keil compilers
- Other option: Download the older 2.4.2 SDK version on the DEFCON server which only has MCUXpresso IDE compiler support.
Badge Source:
- Recommended Option: Download zip off Joe Grand Website: http://www.grandideastudio.com/wp-content/uploads/dc27_bdg_source.zip
- Other option: Download from DEFCON media server. However the .project and .cproject files do not show up by default, so you must make sure to explicitly download them as well and put them in the main firmware folder (at the same level as the .mex file). These are the exact same files as in the zip.
Getting Started with MCUXpresso IDE:
1) Open up MCUXpresso IDE. When it asks for a workspace directory to use, select (or make) a new empty directory that is in a different location than where you downloaded the firmware source.
2) Drag and drop the SDK .zip file from your file system into the MCUXpresso IDE "Installed SDKs" window. This is how the compiler learns about the KL27 device and the flash algorithms.
3) Drag and drop the badge firmware folder from a file explorer window into the MCUXpresso IDE "Project Explorer" window
4) In the Quickstart panel hit Build
5) In the Console tab, you should see the message that it compiled successfully
7) In the Quickstart panel hit Debug. If you're not using a LPC Link2 for programming, you'll need to hold Shift when clicking this the first time so it'll rescan for your debugger. If using the latest MCUXpresso IDE, you'll see a dialog box that the launch configuration needs to be updated. Click on "Yes".
7) A dialog box will come up confirming your debug probe.
8) Connect the programming cable to the board and press to make a good connection. Make sure the alignment pins match up with the alignment holes on the PCB, and that pin 1 (the red stripe) matches the photo below. You may hear the badge beep, as it's being reset.
9) Then hit OK in the dialog box to start programming. Make sure to keep the probe held there until the programming is finished - about 5 seconds.
10) You should see it program successfully and hear the board beep as it reboots.
Programming Troubleshooting/Tips:
If you're not using a LPC Link2, hold down the Shift key when you hit the Debug button, and it'll re-search for new probes. Also make sure your debug settings and probe is using SWD mode and not JTAG mode.
If you have the programming cable not lined up with the pads, you'll see this error. Re-align your probe and try again. Also you must have power from the battery as the MCU needs to be turned on while programming.
You can hit the GUI flash programmer at the top for a quicker download experience since it won't load the debug view. Useful if just flashing the device without wanting to step through code.
Finally, some of the game state variables are stored in the non-volitale internal flash, and may not automatically get erased when reprogramming the firmware as the programmer doesn't realize that area of flash memory is being used and thus to save time, doesn't bother to erase it. You can force a complete erase of the flash to wipe all the game variables by setting the mass erase option. Double click on the dc27_badge LinkServer Debug.launch file which contains the debug settings, and go to GUI Flash Tool->Program and set Program (mass erase first).
Getting Started with ARM-GCC:
To make this easier, you'll need to download the latest SDK from the NXP website first.
Follow the instructions in Section 6 of the MCUXpresso SDK User Guide for how to setup the environment and test it out on Hello World. You can then use that project for copying the badge source code into. I'm sure someone can put together a Makefile for the badge specifically.
See this series of blog posts on how to use the SDK (compiling/debugging) with arm-gcc in Linux.
My badge isn't working:
First thing to try is power cycling the badge by gently prying the battery out (with a butter knife or something) and putting it back in. A couple of things might happen:
- If nothing at all happens, you battery might be dead. Try replacing the battery.
- If nothing at all happens still, the battery holder might be loose. Use a multimeter ot measure the voltage between GND and VCC on the serial header, it should read 1.8V. If it does not, check the battery holder.
- If you hear beeps, all 6 LEDs light up, and then 4 LEDs (2 on each side) flash in sync a few times, it means there was an issue communicating with the NFMI device. This could be due to a loose solder joint on one of the chips or the I2C pull up resistors (SCL and SDA on the pinout image). You could also do a reflow if you have the equipment, but it may not be fixable. Also could see if see any I2C communication on those SCL/SDA pins.
- If you hear a normal startup beep, the lights flash, and then it goes back to the startup beep, and so on, forever, something is causing the MCU to keep resetting. Could be a short or ESD damage. Check soldering. Connecting your board to a serial terminal and see how far it gets in the boot process to help narrow down the cause.
- Sometimes the flags don't get saved properly. A power cycle usually works, and could also try reflashing the badge.
- If your badge isn't responding to other badges with the NFMI, it could be one of two things:
- Your copper antenna is loose/broken/missing. This happened a lot. Solder it back on. If missing, it's a Sunlord MTNF6040FS3R7JTFY01 but it's not available online anywhere at the moment. Datasheet is here. See this post for more details on possible alternatives.
- If you were previously in interactive mode, you have to explicitly exit it with Ctrl+X to receive packets again.
Further hacking:
For basic hacking of the code, try changing your game flags to trick it to giving you a fully unlocked badge. From there, you could try to make your own chameleon badge like others have done (https://github.com/japd06/defcon27_badge and https://github.com/nkaminski/DC27-badge-CFW and https://github.com/NickEngmann/Jackp0t among others if you want ideas). Or make your own songs with the piezo. Or some ASCII art on the terminal.
For more advanced hacking on the badge, PTE22 and PTE23, the TX and RX pins on the serial header, could be programmed to be ADC input pins instead. Or timer inputs or outputs for PWM or input capture.
And with some good soldering, you could even add an additional I2C device by soldering to the resistor points. t.
Finally if you want a more flexible platform for exploring embedded development, you can pick up a FRDM-KL27Z dev kit for $20 which has the same chip as the badge. You can buy it direct or all major distributors online. The programmer and serial interface are built into the board so you only need to use a USB cable to do all the programming. The KL27 SDK also includes dozens of example programs that show how to use all the features of the chip and there's some getting started videos (mostly what I covered already in this post though). While it does not have a NFMI chip on it, it does have USB support, as well as an Arduino hardware footprint on it so it can be easily expanded with extra boards. You can find the example programs by going to "Import SDK examples" from the Quickstart panel window.
If you have any more questions about the badge, post a response!
MCUXpresso IDE 11 includes a serial terminal function now, so you dont even need to download PuTTY or Teraterm :smileyhappy:
In the default layout its grouped with the Installed SDKs, Console, etc:
Click on the terminal icon (highlighted yellow below) then select Serial Terminal:
et voila!
