Python

REST Easy – An Edison Project

This post represents the end (for now) of my series on the Intel Edison board (part 1 and part 2) wherein I describe my latest project. This was an app designed partially for use in my apartment, partially as a trial in programming for such a small device (storage and power-wise). In the end, I managed to squeeze out a minimum viable product with lots of room for growth. There was definitely a need for scaling back initially, however, since the grand design for the project would have overflowed the memory just on install. After swapping some tools for their smaller counterparts, trading uglier code for less space, and dropping of some top level design characteristics, the app was able to build and run on an Edison in almost any storage state, allowing this app to run quietly alongside whatever other tools you have decided to use on your Edison board.

What’s it Do?

For once, I have a project which needs no complicated justification for its use. This app deploys a very simple REST API (get the name now?) which can manipulate the many GPIO pins which make this device a real player in the Internet of Things. Without any need for understanding APIs, no knowledge of javascript, and very little need for understanding linux at all, this makes it possible to manipulate your Edison’s pins from anywhere with an internet connection.  The idea is simple. The Edison has a built in wifi adapter, and using that combined with DHCP reservations can give the Edison a permanent local IP address. Port forwarding port 3000 (the REST API port) to that address allows you to send commands through your router to the wireless device from anywhere in the world. Sure, you could ssh in and manually manipulate each pin from anywhere already. What this api REALLY leads to is extension. When you can reduce a series of complicated ssh commands to the press of a button, that’s progress. With REST Easy, the button need only send an http request to the API, and all changes will propagate.

How?

Very, very simplistically. The app is essentially a prebuilt nodejs application, which self installs and runs with the app’s own install script. Beyond that, the only other trick is a library of very simple python scripts which use JSON to communicate data between the linux representation of the GPIO pins and the API. These scripts are really aggregate read/writers of all the status files associated with each pin.

I have no idea who thought this was a good way to handle GPIO

This is a simple view of the file structure for each pin

 

When the request for the status of a pin is received, the script grabs the information about every aspect of that pin from the file system (/sys/class/gpio/gpio<pin#>/[direction, edge, value, etc.]) and compiles it to a JSON object which can be easily sent back over the API. The reverse is also true. When a POST command is sent to the API with a JSON object (or array) the python script will break down the object and set each field to the value in the received data.  The JSON object for each pin looks like this:

{
 "ID": 130,
 "active_low": 1,
 "direction": "out",
 "edge": "none",
 "value": 0,
 "power": {
     "async": "disabled",
     "control": "auto",
     "runtime_enabled": "disabled",
     "runtime_status": "unsupported",
     "runtime_active_kids": 0,
     "runtime_active_time": 0,
     "runtime_suspended_time": 0,
     "runtime_usage": 0
     }
}

This should be pretty easy to understand, even with no prior experience with JSON. The words before the colons are the keys or variables, and those after are the values. The format is actually how javascript saves objects in flat files, hence the name JavaScript Object Notation. This makes it doubly useful in a javascript based API, since upon the receipt of a JSON payload, the data is immediately converted into an object. This can be manipulated and altered using standard OO operations including dot notation, rather than messing with string manipulation and regexes.

What’s Left

By this point you should be expecting that this project has not fully realized its potential (how many projects ever do?).  There are several features on my list which will hopefully be added in the near future, and many which I plan to leave out until needed unless some willing soul wants to contribute. Some of my planned features:

  • API Keys/Auth
    • The app comes with a SQLite database and authentication system (endpoints /users and /login) but as of yet, they are not used for anything. The plan is to require a login every so often to release an API key. This would limit your board from attack by anyone who knows your IP.
  • Aliases
    • While the pins are currently accessed by passing their linux ID number, it would be even better to be able to assign an alias to a pin and use that to access the pin’s state.
  • Groups
    • Many processes using GPIO rely on the simultaneous change of more than one pin in order to change a multiplexer input or some other multi-bit operation. The app does not currently support the simultaneous changing of pins, however multiple pins can be accessed in the same request via passing an array of ID’s or JSON objects for GET and POST respectively.

I have no intention right now of working on a front end to this application. That task along with any other features not in the above list are up to you, the user. This code is 100% open source, and available in the usual spot on my github. Feel free to alter, use, adapt and destroy any of it to suit your needs. The install process is rather simple:

  1. Download the source code and package all but the “installer” directory into a tar.gz archive (this will be done for you when a release medium is linked).
  2. Send the installer folder and tar.gz package to your edison.
  3. SSH in and run the shell script included in the installer folder.
  4. assuming your Edison is already set up for wifi, you should be able to access the global GET endpoint at: <Edison’s IP>:3000/api/pins

Go forth and do wonderful things with this. If you use it for something cool, I only ask you mention me in the documentation, and of course share a link to what you’ve built so I can admire your work! Next week I will be writing up a very short summary of some project currently on my plate, so stay tuned!

Advertisements

Woodbuntu’s Monitoring Software

Given that my recently created (and blogged about) home theater PC is functionally a piece of furniture, the last thing we need is to be constantly checking on it. Rather, the machine should manage itself, and notify us (the users) when updates or intervention is needed.  As such I played around with my favorite scripting language to make some monitoring tools.

Python!

Using a very very very simple python script, I am able to read in a file and send the contents to a list of recipients. Once that was built, we needed a way to create the file for each email including html formatting. Another simple python script which reads in updates lists and status files to create an html file which can then be sent by the original tool.  The last step was automating the process. A few bash scripts placed in the automatically called locations (init.d, cron) can consolidate the necessary information to a file which can be passed through the python scripts.

actual received email

I should log on and update the end tale!

The result is a daily email or two (perhaps I will consolidate the daily emails in to one soon!) alerting us of any power-cycles, updates, or necessary changes needed.    There is support for a few extra features which I have not implemented yet, but will soon (read: eventually).  These tools can be used for many things I have not thought of I’m sure, so I made them highly generic. The builder can accept any type flags you want to define, so its behavior can be expanded without limit. The sender can send any file desired with a customizable subject in the command line. Both tools are written fairly clearly in the hopes of use for new and different things to suit each need.  The code is available in the usual spot here and is intended for linux systems.  I must clarify that these tools have only been tested on the end table PC, so excuse any compatibility errors.

To install, simply download the repository, edit the sender with the To, From, and Auth fields of your choosing, then run the install.sh as root.

Hope you get some use out of this tool, and as always, raise a glass and code on.

Blast from the past, My first coding project

I’m going to be honest here, I’m updating for the poor HR representatives that have to look at this blog for research after reading my resume at the GT career fair. In order to give some personality to this mysterious author who’s thoughts you read so diligently, I have decided to write about my first real coding project!A little background, when I graduated high school, I KNEW I wanted to do Aerospace Engineering. Until orientation at GT (we call it FASET) at which point I decided I KNEW I wanted to do BioChemistry. I believed that new path was the one for me until I took a wonderful class in Computer Science. At that point, I was sure that I had been hasty before, so I waited an entire semester before realizing that this time I REALLY KNEW. So what magical class was so powerful as to make me change majors again and stick with it?

It was Jython

For the uninitiated, Jython is a special blend of the programming language “Python” and some common java libraries. This allows beginner programmers (like myself at the time) to create very clean object-oriented python code in a neat IDE with a console,  and makes visual animations easy.

Jython code in the JES IDE

Jython code in the JES IDE

Jython was my first experience in coding, and it saw my first “Hello World” program, very basic number programming, image manipulations, and eventually animations.  The final project of this class used a unique aspect of Jython called “Turtles”.  You see, in the parallel version of this class which was required for CS majors, the end of the class involved controlling small robots with attached pens around in a pattern. These robots were called ScribblerBots, but they were relatively expensive. Instead, our class made use of the visual libraries provided by java to create small turtles in a picture. The turtles could then be commanded just like the robots, moving and drawing lines, but they could also be used for animation.  By using an array of turtles, each with a certain job, the turtles could change the background to create animation, they could change colors to act as an animated object themselves, or they could drop images on to the screen to create new visual objects.

Our Final Assignment

We were expected to use everything we learned throughout the year to create an animation which satisfied several requirements. As best I can remember them, the minimum  requirements were:

  • Use at least 4 different turtles on the screen at the same time
  • Make at least one turtle change color and size
  • Make a turtle draw, move, stop drawing, and move again
  • Use a randomizer to change at least one attribute of one turtle.  (I went a little crazy on this one)

Beyond those requirements, the assignment was very free form, and we were encouraged to be creative. I took it to heart.

What Horror Hath I Wrought?

Screenshot of the animation

Screenshot of the animation

Pokémon. Registered copyright or trademark or whatever, but let’s be real, it was Pokémon. My goal was to recreate a Pokémon trainer encounter and subsequent battle. For those that have a JES environment (get it here) you can download my code and watch it with full randomness at the usual place. Feel free to download and parse it to see how it works, but remember this is my first real coding work.

For those who have no interest or capability to parse the code and execute it natively, I have a screen recording of the execution.

I hope you enjoy the movie and stay tuned for more!