blinking the raspi’s built-in LED

I’ve just added a repository of some JavaScript code to take over and exercise the built-in activity LED on a Raspberry Pi Zero W (and presumably other models). It’s called gpiozero-toggle-led and it’s a pretty simple interface with installation instructions and some sample code. It works with the underlying js-gpiozero JavaScript port of the popular original Python code. This would be an excellent way of simply demonstrating GPIO without any additional wiring, components, breadboards, extra power supplies or electrical knowledge (like finding a 330-ohm resistor using its color bands).

zero-wireless

Note that the “zero” in the title of the repository and in js-gpiozero does not refer to the Raspberry Pi Zero but to the original gpiozero Python library.

This should remove some of the guess work when attempting to use the relatively-new library since their documentation examples at the moment are taking a back seat to their code port from the more-extensive Python offering.

This approach can easily be modified to instead exercise external LEDs (as soldered or otherwise attached to the header pin locations seen below).  Note that you’ll use “BCM numbering” for APIs such as this one. For external LEDs, you would need to connect it inline with a resistor from a selected pin to one of the grounds for this to work with correct orientation of the LED’s anode/cathode, of course.

raspberry-pi-pinout

If you’re trying to use this with a Raspberry Pi of a different model, you’ll likely want to adjust the JavaScript slightly as seen below.

/routes/index.js:

// Existing code, for a Raspberry Pi Zero
var ledActivity = new LED(47, false);
// For Raspberry Pi 3, for example
var ledActivity = new LED(47);

And that’s it. Since the Raspberry Pi Zero assumes an opposite value for true/false than the bigger models, it’s necessary to configure this in the device constructor to make things work as expected. Since BCM pin 47 is the activity light on the board itself, this will allow you to control it.

despicable me—themed supercomputer

I gave a talk on Tuesday to an eager group of 155 attendees at the monthly SanDiego.js meetup on the topic of “Supercomputing in JavaScript”. I had an opportunity to show the new Raspberry Pi 3 supercomputer which I’d built and took it through its paces.

I think they mostly loved the audio events for assembling the minions and sending them to bed (shutting off the remote nodes). There was just enough time to also show the obligatory “Hello, Minions!” demo program to exercise the Message Passing Interface. I received a wide variety of questions and compliments from the group. And of course afterward, everyone who owned a Raspberry Pi came over to discuss their own projects, which was cool.

Here’s the PowerPoint presentation from that talk, in case you’re interested.

e-mc2 repository with step-by-step instructions

server-side tone synth with node

I thought I’d work on another Raspberry Pi 3 project and this time was looking to expand my repertoire for server-side audio.  I suppose I was imagining an application in which you’d carry the Pi along with you using a USB-based power bank and plugging in your headphones, controlling the interface via your cellphone’s browser, let’s say.

Platform

Logically then this would need to be a Node.js—based webserver which could synthesize a sine wave tone with a specified frequency on both left/right audio outputs on the server itself (rather than streaming it back to the client browser).  I chose the Raspian image for the microSD card because, as a Debian modification, it’s likely the closest to the standard Ubuntu flavor of Linux which I work with the most.

Open Source

Searching the npm space I found nothing useful, to be honest. It’s rare when the open source world fails to deliver but this was one of those times. I was going to need to innovate on this one. There are many repositories out there which use the browser’s window object but that just wasn’t available here on the server. I installed module after module only to find that one of its dependencies relied upon that same pesky window object. So each time, I had to perform another npm remove --save whatever from my project to return things back to “square one”.

This research took a little longer than I’d hoped for but it turns out that Raspian out-of-box includes the Open Sound System (OSS) aspi-utils collection and its speaker-test program can be used in a terminal to generate tones from both speakers. Okay, so now how do you run terminal programs from JavaScript?

Starting External Programs From Node

It turns out that Node has an internal module called child_process which allows you to spawn (run) something you might normally invoke from the command line. It took some reading but I was able to navigate the documentation and to start a speaker-test session with the necessary arguments. One task down, (one to go).

Stopping External Programs From Node

Fortunately, Node also has an internal module process with a kill command to stop a running process.

Implementation

It takes a bit of state management: the webserver needs to remember if you’ve started a process, what its process ID is and whether or not you’ve now stopped it. A proper open source project would support systems other than Linux but this is the starting point and this wouldn’t work, say, with a Windows-based computer using the PowerShell module control, for example.

Since this wasn’t an exercise in UX design the interface couldn’t really be any simpler. It’s your basic Express-generated website with the Pug view engine and a simple pull-down list for selecting some preset frequencies. Submitting your tone choice POSTs back to the same index page; selecting the Stop button POSTs to a virtually-routed /stop routine which then redirects back to the original index page.

Source Code

Check it out if you’re curious. I’ll likely be using this same technique to create a more self-contained module for managing external programs.

github.com/OutsourcedGuru/heal

a rose by any other name…

Unfortunately for anyone who uses the express generator for Node.js, the very popular (default) jade template language’s owners are being forced by the threat of lawyers to relinquish the name.

It turns out that JADE happens to also be the trademarked name of a software development system that nobody’s ever heard of before this.  It was created by Jade Software Corp and presumably, they have lawyers whose children need braces and their own Mercedes Benz.

At the time of writing this, the jade Node.js module is hugely popular and had over three million downloads in the last month alone and over 40 million downloads since last year. But since the developer of jade is being forced to change the name that means that everyone who uses it is being forced to change their own projects with the new name. Note that express has been downloaded more than 72 million times and this is a project generator (capable of being run multiple times for multiple projects per coder). It’s staggering to try to quantify in terms of dollars how much labor is about to be wasted on this effort for literally a hundred million projects or more.

“But since the developer [of jade] is being forced to change the name that means that everyone who uses it is being forced to change their own projects with the new name. It’s staggering to try to quantify in terms of dollars how much labor is about to be wasted on this effort for literally a hundred million projects or more.”

The module jade has now been re-introduced as pug… or at least until someone who has trademarked that term doesn’t threaten them with a lawsuit, too.

I think it’s time the open-source community push back. This is ridiculous, to think that owning a trademark can prevent another person from using the term for something as unrelated as this. Conservatively, they’ve just cost the open-source community over US$1B in fixing this name change throughout the collection of projects out there.

hacking agar.io, part 2

This would be the second post in a series. You might want to read the first in the series if you haven’t already done so. Here, I continue with the work related to redirecting the game’s server traffic to my own website so that I can discover the interface.

DNS server

I first install Dnsmasq on my MacBook, add a single entry to its /etc/hosts file to redirect traffic for m.agar.io to my MacBook’s private IP address. Starting up Dnsmasq I then have a DNS server which will redirect game traffic to my own website. Make sure that the program is running by entering ps aux|grep dnsmasq|grep -v grep. You should see an entry for this program.

It’s probably a good idea to test your DNS server to verify that it returns the expected information.

nslookup
> server myip
> m.agar.io.
> exit

After entering the third line above you should see a DNS lookup which returns your server’s private IP address.

Our website

In my ~/sites folder, I run the following command to use Express to generate a generic website: express agar. As is usual for Express, I change into the newly-created agar directory and then run npm install to bring in the dependencies. Since the default installation binds to an upper TCP port and we want the standard port 80 instead, I then edit the bin/www file in this folder and replace the port number 3000 with 80 on a single line.

Note that Node.js, the underlying program that serves up an Express website, will not be able to bind to port 80 since it’s reserved unless I’m running as the root user. If your own user is setup to run the su command then you should be able to start this website with the command su npm start in the agar folder. Otherwise, you’ll have to run just su to become the root user, navigate back into your user folder area to find this folder and then just run npm start instead.

It’s probably a good idea to test the website by bringing up Safari and entering the address http://myip/ (substituting my private IP address) to see if it works.

Configuring the iPad

At this step, I’ll need to tell the iPad’s Wi-Fi configuration to use my own DNS server first and then the existing set of DNS servers next. You’ll find this under Settings -> Wi-Fi -> select the i button next to your own connected Wi-Fi network -> DHCP -> DNS -> prepend your own server’s private IP address and a comma at the beginning of the list.

This is the initial preparation for redirecting the game traffic to your own website. Note that the Node.js website while running will write to its log file and this will be our method of discovering the interface for Agar.io.

Discovery phase

By now attempting to play the Agar.io game on the iPad, it makes requests to what it thinks is the server. Only these requests are now being sent to my website instead. As each attempt is logged as a failure on my own website, I then make this call manually in another computer to the actual Agar.io website to see what it’s supposed to return.

For example, the game makes a request to the game server’s interface with just /info as the URL.

/info returns:

{"regions":{
  "CN-China":{"avgPlayersPerServer":368.5,"avgPlayersPerRealm":147.4,"numPlayers":737,"numServers":5,"numRealms":5},
  "US-Atlanta":{"avgPlayersPerServer":445.1034482758621,"avgPlayersPerRealm":203.2755905511811,"numPlayers":25816,"numServers":267,"numRealms":127},
  "EU-London":{"avgPlayersPerServer":430.6,"avgPlayersPerRealm":191.37777777777777,"numPlayers":8612,"numServers":179,"numRealms":45},
  "SG-Singapore":{"avgPlayersPerServer":546.0,"avgPlayersPerRealm":136.5,"numPlayers":1092,"numServers":9,"numRealms":8},
  "Unknown":{"numPlayers":0,"numServers":0,"numRealms":0},
  "BR-Brazil":{"avgPlayersPerServer":333.3220338983051,"avgPlayersPerRealm":200.6734693877551,"numPlayers":19666,"numServers":181,"numRealms":98},
  "RU-Russia":{"avgPlayersPerServer":473.25,"avgPlayersPerRealm":145.6153846153846,"numPlayers":1893,"numServers":45,"numRealms":13},
  "JP-Tokyo":{"avgPlayersPerServer":460.0,"avgPlayersPerRealm":172.5,"numPlayers":1380,"numServers":8,"numRealms":8},
  "TK-Turkey":{"avgPlayersPerServer":287.14285714285717,"avgPlayersPerRealm":154.6153846153846,"numPlayers":2010,"numServers":30,"numRealms":13}
  },
  "totals":{"numPlayers":61206,"numServers":724,"numEnabledServers":317,"numRealms":317}
}

As you can see, this is a fair bit of information. The format is known as json in case it’s not familiar to you. As of my writing this, there appear to be over 61,000 players in the game right now and well over 700 servers with almost half of those enabled. So this would be why it’s difficult to get a simultaneous FFA game with your friends—the odds are against you.

Without further ado, here are the other queries which I discovered.

/ returns:

37.187.171.110:1523
8QJP8

This appears to be your issued server and port on the first line and what is likely its instance alias from whichever cloud-based company they’re using.

/getLatestID returns:

131

I know, not very impressive. But it appears to be the highest user ID for your issued server.

/findServer returns:

{"ip":"151.80.98.52:1516","token":"86JYH"}

Another json response, this appears to also be issuing you a server and port. It’s possible that the first home query is asked at the beginning of the game and then /findServer is called each time your die in the game.

So far, this appears to be everything I’ve learned from this redirection technique.

Status

At this point, I now have the game interface which the Agar.io app uses to communicate with the server. It likely makes more requests but that’s good for now. I could have enough to go on in order to work up something so that multiple iOS people could join the same FFA game, for example, since we know this issuing mechanism.

hacking agar.io

In an earlier post I described an addictive game called Agar.io, an interactive eat-or-be-eaten game involving graphical dots. In this series of posts, I’ll be attempting to hack the game to see what I can get away with.

Agar-top

Define:  hacking

I suppose there are several ways of interpreting the term hack here. In the movies, some character will “hack the mainframe” or some other nonsense. And we’re also familiar with someone who attempts to use techniques to hack a website, perhaps injecting SQL code into an innocent-looking HTML form. Here, I refer to one of the original uses of the word, to hack away at a problem until it is solved. I’m interested in the game itself, how it talks to the server and I’d like to go to school on their efforts. As a coder of smartphones myself I’d call that part of the learning curve.

Goals

Ultimately, I would like to learn how the game works behind-the-scenes. I do have some secondary goals though. It would be interesting to see if it is in fact possible to edit an existing iOS app and have it still work and all without the original coder’s digital certificate. If successful, I think the first order of business would be to remove the ads you might see during game play. Another personal goal would be to allow multiple friends on iOS devices to play the FFA (free-for-all) mode of the game with each other; this could be made possible with a proxy server, I’d propose.

The platform

Currently, I play the Agar.io game on an iPad II since I prefer the interface over a browser-based version that’s available. So I will be attempting to hack the Apple store app ultimately.

This may turn out to be impossible since an app that runs on iOS is supposed to be digitally signed to prevent tampering. And yet this is what I intend to do, nonetheless. I’ll be testing that assertion to see if a hacked app will still work.

Concepts

Here, I’ll discuss some of the concepts of the approaches I’ll take.

  • Patching:  Patching is an old-school technique in which binary code, for example, is edited in place with a script. Individual characters or code is replaced in the original to create a new file. The patch program itself works together with another program called diff, used to calculate the differences between two files.
  • DNS:  This service is responsible for looking up a name like m.agar.io and replacing it with an IP address.
  • Redirection:  Using your own DNS server so that you can redirect requests to your own website instead of the intended one.
  • iOS app:  An iOS app might seem a little daunting if you’re not a coder. It’s actually a collection or manifest of files all rolled up into one .ipa file. I think it’s safe to say that the app was written in Apple’s Xcode using a computer language like Objective-C or Swift.
  • Ad-based add-ons:  It’s clear that Agar.io has many opportunities to display ads within the game itself. The programming interface to these (for the Agar.io developer) is almost always JavaScript-based.
  • Tethering:  Connecting a smartphone—or the iPad in this case—to a computer to allow for interaction (like development testing) to occur.

Throughout this series of posts keep in mind that if I’m indicating a command, it’s often being done on a MacBook with OS X 10.11.5 El Capitan at a shell prompt. Otherwise, I could be referring to something I’m doing on an iPad II with iOS 9.3.2 installed.

DNS server

I’ll be using the Dnsmasq easy-to-implement DNS server for redirecting Agar.io’s server requests to my own website. I’ll then configure my iPad to use this server first when doing DNS lookups.

Discovery website

And since I’m familiar with Node.js and Express I’ll be using this to mockup a website for those redirected app requests. When the iPad makes a request to what it thinks is the Agar.io website, I will see that request in my website’s logs.

This could be technically called a man-in-the-middle technique since I could then have my own website forward the request to Agar.io’s actual server and then answer the iPad with that response, adjusting it if I wanted to. I guess technically you could also call this a proxy approach.

Binary editor

I’ll likely also use Hex Fiend at least minimally to find the location within the main program app where I’ll be patching the code.

Installing a modified app

Normally, you would download an app directly to our iPad straight from the Apple iTunes store. Technically, I suppose, I could have taken advantage of the redirection concept from before to steer the iPad to my own website to deliver the edited content but it’s not that difficult. There appears to be a mechanism so that you can download iOS applications on an OS X computer and then, while tethered, install them remotely using iTunes. This actually allows us to use a MacBook in this case to snag the code package itself and to start all the fun. We’ll be taking advantage of this in order to then try to push a modified app package to the iPad.

If you’re on a standard OS X computer and you get the Agar.io app, it won’t seemingly do anything after the download; you’re not presented with the usual Open button after it has downloaded. It does, however, get silently copied to your hard drive under your user folder in /Users/username/Music/iTunes/iTunes Media/Mobile Applications. Having downloaded it, you should find a file called Agar.io 1.3.0.ipa which is the app (collection) itself.

Expanding the app

From here, you might not know that an .ipa file is little more than a .zip file. I’d suggest copying the Agar.io app file somewhere else (like creating a folder called AgarIO) and then open a shell so that you can decompress it.

MacBook:AgarIO$ unzip "Agar.io 1.3.0.ipa"

This command then will decompress the collection of files for you.

What’s inside the .ipa file

There are a lot of files inside this package, just like you’d find with most store apps. The first I’ll discuss is iTunesMetadata.plist which is perhaps the most aggravating of all. A .plist file is like a database for a coder, it usually stores configuration options. Opening it with TextEdit then shows me that this is the file responsible for knowing who downloaded it (myself) and how I’m then authorized to use it. I’m sure there’s a similar mechanism inside any music file you download from iTunes to prevent you from playing it on an unauthorized device. So in other words, I couldn’t just patch the Agar.io application and then make it available for download for others. Each person interested in this would need to go through the motions themselves.

Next, there is a META-INF folder which contains two files. I haven’t fully investigated them yet but the first is com.apple.FixedZipMetadata.bin which appears to again be a compressed collection of files. And the second is com.apple.ZipMetadata.plist. It appears to have some indication of how the actual program was zipped up into an .ipa file.

The final folder is Payload which includes what appears to be a single file, Agar.io. Or, is it a single file? Knowing what I do about making iOS apps, it’s actually another compressed file. In Finder, you’ll want to rename this Agar.io file to Agar.zip, for example. Back in your shell, then unzip it as you did before to expand its contents.

What’s inside the Payload file

So now we’re getting down to the actual programming itself. Everything we have seen up until now is just a wrapper so that iTunes and Apple can provision an app to you and just your device(s).

Surprisingly, there are a total of 1,111 .png graphic files inside. Most seem to represent the many skins that you’ll see in the game. There are 153 .plist files which are used to store anything from advertisement configuration information, to promotions, to language localization information and collections of available skins by category. With respect to my goals, I’m not really interested in these. And there is a single .db file for the Vundle advertising platform.

There is a folder called _CodeSignature which appears to include hashes of the collection of graphics, presumably to prevent them from being edited perhaps.

There are 65 .ccbi files which appear to be another form of .plist files. There are 15 .json files which appear to have different localized versions.

Finally, there is agar.io which is the actual program file itself. I’ll save the actual editing for a follow-up post to this one.

Status

That’s a good start so far. We’ve downloaded the Agar.io app and performed two decompression steps to get at the actual executable itself. Next, I think I’ll switch gears and build the discovery website and DNS server so that I can get at the app’s server interface.

Update

Skip to the final post in this six-part series if you’re looking for the code. Enjoy!