Wednesday, March 26, 2014

Pinewood Derby Race Track Timer

Last week a cubmaster friend of mine mentioned his troubles with the upcoming Pinewood Derby that the local cubs were going to participate in. He had a track but no easy way to determine the winner except with some judges sitting at the finish line. He mentioned how he might forego using his own den's track and borrow one from another cubmaster friend of his that has an electronic timer. After talking with his friend, it became apparent that it wasn't in working order and would need some TLC from someone experienced enough with the microcontroller used. This is what spurred the conversation with me.

Not having any experience with that particular type of microcontroller, I told him I could research some ways that I could build one into his track (thinking perhaps that it could be another use for the RaspberryPi). I spent a few days "thinking about it" (i.e. on the back burner). I even started a python script that I could use in conjunction with the GPIO ports and some photo resistors to get the times. However, after digging a little deeper, it appeared while this was possible the result wouldn't be accurate.

In steps the Spark Core. I had seen this little beauty back when it was in its Kickstarter campaign and went ahead and purchased one back then thinking I could use it as the brains for my iPhone controlled garage door opener. While it turned out the RaspberryPi was more suited for that, the Spark Core seemed a perfect candidate for this project.

I posted to the Spark community that I wanted to try to use the Core for a Pinewood Derby Race timer and got tons of support. Total props to Brian Ogilvie (bko) and BDub who even gave up some sleep to help out a complete noob.

Here's the schematic:

Here's the finish line. I purchased 4 novelty LED flashlights from the local hardware store and mounted them above. You can barely see the holes, but they are there. There's about 3/4 of an inch between the surface of the track down to the photo resistors, so there shouldn't be any bleed over between lanes or from stray light sources.

I used this code on the Spark Core for testing the circuits to make sure the lights were powerful enough and that the shadows were dark enough. Here's the final code used during the race. I hooked up the Spark Core to my laptop, installed the driver, opened Putty, and connected to the COM port.

So, in the testing, I got an accuracy of ±0.00002 seconds. Once the photoresistors were hooked up, the accuracy became harder to test. However, by sliding a single board over all 4 lanes at the finish line "at the same time", I got about ±0.02 seconds. The degraded accuracy is probably due to the photoresistor reaction times and the fact that even though I tried, I might not have been pushing the board across all four holes at the exact same time.

Here's the video. I finally got around to getting it off my phone and editing it all together.

Putting a Hidden Help Section on a Web Page

Continuing in a series of posts, here's how to add a hidden div to a web page (and make it visible on demand).

For the health check report, I had built a way to transform the output of the script into a usable report and added editable content so that the report could be further tweaked after rendering the page. Given that others would eventually be using the report, I needed to add a way to help non-coders when inserting content into the report so that it looked cogent and coherent. Thus the help section.

However, I couldn't put a help section on the final report, that wouldn't look good when the report was delivered to the customer. So, I had to create a way for the help section to be normally hidden, with a button or link to display the help section. Also, the button had to be hidden!

Let's start with the help section itself. Take a look at the XSLT itself. The help section is simply a DIV containing the help content, with some special CSS applied to hide it until needed. Look at line 22. Notice that the display style is set to none. This hides the DIV entirely and collapses the space around it. It's as if the DIV isn't even there.

Now for a button to show the div when needed. Look at line 15 and you'll see an image with an onclick function. The function is contained in the external JavaScript file (lines 23-29). The JavaScript simply toggles the display style from none to block and back. Really, it wouldn't be too much to just put that function right in the img tag itself, but since I already had the external JS file, it was just as easy this way.

Another look at line 15 will show that the img is contained within a div with id="helptoggler". That div has three lines of CSS that essentially make it invisible until the mouse hovers over it and also puts it in the top left corner of the page:

  1. #helptoggler {position:absolute;left:0px;top:0px;}
  2. #helptoggler > img {visibility:hidden;width:32px;height:auto;}
  3. #helptoggler:hover > img {visibility:visible;}

This means that the image is in the top left corner of the page, is hidden until moused over, and when clicked shows the help section.

Since the JavaScript is built as a toggler, the same function can be called anywhere a link is desired to hide the help section. Clicking on the image in the top left corner hides the DIV, but notice that within the help section itself is a span with an onclick action calling the same JavaScript function (line 24).

Once again, if you want to play with the files themselves, just download, unzip, and open the XML file in IE.

Displaying Editable Content on a Web Page

In my previous post, I detailed how I went about transforming an XML document into a readable report, displaying data from the XML. If you downloaded and tried out the files, you should have noticed that the final report was more than I described.

Particularly, there were two things I glossed over:
  1. There are several boxes on the page that have edit buttons and can be modified after the page is rendered.
  2. There is a hidden div that shows the report author how to format additional content so that it shows up with the same style as the rest of the content on the page.
I'll cover #2 at a later time. Right now, I wanted to talk about how the editable content was built. Remember, the point of the project was to build a final report that could be delivered to the customer. A script was used to gather a bunch of data and output it to XML. An XSLT was used to transform that information into a more readable format. While the script was good at gathering much of the information needed, it didn't go into wordy detail about the recommended changes to be made. Thus a method of adding to the document was needed.  

Initially, I built a section of the XML that would allow the user to input all the information needed right into the XML. That way, the XML transformation and PDF generation would be the last step in generating the report. However, that wasn't too sexy and I still found myself needing a way to edit the content after it was rendered.

So, I came up with EditableContent. This comprised of a few components. Here is what part of the code looks like:

  1. <h2>Summary Recommendations</h2>
  2.     <div id="recsummary" class="editablecontent">
  3.      <img src="health_check_files/edit-icon.png" onclick="editcontent('recsummary','recsummary_content')" />
  4.      <div id="recsummary_content">
  5.       <xsl:if test="reportinfo/recsummary!=''"><xsl:value-of select="reportinfo/recsummary" disable-output-escaping="yes"/></xsl:if>
  6.       <xsl:if test="not(reportinfo/recsummary) or (reportinfo/recsummary='')">Provide a summary description of your recommendations<br /><span class="example">EXAMPLE</span>: The primary recommendations resulting from the data gathering, assessment, and analysis performed during this Health Check are to upgrade both hardware and software on the core NMS components of the infrastructure. In addition to hardware and software upgrades, a review of the alarm/event management process is recommended. Architecturally, the NMS deployment is in accordance with a “Best Practices” implementation for an organization of this size.</xsl:if>
  7.      </div>
  8.     </div>

First is the div containing the content. This div has a unique id and uses a CSS class of 'editablecontent'. This CSS class is what puts the red line around the editable content and also puts the edit button. Click here to see the CSS (pay attention to lines 63-85).

The main DIV has two children, the edit image and the content DIV. The edit button has some special CSS that make it only visible when the mouse moves over the parent DIV. The child DIV is the one containing the content.

Notice the image has a JavaScript function attached. The JavaScript is contained in a separate file (but could just have easily been included in the XSLT). The JavaScript simply switches from a static DIV to an editable textarea box and back again. Depending on which save button is pressed, the JavaScript will return to a DIV that looks like a draft or a final version.

Adding editable content to the XSLT all over the place made it easy to use the data from the XML but have a last minute override for any of the content (i.e. to fix a single misspelling without editing the XML manually).

To see it all in action, download the files, unzip, and open the XML file in IE.

XML and XSLT: Transforming Raw XML into Readable Reports

Not too long ago I was tasked with doing a health check for one of our customers. They used one of the products I was less familiar with, so I decided to look at some previous examples of health check reports and see what information I would need to gather and put in the report. It turns out one of my co-workers had already built a script that gathered some of the necessary information. At my request, he modified the output to XML so that I could then take that XML and use and XSLT (eXtensible Stylesheet Language Transformation) to convert it into a nice pretty report in a browser.
Stored data is really comprised of two parts: the data itself and the schema. The schema is the format or syntax of the stored data. For example, let's say I wanted to store my CD collection. For each CD, would probably store the name of the CD, the artist, what country it was released from, the record label, the price I paid, and the year it was released. These descriptive details form the schema of the data I'm going to store. I could store the data in an Excel spreadsheet, with column headers and one row for each CD. That would be pretty easy, but what if the person I was sending the data to didn't have Excel? Plus, if I took one row out of the spreadsheet, I'd also have to copy the column headers so that the person I was sending the one row to would know what each column means. Without the schema information, the data isn't as easy to understand. XML is a language that allows all my data to be transmitted along with complete schema information. Consider the XML for a CD collection:
See how each piece of data has surrounding tags that help identify what each piece of data means? See how things are nested within each other so that it's easy to see what data pertains to which objects (i.e. which Artist produced which CD)? That's the nice part about XML.

Now, back to the health check. My co-worker had modified his script so that the output was in XML format. That meant that I could then take the XML and easily interpret the data. It also meant that I could build an XSLT which would apply styles, chrome, and extra text to the XML to make it much more readable. Here is what the output of the script looks like. This is the XML, that I want to take and turn into a readable nice report. Ideally, I'd like to turn this into a PDF.
The way to transform this is to build an XSLT and reference that XSLT within the XML itself. See how line 1 has a link to a xsl stylesheet? That's the XSLT. When the XML is opened in a supported browser (IE works best surprisingly), the browser will go find the XSLT and perform the translation against the XML data.
Ok, that's not too bad, right? Ok, let's go through the magic one piece at a time. The first 6 lines are pretty standard XSLT. The good stuff starts online 7. In a way, the XSLT will be merged with the XML. Technically, the XSLT is inserted into the XML document, but it is almost easier to think about the XML being inserted into the XSLT (it's actually because of this that most people actually incorrectly say that XSLT is in HTML format thinking that it's the HTML that the XML gets inserted into, but I digress).
So, line 7 starts an XSL template. The XSL template here essentially says to go to the tag in the XML called 'nimsoft' and insert some HTML. (By the way, whenever an XSLT is applied, the underlying XML is pretty much hidden except where the XSLT specifies that it should be displayed.) So lines 8-19 are pretty standard HTML document headers. In another post, I'll go into the details about the helptoggler and the editablecontent parts. They have more to do with HTML and Javascript than XML/XSLT.
Line 20 is the first place where we're going to insert some of the XML data. The <xsl:value-of select="reportinfo/company" /> tag instructs the browser to display the value inside the company tag, which is under the reportinfo tag, which is under the nimsoft tag. In the final HTML, line 20 would look like this:
<div id="company_name_content">Health Check for Fake Company</div>
Lines 21-88 are more standard HTML. This section of the report is displayed to help the author make some changes after the initial version is rendered. I'll discuss this in another post.
Lines 89-96 make use of the xsl:value-of tag to pull in more XML data. This time, pulling from the nimsoft/reportinfo/authors tag (e.g. Mickey Mouse) and the nimsoft/reportinfo/reportdate tag (e.g. 06 Feb 2014).
Lines 97-107 contain a simple legal notice, another standard HTML block. Remember, all the standard HTML is just inserted at the point of the last template match. So, we're still inserting onto the root of the XML.
Lines 108-135 begins the first section of the actual report and is more standard HTML, with a couple xsl tags. The first is at line 130, which uses the xsl:if statement to check to see if there is a value at the nimsoft/reportinfo/recsummary tag. If there is something there, the xsl:value-of tag displays it. It also uses the disable-output-escaping attribute, which means that the XML can contain valid HTML. Line 131 uses the xsl:if again checking for the existence of the nimsoft/reportinfo/recsummary tag or if it's empty. If it doesn't exist or it's empty, some boiler plate HTML is inserted instead of what we would have expected from the XML. This is handy since it allows that tag to be optional in the XML.

Up to this point, I've been using something called XPath to reference particular tags within the XML. XPath is a specification that allows tags to be referenced using their path in the XML. So far, I've shown how the root template has worked. Within any of the xsl:value-of tags, the select attribute has used XPath to specify a particular tag. Since I've been working within the root template (nimsoft), that part of the path is implied. 

From lines 136-169, I follow the same pattern already established: put some raw HTML on the page, insert some values from particular XML tags using XPath. This also applies to lines 177-367. It all uses the same basic concepts.

However, lines 170, 172, 174, & 176 use the xsl:apply-templates tag. This xsl tag instructs the browser to move down to the specified node in the XML and loop through the children of that node. This is similar to calling a function from within a program.

Line 170 specifies to go to the NMS node. Since we're inside the nimsoft template, that means the browser will move to the nimsoft/NMS node and loop through the children. To see what the browser does, look at lines 368-394. These lines specify what to do whenever the xsl:apply-templates tag is used for any node called NMS.
Particularly, this piece of the XSLT builds a table and inserts the values of the various children nodes of the NMS node (lines 369-383 & 389-393). Lines 384-388 specify another xsl:apply-templates tag (disks/disk), which means the browser moves to that node and processes the children; see lines 422-427. This nested template outputs a single row for each disk under NMS/disks/. Once all the children are processed, the browser returns to the template that called the apply-templates tag.

Lines 172, 174, & 176 use similar templates, which either call their own templates or existing templates. For example, both the NMS and UMP templates call the disks/disk template since the disks are stored in the same way as the parent.

And that's about it. By walking through the XSLT with the XML right beside it, you can see how the final result is made. Simply opening the XML in IE was enough to get the information to display. It is pretty trivial from there to generate a PDF version of the report.

Here's a snipped of what the final report looks like. If you're interested in playing around with it yourself, you can download the sample XML, XSLT, and the other auxiliary files here. Next time, I'll talk about how I built the help section and the editable content.



Monday, March 10, 2014

Raspberry Pi Possible Projects

Whenever I get into a conversation with people about the RaspberryPi, the question always comes up, "What would I do with something like that?" This post answers that question. In addition to the two projects that I've already completed (PiTunes, DoPi), here are some project that I've run across that are pretty cool ideas:

  • Make your own radio station - be careful with this one; once you're transmitting beyond a particular power level (which isn't really controllable in the Pi), you're required to have a license from the FCC (even if no one else is transmitting on the same frequency).
  • Make an motion detector - this one is pretty cool since it uses Google's translate service to speak whatever text you want.
  • Get the heck outta my office device - Ok, this one actually uses an arduino, but it would be pretty easy to make something like this using the RPi. 
  • Make a simple webcam
  • Make an Apple iBeacon - I may actually integrate this into DoPi at some point so you get a push notification on your phone as you drive up to your house, prompting you to open the garage door. Otherwise, it could be used for a variety of annoying reasons (including on a convention floor to drive people to your booth...). (Alternate method)
  • Make an AirPlay receiver - an AirPlay receiver will receive a stream of music from an Apple iOS device (phone, tablet, or even iTunes on a PC/Mac) and output it to speakers. This can be handy if you ever wanted to add music to a room without major electronics.
  • Make a camera
  • Make a tablet
  • Connect your analog phones to Google Voice
Oh, and if you wanted to do something with the RPi, but found the portability an issue, there are a couple of ways to make your own battery pack (way 1, way 2).