# Brushless actuator control board, r2

The first revision of the brushless servo control board for SMMB was successful in getting a leg to jump.  I ended up doing a small-run second revision that addressed a few minor problems and added a couple more capabilities.

• RS422 Debug/Link Port: I had a 3.3V serial port exposed previously for debugging, however it caused my USB-serial converter to dislike itself due to common mode ground shifts and it wasn’t reliable at high baud rates (>3Mbps).  I also wanted to support “linked” modes, where two servos would perform control in the actuator space at full rate.
• Debug through holes: r1 had a number of debug connections, all of which were unpopulated SMD pads.  I decided that through holes were easier to connect debug wires to.
• Vertical SWD connector: I had initially thought I would hide the SWD connector within an enclosure.  However, the initial enclosure prototypes made that seem less desirable, so I switched it to vertical.
• More debugging points: When bringing up the first board, I ended up doing a lot of carefully balancing scope probes on various pins, when there was plenty of board room to just have through hole debug points.  Lesson learned.
• FET temperature sensing: r1 just had an external temperature sensor port, r2 additionally has a thermistor next to the FETS.

Macrofab’s current pricing scheme provides a great incentive to keep your BOM below 20 parts, as that is the only way to get quick turn service.  Otherwise you pay an extra 2 or 3 weeks of calendar time.  In r1, I went to some lengths to stay under 20, however, it just wasn’t going to work with r2, so I left a few easy-ish or non-critical parts unpopulated to do them myself: the connectors, LEDs, and one really big diode.

# Pinions, set screws, and glue

One of my intermediate goals for building new actuators for SMMB is to get them robust enough to jump continuously for some duration of time.  Progress is slow, as things break, new parts are ordered, repairs are made, and jumping resumes.  The most recent failure is at least interesting enough to me that it is worth writing up.

To recap, I’m building a brushless servo based around a Turnigy Elite 3508 brushless motor and a custom 5x planetary gearbox.  The 3508 is intended for quadcopter applications, so to install a spur gear I first extracted the original shaft, then pressed in a new shaft with two flats on it.  One flat for the set screw attaching the rotor to the shaft (which had a press fit), and a second for the set screw attaching the spur gear to the output of the shaft.

While jumping, the set screw holding the spur gear kept freeing itself, no matter whether thread lock was applied or not.  In retrospect, the reason should have been obvious.  In all my previous RC motor experience, pinions were attached with set screws and a slip fit.  However, all those previous applications also used a motor that spun fast with a high ratio gearbox, so the actual torque applied to the motor shaft through the spur gear was relatively low.  In this application, with just a 5x gear reduction and relatively large amounts of torque, the spur gear was seeing torque on the order of 1 N*m.

As the internet will tell you, set screws are not an appropriate attachment mechanism for anything but the smallest of loads.  Even with a shaft with a flat, the entire torque load ends up being concentrated in just one tiny bit of the set screw until it elastically deforms and eventually either destroys or frees itself.

Ben Katz, who built the inspiration for this work, used a shrink fit to attach the spur gear to the motor.  I knew that, but didn’t have sufficient machining tolerances easily available to me to make that happen.  Other simple mechanical options, like a dowel pin didn’t seem like they would be that much more effective than the set screw.

What seemed like more of an option after a little calculation, was glue!  Or rather, LOCTITE 680 brand retaining compound .  The shaft is 4mm in diameter, and the spur gear covers about 8mm of the shaft’s length.  That means there is $\pi * 4mm * 8mm =100mm^2$ of contact surface area.  A 1 N*m torque at 2mm radius thus results in $1 N*m * 2mm / 100mm^2 ~= 5 MPa$ of shear strength required.  LOCTITE 680 has a shear strength when cured of approximately 25 MPa, which gives a 5x safety margin.

Retaining compound was applied, jumping recommenced, at least until the next thing broke…

# bazel for gstreamer – plan

After OpenCV, the other major dependency the mjmech software has, which is necessary to complete the raspberry pi 3b+ bazel build setup, was gstreamer. Unlike the previous dependencies, this one is a doozy — gstreamer has an enormous transitive dependency set. Additionally, we needed to use its ffmpeg wrappers, which brings in more dependencies.

In this post, I’ll just try to map out the dependencies that we ended up actually needing, so that they can be tackled one by one.

### gstreamer core

The core gstreamer base, actually has a minimal dependency set, only really glib. glib in turn has a small dependency set, just libffi, pcre, and zlib.

### gst-plugins-base

Most of the functionality within the gstreamer ecosystem is contained within “plugins”, i.e. modules of software which implement a constrained interface and can be installed into media pipelines. All plugins use the common routines defined within gst-plugins-base, and a few low level plugins are defined here. This begins the dependency explosion, as some of these base plugins start to call into non-trivial pieces of the free desktop graphical stack. Direct dependencies here include libx11, libxv, from x.org, and pango.

In turn those packages have a large fanout. libx11 and libxv depend upon videoproto, libxext, xorgproto, libxcb, libxau, libxdcmp, xtrans, and xcb-proto. pango depends upon freetype, harfbuzz, fribidi, cairo, bzip2, freetype, pixman, fontconfig, util-linux, and expat.

mjmech doesn’t rely on any of the plugins in gst-plugins-good, so nothing was necessary there! We do use some from gst-plugins-bad, but those have no additional dependencies.

### gst-plugins-ugly

Here, mjmech uses the x264 plugin, which in turn depends on the x264 external library.

### gst-libav

These are the plugins which wrap ffmpeg (nee libav, nee ffmpeg). ffmpeg in turn depends additional on nasm to assemble for x86.

## Next steps

Now that we’ve enumerated all the dependent packages, we can start to work on packaging them. First up are those necessary for gstreamer core, so libffi, pcre, and zlib.

# bazel for opencv

The next level of difficulty in bazel-ifying packages for mjmech was opencv.

First, for the impatient, Apache 2.0 licensed sources are available on github: https://github.com/mjbots/bazel_deps/tree/master/tools/workspace/opencv

OpenCV’s native build system consists of nearly 200 cmake files with over 20,000 total lines of code, plus assorted helper scripts and prototype files which are substituted into.  Fortunately, I didn’t need to support the full complexity of the opencv build system.  Things I didn’t bother to touch:

• Autodetecting the location of any packages:  Since this is embedded within a bazel project, all the dependencies I was going to use were already bazel-ified.
• GPU support:  I didn’t bother with CUDA, OpenCL, or anything else GPU, as the GPU on the raspberry pi3 has only a minimally supported OpenCL stack, at best.
• Examples: I had no real need to build any of the sample or demonstration applications.
• Modules: I only needed, for now, a small fraction of the total opencv module set.

## Intended result

OpenCV is broken up into numerous “modules”, each of which is largely independent and implements a relatively self-contained piece of functionality.  Each module can depend upon other opencv modules and other external packages.  I wanted to reach a point with the bazel configuration where each module could be described at a relatively high level, which didn’t seem too implausible since the module structure is relatively constant across modules.

Think something like:

cvmodule(
name = "core",
)

cvmodule(
name = "imgproc",
deps = [":core"],
)

# ... etc

## Bazel implementation

To achieve this in bazel requires three phases: first, a repository rule to actually download the opencv tarball, second something written in Starlark which could implement a cvmodule like rule, and finally a BUILD file equivalent to call it and enumerate the opencv modules I cared about.

The repository rule was relatively straightforward.  It just uses the standard bazel mechanisms to download a tarball and template expand a known BUILD file into place.

The Starlark file is where all the real work lies:

First, we just define a common set of preprocessor defines which will be applied to all opencv translation units:

_OPENCV_COPTS = [
"-D_USE_MATH_DEFINES",
"-D__OPENCV_BUILD=1",
"-D__STDC_CONSTANT_MACROS",
"-D__STDC_FORMAT_MACROS",
"-D__STDC_LIMIT_MACROS",
"-I$(GENDIR)/external/opencv/private/", ] The only real interesting piece there is the $(GENDIR) fragment, which causes bazel to substitute in the path to the generated output directory. Since a number of the headers that we will be using later on are generated as part of the bazel build process, we need to ensure that the compiler can actually find them.  The alternate formulation which doesn’t require knowledge of GENDIR is to list it in the includes attribute.  That however, exposes the headers to all downstream modules, which we don’t want.

Next, we enumerate the set of processor specific options that we will support:

_KNOWN_OPTS = [
("neon", "armeabihf"),
("vfpv3", "armeabihf"),
("avx", "x86_64"),
("avx2", "x86_64"),
("avx512_skx", "x86_64"),
# ...


OpenCV has support for a comprehensive set of special instruction set extensions for a variety of different processors. They can either be compiled in and always used, or dispatched at runtime, although these bazel rules ignore runtime dispatching entirely. Some of the generated headers need to know the full possible set of options for a given architecture, thus this list here.

## Module definition macros

Now we can start getting into the module definition Starlark macros.  To handle some generated headers that are common to every opencv module, I ended up creating an opencv_base macro that is module independent.  It needs to be called from the BUILD file, to generate a number of the private headers, but exposes no logically public labels.  It does require a passed in “configuration” dictionary (which will also be passed in to the primary module generation macro).

CONFIG = {
"modules" : [
"aruco",
"calib3d",
"core",
"imgcodecs",
"imgproc",
],
# ...

The big annoyance here is that you have to enumerate the set of modules twice.  Once in that config, and again in the set of invocations to the module creation macro.  The reason is the generated opencv_modules.hpp file, which provides preprocessor defines describing which modules are included in the build.

Next is the implementation of the module generation macro, which I ended up calling opencv_module.  It needs just a few arguments for the modules I ended up converting:

• name – should be self-evident
• config – the same configuration dictionary from above
• excludes – source files to skip compiling from this module
• dispatched_files – the list of files in this module which contain processor specific specializations
• deps – a set of bazel labels describing the dependency set

This macro goes about generating the appropriate .simd_declarations.hpp and .simd.hpp files, a non-functional stub OpenCL implementation, and then goes on to define the actual bazel cc_library.

## Resulting BUILD file

At this point, the BUILD file can glue all these things together. It ended up being not too far away from my initial ideal:

opencv_base(config=CONFIG)

opencv_module(
name = "core",
config = CONFIG,
dispatched_files = {
"stat" : ["sse4_2", "avx"],
"mathfuncs_core" : ["sse2", "avx", "avx2"],
},
deps = ["@eigen"],
)

opencv_module(
name = "imgproc",
config = CONFIG,
dispatched_files = {
"accum" : ["sse2", "avx", "neon"],
},
deps = [":core"],
)

# ...

As mentioned at the start, all the source are available on github:

# Slow motion leg jump

After the initial leg jumping with the prototype brushless actuator for SMMB, I spent some time actually tuning the control loops and making the firmware not incredibly convoluted to get started.  I also acquired a high speed camera for analysis.

So, here is a brief update of the final jump before I seem to have toasted one of my DRV8323 motor drivers.  It jumped for about 400ms of hang time, running at about half of the maximum current the system should be capable of pulling.

# More robust jumping fixture

In my first foray into 80/20, I built a slightly more robust jumping fixture for the SMMB leg jumping test:

Overall it is much more rigid than the old one, and looks a little nicer.  To top it off, I laid down a neoprene sheet for surface protection and friction enhancement, which is a step up from the old cardboard surface both in aesthetics and function.

# bazel-ifying simple autoconf packages

This is part N in a series describing how I created the bazel infrastructure to build all the third party packages for mjmech.  Previously we have:

We left off with the first, very simple packages configured to build with bazel.  In this installment we will tackle those that require at least minimal configuration, i.e. those that have some files which are normally generated as part of the build process.

## snappy / template_file

snappy (https://github.com/google/snappy), a file compression library, is largely a pure C++ project, but it does have a single generated header file.  There are a few possible options within bazel to handle this.  The simplest would be to use a macro, although that has complications with respect to namespacing and label resolution.  Here, I created a custom rule, called “template_file”.

As seen in the source on github the interface is relatively simple:

template_file(
src,
is_executable,
substitutions,
substitution_list,
)

There are two possible forms for passing in substitutions, either a string_dict when using “substitutions”, or a list of KEY=VALUE strings in “substitution_list”.  The two forms are present because starlark can make it awkward to deal with dictionaries, so often working with a list is much more convenient.

The snappy build rule uses this to generate snappy-stubs-public.h:

template_file(
name = "snappy-stubs-public.h",
src = "snappy-stubs-public.h.in",
substitutions = {
"${HAVE_STDINT_H_01}": "1", "${HAVE_STDDEF_H_01}": "1",
"${HAVE_SYS_UIO_H_01}": "1", "${SNAPPY_MAJOR}": "1",
"${SNAPPY_MINOR}": "1", "${SNAPPY_PATCHLEVEL}": "7",
},
)

## log4cpp / autoconf

Next up in the difficulty level is log4cpp, which uses autoconf as its native build system.  autoconf typically has a config.h.in file, defined in a semi-standardized format, mostly comprised of lines like:

/* Define to 1 if you have the  header file. */
#undef HAVE_STRING_H

The pre-processing stage turns each of those lines into either an actual #define, or just a a comment saying that it continues to be undefined.

That is substantive enough that the simple built-in bazel template rule won’t cut it though.  For this, we split the work into two pieces, 1) a python helper script to do the actual formatting and 2) a starlark bazel rule which defaults in some common autoconf defines.  For the bazel_deps repository, the bazel autoconf rule has basically every autoconf define that is shared by more than one project in it, to reduce duplication and make it more likely that all the dependencies are configured consistently.

With the two of them together, the resulting BUILD file defines a cc_library as normal, but it depends upon the new autoconf rule like found in the log4cpp instance:

autoconf_config(
name = "include/log4cpp/config.h",
src = "include/config.h.in",
package = "log4cpp",
version = "1.1.3",
defines = autoconf_standard_defines + [
"DISABLE_SMTP",
"DISABLE_REMOTE_SYSLOG",
],
prefix = "LOG4CPP_",
)

# First day jumping!

I continue to make progress on the improved actuators for SMMB.  To briefly recap, these are based on a home-built brushless servo consisting of off the shelf gears, bearings, 3d printed assemblies, and a custom control board.

Moving on from closed loop vector (FOC) control, I’ve now built up a second motor, set both of them communicating over the same RS485 bus, and wired up a minimal makeshift jumping fixture.  The leg didn’t jump as well as I had expected: I was only able to achieve about 300ms of air time and there are a lot of other minor problems/deficiencies as well.  But on the other hand, I don’t appear to have permanently broken anything yet, so improvement will hopefully be mostly continuous!

Obligatory video:

# First closed loop vector control

I’ve reached a minor milestone in developing improved actuators for Super Mega Microbot.  Previously I demonstrated basic closed loop control using a VESC.  Now I have a custom control board running closed loop vector-based current and position control on a single brushless servo!  I’ll hopefully write up pieces in more depth later, but this post can serve as a proof of existence.

First, boards as received from MacroFab:

Mounted onto the planetary gearbox:

And finally, a brief video of operation, with tview (from the mjmech gimbal) alongside.

Amazingly, I’ve needed no blue wires or rework of any kind so far.  Next up is to get it communicating over the RS485 link instead of serial, build a second gearbox, and get it jumping!

# rules_mbed – bazel for mbed

When working on the firmware for Super Mega Microbot’s improved actuators, I decided to try using mbed-os from ARM for the STM32 libraries instead of the HAL libraries.  I always found that the HAL libraries had a terrible API, and yet they still required that any non-trivial usage of the hardware devolve into register twiddling to be effective.  mbed presents a pretty nice C++ API for the features they do support, which is only a little less capable than HAL, but still makes it trivial to drop down to register twiddling when necessary (and includes all of the HAL by reference).

Most people probably use mbed through their online IDE.  While this is a remarkable convenience, I am a big fan of reproducibility of builds and also of host based testing.  mbed provides mbed-cli which gets part of the way there by letting you build offline.  Unfortunately, it still doesn’t provide great support for projects that both deploy to a target and have automated unit tests.  It actually has zero support for unit tests that can run on the host.

## Enter bazel

As many have guessed, I’m a big fan of bazel https://bazel.build, for building software projects.  Despite being raw around the edges, it does a lot of things right.  Its philosophy is to be fast, correct, and reproducible.  While it doesn’t support flagless multi-platform builds yet (#6519), it does provide some minimal multi-platform support.  It also has robust capabilities for pulling in external projects, including entire toolchains and build environments.  Finally, it has excellent support for host based unit tests.

To make it work, you do have to configure a toolchain though.  That I’ve now done for at least STM32F4 based mbed targets.  It is published under an Apache 2.0 license at: https://github.com/mjbots/rules_mbed

## rules_mbed features

• Seamless toolchain provisioning: It configures bazel to automatically download a recent GNU gcc toolchain from ARM (2018q2).
• Processor support: Currently all STM32F4 processors are supported, although others could be added with minimal effort.
• Host based testing: Common modules that rely only on the standard library can have unit tests run on the host using any C/C++ testing tools such as boost::test.
• Simultaneous multi-target configuration: Multiple targets (currently limited to the same CPU family) can be built with a single bazel command.  Multiple families can be configured within the same source tree.

Once you have it installed in a project, building all host based tests is as simple as:

tools/bazel test //...

and building all binary output files is as simple as:

tools/bazel test -c opt --cpu=stm32f4 //...