Notes on “Make: FPGAs” by David Romano

After skimming through a Maker Media book on CNC routing wood furniture, I wanted to see what I could learn from their FPGAs: Turning Software into Hardware with Eight Fun & Easy DIY Projects (*) by David Romano. I was motivated by the FPGA-based badge of Superconference 2019, which had (I was told) a relatively powerful FPGA at its core. But all my badge work were at the software level, I never picked up enough to make gateware changes. Perhaps this book can help me?

My expectations dropped when I saw it was published in February 2016. The book is very honest that things are evolving quickly in the realm of FPGAs and things would be outdated quickly, but I was surprised at how little of the information in the book could be transferred to other FPGA projects.

In the preface, the author explained they had worked with FPGAs in a professional context since the early days (1980s) of the field. Seeing the technology evolve over the years and drop in price into hobbyist-accessible range, this book was written to share excitement with everyone. This is an admirable goal! But there is a downside to a book written by someone who has been with the technology for so long. They are so familiar with concepts and jargons that it’s difficult to get in the right frame of mind to explain things in a way that novices in the field can understand.

As an example of this problem, we only got up to page 15 before we are hit with this quote: “Behavioral models and bus functional models are used as generators and monitors in the test bench. A behavioral model is HDL code that mimics the operation of a device, like a CPU, but is not gate-level accurate. In other words, it is not synthesizable.” That sound is the <WOOSH> of indecipherable words flying over my head.

The hardware examples used in this book are development boards built around various FPGAs from Xilinx. To use those boards, we have a long list of proprietary software. It starts with Xilinx software for the FPGA itself, followed by tools from each development board vendor to integrate with their hardware. This introduces a long list of headaches, starting from the fact Xilinx’s “ISE WebPack” was already a discontinued product at the time of writing, with known problems working under 64-bit Windows. And things went downhill from there.

For reference, the hardware corresponding to projects in the book are:

The project instructions do not get into very much depth on how to create FPGA gateware. After an overly superficial overview (I think the most valuable thing I learned is that $display is the printf() of Verilog) the book marches into using blocks of code published by other people on OpenCores, and then loading code written by others onto FPGA. I guess it’s fine if everything works. But if anything goes wrong in this process, a reader lacks knowledge to debug the problem.

I think the projects in this book have the most value for someone who already has one of the above pieces of hardware, giving them instructions to run some prebuilt gateware on it. The value decreases for other boards with Xilinx FPGA, and drops to nearly nothing for non-Xilinx FPGA. This book has little relevance to the Lattice ECP5 on board Superconference 2019 badge, so I will have to look elsewhere for my FPGA introduction.

(*) Disclosure: As an Amazon Associate I earn from qualifying purchases.

Notes on “Make: Design for CNC” by Filson, Rohrbraher, and Kaziunas France

After skimming through Maker Media’s Bluetooth book, I did the same for their Design for CNC: Furniture Projects & Fabrication Technique (*) published in 2017. The cover listed authors as Anne Filson, Gary Rohrbacher, and Anna Kaziunas France. Bill Young didn’t get on the cover but was included in “About the Authors” section at the end. The focus is on building human-scale furniture by using CNC routers to cut flat pieces out of 4′ x 8′ sheets of plywood. Details are given for some (but not all) of the pieces we see on the authors’ site AtFAB, and readers without all the equipment (which includes me) are encouraged to join the 100kGarages community for help to turn ideas into reality.

CAD software used for examples was SketchUp 2015, that particular version is no longer available. While there is still a free Sketchup tier, it is limited to their browser-based release. CAM software in the book is Vectric VCarve, which never had a free tier. The authors’ CNC router is a ShopBot PRSalpha and discussion on cutters mostly referenced Onsrud. Obviously, a reader with more in common with authors’ setup will have an easier time following along. I have none of it, but I skimmed the book to see what I can learn. Here are the bits that I thought worth jotting down:

Chapter 2 had several sections that are valuable to anyone building structures out of flat sheets of material, whether CNC routing big pieces out of plywood or laser-cutting small things out of acrylic. They describe some basic joints, that lead to assemblies, leading to styles of structures. These were the building blocks for projects later in the book and are applicable to building 3D things out of 2D pieces no matter what tools (software or hardware) we use.

Chapter 3 describes their design process using SketchUp. Some of the concepts are applicable to all CAD software, some are not. Explanations are sometimes lacking. The author used something called the Golden Ratio without explaining what it is or why it is applicable, so we have no idea when it would be appropriate to use in our own designs. We are shown how CAD helps keep various views of the same object in sync, but at certain places the book also says to use “Make Unique” to break this association without explaining why it was necessary. I had hoped to see automated tooling to support managing 3D structures and their 2D cutting layout, but no such luck. This workflow used a “Model” layer to work in 3D and a “Flat” layer to lay out the same shapes in 2D space for cutting followed by a “Cut” layer with just 2D vectors to export to CAM software. It feels like a motivated software developer can help automate this process. (Perhaps someone has in the past five years! I just have to find it.)

I noticed a trend of information becoming less generally applicable as the book went on. By the time we got to CAM in Chapter 7, it was very specific to VCarve with few generalizations that we can take and apply to other CAM software. One missed opportunity was a discussion on climb milling versus conventional milling. The book explains that there are so many variables involved (the material, the cutter, the machine) a specific setup may work better one way versus the other. The only way to know is to try both approaches and use whichever one works better. Problem: they never explained what “better” means in this context. What do we look for? What metrics do we use to decide if one is better than the other? The authors would have a lot of experience seeing various results firsthand. That would have been valuable and applicable no matter what CAM software we use, but they didn’t share that knowledge and just left us hanging. Or perhaps they have seen so much, it never occurred to them that beginners would have no idea how to judge.

Another disappointment was in the area of parametric design. In chapter 5 they covered the fact that plywood is not made to precise dimensions, and we’d need to adjust accordingly. However, the recommended default method of adjustment is to scale the entire project rather than adjust a thickness parameter. Later in chapter 12 they showed how to modify a few of their designs by plugging parameters into an app written in Processing. However, the app is limited to the variables allowed by the authors, and each app is unique to a project. The book doesn’t cover how to do parametric design in SketchUp. (Maybe it can’t?) But more disappointingly, the book doesn’t cover the ins and outs of how to write parametric capability for our own designs. The authors started this book by saying how designing and customizing for our own purposes is a huge part of what makes CNC routed projects preferable to generic designs from IKEA, so it was a huge letdown to see nothing about making our own parametric designs.

I would have appreciated more information on working with wood grain. Wood grain is discussed mostly as a cosmetic concern and not a structural one. I guess using plywood mitigates most of those worries? I would have also wanted to see more actual finished pieces. Most of the images in this book were 3D renders and not real pictures, another letdown.

Despite these disappointments I felt I learned a lot from this book generally applicable to building 3D structures from 2D shapes. The resources section at the end looked promising for more information on designing for CNC that go beyond wooden furniture. And finally, unrelated to the topic or the book content, the colophon pointed me to AsciiDoc, which is something I might look into later for future Sawppy documentation.

(*) Disclosure: As an Amazon Associate I earn from qualifying purchases.

Notes on “Make: Bluetooth” by Allan, Coleman, and Mistry

As a part of a Humble Bundle package of books published by Maker Media, I had the chance to read through Make: Bluetooth (*) by Alasdair Allan, Don Coleman & Sandeep Mistry. This book covers a series of projects that can be built by the Make audience: by assembling development breakout boards and discrete components on prototype breadboards.

One of the first things this book covers is that these projects all use Bluetooth LE and not “Classic” Bluetooth. They share two things: (1) they both communicate over 2.4GHz range of RF spectrum, and (2) they are both administered by the Bluetooth Special Interest Group. Other than that, they are completely different wireless communication protocols named for maximum customer confusion.

For each project, this book provides a detailed step-by-step guide from beginning to end, covering just what we need for each project. This is both the book’s greatest strength and leads to my biggest criticism. Minimizing extraneous information not pertinent to the current project avoids confusing beginners, but if that beginner wants to advance beyond being a beginner, this book doesn’t provide much information to guide their future study. This problem gets worse as the book ages, because we’re not given the background information necessary to adapt. (The book is copyrighted 2016, this post is written in 2022.)

The first example is the Bluetooth LE module they used for most of the book: Adafruit product #1697, Bluefruit LE – Bluetooth Low Energy (BLE 4.0) – nRF8001 Breakout. The book never covers why this particular BLE module was chosen. What if we can’t get one and need to find a substitute? We’re not just talking about a global chip shortage. It’s been years since the book was written and Adafruit has discontinued product #1697. Fortunately, Adafruit is cool, and added a link to their replacement products built around the nRF51822 chip. But if Adafruit hadn’t done that, the reader would have been up a creek trying to figure out a suitable replacement.

Another example was the phone interaction side of this book, which is built using Adobe PhoneGap to produce apps for either iOS or Android phones. And guess what, Adobe has discontinued that product as well. While most of the codebase is also available in the open-source counterpart Apache Cordova, Adobe’s withdrawal from the project means a big cut of funding and support. A web search for Apache Cordova will return many links titled “Is Apache Cordova Dead?” Clearly the sentiment is not optimistic.

The Bluetooth LE protocol at the heart of every project in this book was given similarly superficial coverage. There were mentions of approved official BLE characteristics, and that we are free to define our own characteristic UUID. But nothing about how to find existing BLE characteristics, nor rules on defining our own UUID. This was in line with the simplified style of the rest of the book, but at least we have a “Further Reading” section at the back of the book pointing to two books:

  1. Getting Started with Bluetooth Low Energy (*) by Townsend, Cufí, Akiba, and Davidson.
  2. Bluetooth Low Energy: The Developer’s Handbook (*) by Heydon

I like the idea of a curated step-by-step guide to building projects with Bluetooth LE, but when details are out of date and there’s nothing to help the reader adapt, such a guide is not useful. I decided not to spend the time and money to build any of these projects.

(*) Disclosure: As an Amazon Associate I earn from qualifying purchases.

Notes on “Exploring BeagleBone” by Derek Molloy

As an electronics hobbyist I’ve managed to collect two different BeagleBone boards, but I’ve never done anything useful with them. In the interest of learning enough to put them to work, I bought the Kindle eBook for Exploring BeagleBone, Second Edition by Derek Molloy. (*) I dusted off my PocketBeagle from the E-ALE hardware kit and started following along. My current level of knowledge is slightly higher than this book’s minimum target audience, so some of the materials I already knew. But there were plenty I did not know!

The first example came quickly. In chapter 2 I learned how to give my PocketBeagle access to the internet. This is not like a Raspberry Pi which had onboard WiFi or Ethernet. In contrast, a PocketBeagle’s had to access the network over its USB connection. At E-ALE I got things up and running once, but SCaLE was a Linux conference so I only received instructions for Ubuntu. This book gave me instructions on how to set up internet sharing over USB in Windows, so my PocketBeagle could download updates for its software.

Chapter 5 Practical Beagle Board Programming is a whirlwind tour of many different programming languages with their advantages and disadvantages. Some important programming concepts such as object-oriented programming was also covered. My background is in software development, so few of the material was new to me. However, this chapter was an important meta-learning opportunity. Because I already knew the subject matter, as I read this chapter I frequently thought: “Wait, but the book didn’t cover [some related thing]” or “the book didn’t explain why it’s done this way”. This taught me a mindset for the whole book: it is a quick superficial overview of concepts that give us just enough keywords for further learning. The title is “Exploring BeagleBone”, not “BeagleBone in Depth”!

On that front, I believe the most impactful thing I learned from this book is sysfs, a mechanism to allow communication with system hardware by treating their various input/output parameters as files. This presents an interface that avoids the risks and pitfalls of going into kernel mode. Sysfs was introduced in chapter 2 and is used throughout the text, culminating in the final chapter 16 where we get a taste of implementing a sysfs interface in our own loadable kernel module. (LKM) But there are many critical bits of knowledge not covered in the book. For example, sysfs was introduced in chapter 2 where we were told the sysfs path /sys/class/leds/beaglebone:green:usr3/brightness will allow us to control brightness of one of BeagleBoard’s onboard LEDs. That led me to ask two questions immediately:

  1. If I hadn’t known that path, how would I find it? (“What is the sysfs path for an onboard LED?”)
  2. If I look at a /sys/ path and didn’t know what hardware parameter it corresponded to, how would I find out? (“What does /sys/[blah] control?”)

The book does not answer these questions. However, it taught me that sysfs interfaces were exposed by loadable kernel modules (LKM, chapter 16) and that LKMs are loaded for specific hardware based on device tree (chapter 6). Given this, I think I have enough background to go and find answers elsewhere.

The book used sysfs for many examples, and the book also covered at least one example where sysfs was not enough. When dealing with high-bandwidth video data, there’s too much overhead for sysfs so the code examples switched to using ioctl.

My biggest criticism of this book is a lax attitude towards network security. In chapter 11 (The Internet of Things) instructions casually tell readers to degrade their GMail account security and to turn off Windows firewall. No! Bad book! Bad! Even worse, there’s no discussion of the risks that are opened up if a naive reader should blindly follow those instructions. And that’s just the reader’s email account and desktop machine. What about building secure networked embedded devices with a BeagleBone? Nothing. No discussion at all, not even a superficial overview. There’s a running joke that “The S in IoT stands for security” and this book is not helping.

Despite its flaws, I did find the book instructive on many aspects of a BeagleBone. And thanks to the programming chapter and lack of security information, I’m also keenly aware there are many more things not covered by this book at all. After reading this book, I pondered what it meant for my own BeagleBone boards.

UPDATE: I was impressed by this application of sysfs: show known CPU hardware vulnerabilities and status of mitigations: grep -r . /sys/devices/system/cpu/vulnerabilities/

(*) Disclosure: As an Amazon Associate I earn from qualifying purchases.

Notes on “Open Circuits” by Eric Schlaepfer and Windell H. Oskay

I am interested in electronics, in teardowns, and in electronics teardowns. Thus I was the exact audience for a book coming out soon: Open Circuits by Eric Schlaepfer and Windell H. Oskay. I preordered directly from publisher No Starch Press, which also granted me access to an early access eBook. I’ve finished browsing through that PDF and loved every page of it. I look forward to having the print book in my hand.

I first became aware of these cutaways from Twitter, where author Eric Schlaepfer tweeted a few cross sections shot with a cell phone camera via @TubeTimeUS. Feedback was positive, encouraging Eric to repeat the same treatment for more components, improving the techniques as he went. Things got popular enough that a vocal subset of his new Twitter following got grumpy when he went back to his regular programming. (Paraphrasing his reply: “Come on, guys, this account isn’t @CrossSectionTimeUS.”) Still, people loved the cross-sections and some said “I would love to have these pictures in a coffee-table book.” Thus this book Open Circuits.

Every component cross-sectioned in the book is accompanied by a brief explanation of the component. Knowing what a component does and how its internals accomplish the objective helps give us context to understand what we see in the pictures. Sometimes there’s a diagram with subcomponents called out as a visual explanation augmenting the text description. I knew roughly what some of these components did, but most of them were new information for me. But even if I had known of a component, usually I hadn’t known what it looked like inside! Every page is a new discovery. Occasionally, I even recognized something that I’ve seen before. For example, I recognized a thermal switch as something I took out of a retired coffee maker but I wasn’t sure what it was until I saw one explained and cross-sectioned.

This book is aimed at people who want to know more about what happens behind the scenes, so naturally the book covered that as well: the afterword section describes the techniques that went into this book’s photography. From cutting and polishing of components, to cleaning and mounting, to the photography process. Starting with cameras and lenses, to macro photography, and finally focus stacking to compose the sharp pictures in the book.

If you’ve read this far, you will enjoy the book as well.

I earn nothing from endorsing this book, I just love it.

Notes on “Data Oriented Design” Textbook

I spent a lot of time playing Hardspace:Shipbreaker because I enjoyed the game, and I learned about it as an example of Unity’s Data Oriented Technology Stack (DOTS) in action. I was curious about the promised benefits of DOTS and wanted to know more about it. Unity’s learning portal has published several guides relating to the topic including DOTS Best Practices. Among the list of pointers to various background primers is the book Data-Oriented Design by Richard Fabian. (*) The physical book and/or its various digital editions give a full treatment of the topic, but for those who just want to skim through to see the basic concepts, the author has actually made the raw text available online.

And by “raw text” I mean that almost literally. This is a bare-bones site (“HTML 1.0”) with just contents in paragraphs. (Yes, HTML <P> tags.) Tables of information are in actual <TABLE> which sees little use on modern HTML sites. The CSS style sheet is used for its original purpose: declare styling on text with no layout or funny business with <div> mutations. The only images I see are actually code listings a.k.a. pictures of more text. I enjoyed reading such a feed of raw knowledge and here are a few notes.

If I were to summarize the book, I would go with “Why Game Developers Should Learn from Database Gurus.” To be clear, this is not a book about databases, but it discusses many concepts from the world of databases because they are obviously data oriented in nature. Plus, databases have a tremendous history developing methods to work in parallel, taking advantage of multicore processors where most modern applications struggle to do the same. This requires certain ways of thinking about problems, and we can learn from those lessons.

While it would be silly to say every game should be built on SQL queries, it makes sense to consider data-oriented approaches for certain domains. After all, databases underlie a lot of what we do with computers. So many computer applications are merely custom variations of database CRUD pattern that we now have products like Amazon Honeycode built around the concept of letting people create CRUD apps without code. For core game loop data, a general database would incur too much overhead. But we can tailor game code to adopt database concepts where it makes sense to improve game performance.

This book has a focus on game development, which I was surprised by given the lack of mention in the title or in some of the abstracts. It does talk about Unity at places, but only because Unity is a game engine. This book predates Unity’s currently ongoing DOTS overhaul, so DOTS is not mentioned. Code examples are in C/C++ and not the C# used by Unity, but as they are there mostly to illustrate concepts, the specific programming language is less important.

The text starts with a lot of thick theoretical foundations that I found difficult to chew through, with many words I found ambiguous. Things didn’t start to click for me until some concrete examples were shown. There were examples of how object-oriented programming becomes unwieldy in large projects, and I find myself nodding a lot from my own career experience. Data-oriented design approaches were then given as examples of how many of those problems can be solved, and they certainly sound good in theory! But I have yet to see them in practice for large projects and, more importantly, this book didn’t spend any time talking about how DOD might stumble into its own unwieldy problems. I don’t know how to avoid them if I don’t even know what they look like! Another way to present my wariness is this table:

Development ApproachGreatness in TheoryHurdles in Reality
Object-Oriented DesignDiscussedDiscussed
Data-Oriented DesignDiscussed…?

After reading this book, I’m convinced enough of merits to give data-oriented design a try, but I will have to keep my eyes open for where it stumbles. Because I’ve been writing code long enough to be sure of one thing: every nifty new solution to existing problems will bring its own new and unique problems. In time, with practice, I’m sure I’ll learn where DOD is the wrong tool for the job. The good news is that, thanks to the generalized nature of this book, I don’t necessarily have to try applying these concepts inside Unity. Which is good because Unity is still rolling through a multi-year transition to DOD.

(*) Disclosure: As an Amazon Associate I earn from qualifying purchases.

Notes on “ROS Robot Programming” Book by Creators of TurtleBot 3

ROS Robot Programming cover 800The people at Robotis who created TurtleBot 3 created a pretty good online manual for their robot that also served as a decent guide for a beginner like myself to start experimenting with ROS. But that’s not the only resource they’re released to the public – they’ve also applied themselves to writing a book. It has a straightforward title “ROS Robot Programming” and is described to be a compilation of what they’ve learned on their journey to create the TurtleBot 3. Pointers to the book are sprinkled throughout the TurtleBot 3 manual, most explicitly under the “Learn” section with additional resources.

The book is available in four languages: English, Chinese, Japanese, and Korean. The English and Chinese editions are also available freely as PDF. I thought I’d invest some time into reading the book, here are my comments:

Chapters 1-7: ROS Fundmentals

The reader is assumed to be a computer user who is familiar with general programming concepts, but no robotics knowledge is assumed. The book starts with the basic ideas behind ROS, then working from there. These chapters have a great deal of overlap with existing “Beginner Level” tutorials on ROS Wiki. Given this, I believe the bigger value of this book is in its non-English editions. Chinese/Japanese/Korean readers would probably benefit more from these sections written in their respective languages, making this information accessible for readers who can’t just go to the English ROS Wiki tutorials like I did.

Content-wise, the biggest deviation I found in this book was that it treated the action library as peers of ROS topics and services. As a user I agree it made sense to cover them together and I’m glad this book did it. And as someone who has worked on programming platforms, I understand why the official documentation treated them differently.

Chapter 8: Sensors and Motors

Given that chapters 1-7 overlapped a lot with the tutorials I’ve already covered, it was not terribly informative. That changed when I got into chapter 8, where we started talking about a few different classes of sensors people have used in ROS. When it came to motors, though, the only one covered was Robotis’ own Dynamixel product. This was a little disappointing – they could have at least put some minor lip service to motors other than their own product. But they chose not to.

This chapter ended with a useful tutorial and some words of wisdom about how to navigate the big library of ROS modules openly available for us to play with. This is a good place for the topic, because sensor and motor driver libraries are going to be the first things beginners have to deal with beyond core ROS modules. And skills dealing with these libraries will be useful for other things beyond sensors and motors.

Chapter 9-13: All Robotis All The Time

The rest of the book is effectively an extension of the TurtleBot 3 manual with side trips to other Robotis projects. They go over many of the same ideas, using their robots as example. But while the manual focused on a specific robot, the book did try to go a little deeper. They said their goal is to cover enough so the reader can adapt the same general ideas to other robots, but I don’t feel I’ve received quite enough information. This is only a gut feeling – I won’t know for sure until I start rolling up my sleeves and get to work on a real robot.

The final few chapters felt rushed. Especially the abrupt ending of the final manipulator chapter. Perhaps they will work to fill in some of the gaps in a future edition.

Final Verdict: B+

I felt like my time spent reading the PDF was well spent. If nothing else, I have a much better understanding of how TurtleBot 3 (and friends) work. The most valuable aspect was seeing ROS described from a different perspective. I plan to check out a few other ROS books from the library in the future, and after I get a few books under my belt I’ll have a better idea how “ROS Robot Programming” ranks among them. It’s clear the first edition has  room for improvement, but it is still useful.

Rails Tutorial (Take 2)

With all the fun and excitement around 3D printing, I’ve let my Ruby on Rails education lapse. I want to dive back in, but it’s been long enough that I felt I needed a review. Also, during my time away, the Ruby on Rails team released version 5, and Michael Hartl’s Ruby on Rails Tutorial was updated accordingly.

Independent of the Rails 5 updates, it was well worth my time to go through the book again. On second run, I understood some things that didn’t make sense before. It was also good to look at the first do-nothing “hello app” and the second automated-scaffold “toy app” with a little more Rails knowledge under my belt. The book is structured so the beginner reader didn’t have to understand the mechanics of the hello or toy apps, but readers with a bit of understanding will get something out of it.

The release notes for the update mentioned that a few sections were rearranged for better pacing and structure, and added more exercises for readers to check their progress. Both are incremental improvements that I appreciated but neither were especially earth-shattering.

Action Cable, one of the big signature feature of Rails 5, was not rolled into the book. Hartl is handling that in a separate tutorial Learn Enough Action Cable to be Dangerous which I will go through at some point in the near future.

Towards the end of the book, Hartl introduced an optional advanced concept: using Amazon Web Services to store user image uploads. I skipped that section the first time through, and decided to dive into it this time.

I quickly found myself in a deep rabbit hole. Amazon Web Services has many moving parts designed for a wide range of audiences and it’s a challenge to get started without being overwhelmed.

Which is where I am now. Lots more exploration ahead!