Compile the Robot Control Library for a different beaglebone cape - beagleboneblack

Question

How should I go about modifying and/or compiling the Robot Control Library for use with a different beaglebone cape that uses slightly different pin assignments?
My primary reason for wanting to re-use the Robot Control Library is the ability to read a fourth encoder via the PRU. Beyond that, I only need access to the encoder and pwm modules.

Answer 1

TL;DR
Modifying the PRU firmware to read the encoder signal from a different pin was easy. Figuring out how to assemble a working device tree for the combination of features I needed was way harder.
I would welcome any feedback on how I should have done this, or how I could improve upon what I currently have.
Robot Control Library + Motor Cape
The Robotics Cape and the BeagleBone Blue provide a turnkey solution for servo controlling four motors,
IFF you are satisfied with driving them at 8V (e.g. a 2S LIPO battery). The Motor Cape can handle a
higher drive voltage (and more current), but does not include encoders. Plugging encoders into the P8 & P9
headers on the Motor Cape is simple enough, but the BeagleBone itself only has 3 encoder counters (eQEP).
The Robot Control Library solves this problem by reading the fourth encoder with PRU0. However, some of the
pins conflict between the Motor Cape and what the Robot Control Library expects on the Robotics Cape.
So, how hard could it be to use the Robot Control Library to read encoders and drive motors with a slightly
different pinout on the Motor Cape? Probably not difficult at all if you are already competent with BeagleBone
device tree overlays, which I am not...
It all starts with a plan -- Pin Selection
Pin
PRU Bit
Robotics Cape
Motor Cape
P8_15
15
Enc 4B
--
P8_16
14
Enc 4A
M2 Dir
P9_25
7
IMU
--
The Robot Control Library expects the fourth encoder to show up on P8_15 and P8_16, but the
Motor Cape has P8_16 wired as a direction signal. There are only 12 pins than be configured
as inputs to PRU0 and I eventually selected P9_25 because I did not need the IMU functionality.
The best reference I found for what pins can be used for what purposes were these pdfs:
https://ofitselfso.com/BeagleNotes/BeagleboneBlackP8HeaderPinMuxModes.pdf
https://ofitselfso.com/BeagleNotes/BeagleboneBlackP9HeaderPinMuxModes.pdf
The Easy Part -- Modifying the PRU Code
The Robot Control Library defines the encoder signal input bits in pru_firmware/src/pur0-encoder.asm as
; Encoder counting definitions
; these pin definitions are specific to SD-101D Robotics Cape
.asg r0, OLD ; keep last known values of chA and B in memory
.asg r1, EXOR ; place to store the XOR of old with new AB vals
.asg 14, A
.asg 15, B
This can be modified to look for the A channel on bit 7 (of register 31, which is used for all inputs) as
; Encoder counting definitions
; these pin definitions are specific to SD-101D Robotics Cape
.asg r0, OLD ; keep last known values of chA and B in memory
.asg r1, EXOR ; place to store the XOR of old with new AB vals
.asg 07, A
.asg 15, B
N.B. The PRU firmware has to be separately compiled by by running make and sudo make install
inside the pru_firmware directory. It is not compiled automatically as part as part of building the rest
of the library from the top-level Makefile.
Helpful Tip: What version am I actually running?
There are instructions on modifying the repored version of librobotcontrol in
library/version_updating_howto.txt. I followed these instructions to create my own
"private" version number so that I could confirm that I was actually running my modified
version of the libray. This version is reported by rc_test_drivers.
However... as noted above, the PRU firmware was not getting compiled by the top-level Makefile,
so for a while I was running my "new" version of librobotcontrol with "old" firmware in the PRU.
The Part that Almost Worked -- The Device Tree
I found references in both the documentation and code for librobotcontrol that device tree overlays
were no longer needed because the Robotics Cape used its own device tree.
The overlay is deprecated now, instead the cape gets its own complete device tree.
I also observed that running the recommended configure_robotics_dt.sh replaced /boot/uEnv.txt with
the following simplified version that loads a single device tree binary (.dtb)
uname_r=4.19.94-ti-r42
dtb=am335x-boneblack-roboticscape.dtb
cmdline=coherent_pool=1M
My favorite reference that I found for general information about the device tree, pinmux, etc was
http://www.ofitselfso.com/BeagleNotes/AboutTheDeviceTree.pdf However, I now realize that some of the
details are a bit out of date, so be careful.
Because I had very little idea of where else to start, I set out to modify the robotics cape device tree
just enough to eliminate the conflicts with the Motor Cape. I forked and cloned
https://github.com/beagleboard/BeagleBoard-DeviceTrees and created two new files
am335x-boneblack-custom.dts
copy of am335x-boneblack-roboticscape.dts
changed model to make the new device tree recognizable
changed #include to point to am335x-custom.dtsi instead of am335x-roboticscape.dtsi
am335x-custom.dtsi
copy of am335x-roboticscape.dtsi
deleted a whole bunch of stuff I thought I didn't need anymore
routed P9_25 (instead of P8_16) to PRU0
Before
/* PRU encoder input */
0x03c 0x36 /* P8_15,PRU0_r31_15,MODE6 */
0x038 0x36 /* P8_16,PRU0_r31_14,MODE6 */
After
/* PRU encoder input */
0x03c 0x36 /* P8_15,PRU0_r31_15,MODE6 */
0x1ac 0x36 /* P9_25,PRU0_r31_7,MODE6 */
After compiling and installing the modified device trees (make, sudo make install in the
BeagleBoard-DeviceTrees repo), I modified /boot/uEnv.txt to call my new custom device tree
uname_r=4.19.94-ti-r42
dtb=am335x-boneblack-custom.dtb
cmdline=coherent_pool=1M
I was able to boot the BeagleBone with no cape installed, plug encoders directly into the desired pins
on P8_and P9 (including enc4a on P9_25) and read all four encoders using sudo rc_test_encoders.
I thought I had won and went to bed...
Motor Cape Won't Boot
After a good night's sleep, I plugged the Motor Cape onto the BeagleBone expecting nothing to change since
I was only passing encoder signals directly through the P8 and P9 headers. I thought the next step would be
to make similar tweaks to a few of the pwm direction pins.
However, the BeagleBone refused to boot my custom device tree with the MotorCape installed. I went back to
the "standard" am335x-boneblack-roboticscape.dtb device tree and observed that it would not boot either with
the Motor Cape intalled. I also became suspicious that the "factory" installation of the Robotics Cape might have
been using overlays after all
I had been torn from the beginning about whether I should be starting from the Robotics Cape device tree and removing
things I did not need in order to eliminate resource conflicts, versus starting with the "naked" BeagleBone device tree
and adding the things that I did need. Whether accurate or not, in my mind that kind-of mapped into trying to specify
a full device tree versus providing an overlay to apply on top of the base device tree. The latter seemed like
the conceptually more correct path, so once the Motor Cape failed to boot with the robotics-cape-derived device tree,
I decided to bite the bullet and try to figure out device tree overlays.
Unanswered Questions
[ ] Why won't the BB boot from am335x-boneblack-roboticscape.dtb with the motor cape installed? What is the actual error?
[ ] Does a "normal" installation of librobotcontrol install the simplified uEnv.txt above or does it use an overlay? Does it work?
I did not yet have USB-to-TTL serial cable that could fit under an installed cape, so I know very little about
why or how this was failing to boot.
The Part that Finally Worked -- Device Tree Overlays
I eventually figured out that the collection of device tree overlays is avialable both at
https://github.com/beagleboard/bb.org-overlays and in the v4.19.x-ti-overlays branch at
https://github.com/beagleboard/BeagleBoard-DeviceTrees. I suspect that this might be an
in-progress migration, but there was more documentation associated with the bb.org-overlays
repository so that is what I chose to use.
A few documentation links that I wish I had found earlier:
https://elinux.org/Beagleboard:BeagleBoneBlack_Debian#U-Boot_Overlays
https://github.com/cdsteinkuehler/beaglebone-universal-io
https://vadl.github.io/beagleboneblack/2016/07/29/setting-up-bbb-gpio
I created forked, cloned, and branched the bb.org-overlays repo and created a new overlay at
src/arm/CustomCape-00A0.dts by hacking together pieces from BBORG_MOTOR-00A2.dts and RoboticsCape-00A0.dts
/*
* Device Tree Overlay for custom cape trying to reuse Robot Control Library's
* reading of 4x optical encoders.
*/
/*
pinmux control byte map courtesy of http://beaglebone.cameon.net/
Bit 5: 1 - Input, 0 - Output
Bit 4: 1 - Pull up, 0 - Pull down
Bit 3: 1 - Pull disabled, 0 - Pull enabled
Bit 2 \
Bit 1 |- Mode
Bit 0 /
*/
/dts-v1/;
/plugin/;
/ {
compatible = "ti,beaglebone-black";
/* identification */
part-number = "CustomCape";
/* version */
version = "00A0";
exclusive-use =
"P8.11", /*QEP_2B*/
"P8.12", /*QEP_2A*/
"P8.16", /*PRU_ENCODER_A*/
"P8.33", /*QEP_1B*/
"P8.35", /*QEP_1A*/
"P9.27", /*QEP_0B*/
"P9.41", /*MOT_STBY*/
"P9.42"; /*QEP_0A*/
/*
* Helper to show loaded overlays under: /proc/device-tree/chosen/overlays/
*/
fragment#0 {
target-path="/";
__overlay__ {
chosen {
overlays {
CustomCape-00A0 = __TIMESTAMP__;
};
};
};
};
fragment#1 {
target = <&am33xx_pinmux>;
__overlay__ {
/****************************************
* pinmux helper
****************************************/
mux_helper_pins: pins {
pinctrl-single,pins = <
/* EQEP */
0x1A0 0x31 /* P9_42,EQEP0A, MODE1 */
0x1A4 0x31 /* P9_27,EQEP0B, MODE1 */
0x0D4 0x32 /* P8_33,EQEP1B, MODE2 */
0x0D0 0x32 /* P8_35,EQEP1A, MODE2 */
0x030 0x34 /* P8_12,EQEP2A_in, MODE4 */
0x034 0x34 /* P8_11,EQEP2B_in, MODE4 */
/* PRU encoder input */
0x03c 0x36 /* P8_15,PRU0_r31_15,MODE6 */
0x1ac 0x36 /* P9_25,PRU0_r31_7,MODE6 */
>;
};
};
};
/****************************************
Pinmux Helper
activates the pinmux helper list of pin modes
****************************************/
fragment#2 {
target = <&ocp>;
__overlay__ {
test_helper: helper {
compatible = "bone-pinmux-helper";
pinctrl-names = "default";
pinctrl-0 = <&mux_helper_pins>;
status = "okay";
};
};
};
/*
* Free up the pins used by the cape from the pinmux helpers.
*/
fragment#3 {
target = <&ocp>;
__overlay__ {
P8_11_pinmux { status = "disabled"; }; /* enc3b */
P8_12_pinmux { status = "disabled"; }; /* enc3a */
P8_15_pinmux { status = "disabled"; }; /* enc4b */
P8_33_pinmux { status = "disabled"; }; /* enc0 */
P8_35_pinmux { status = "disabled"; }; /* enc0 */
P9_25_pinmux { status = "disabled"; }; /* enc4a */
P9_27_pinmux { status = "disabled"; }; /* enc1b */
P9_92_pinmux { status = "disabled"; }; /* enc1a */
};
};
/****************************************
Encoders
****************************************/
fragment#9 {
target = <&eqep0>;
__overlay__ {
count_mode = <0>; /* 0 - Quadrature mode, normal 90 phase offset cha & chb. 1 - Direction mode. cha input = clock, chb input = direction */
swap_inputs = <0>; /* Are channel A and channel B swapped? (0 - no, 1 - yes) */
invert_qa = <1>; /* Should we invert the channel A input? */
invert_qb = <1>; /* Should we invert the channel B input? I invert these because my encoder outputs drive transistors that pull down the pins */
invert_qi = <0>; /* Should we invert the index input? */
invert_qs = <0>; /* Should we invert the strobe input? */
status = "okay";
};
};
fragment#10 {
target = <&eqep1>;
__overlay__ {
count_mode = <0>; /* 0 - Quadrature mode, normal 90 phase offset cha & chb. 1 - Direction mode. cha input = clock, chb input = direction */
swap_inputs = <0>; /* Are channel A and channel B swapped? (0 - no, 1 - yes) */
invert_qa = <1>; /* Should we invert the channel A input? */
invert_qb = <1>; /* Should we invert the channel B input? I invert these because my encoder outputs drive transistors that pull down the pins */
invert_qi = <0>; /* Should we invert the index input? */
invert_qs = <0>; /* Should we invert the strobe input? */
status = "okay";
};
};
fragment#11 {
target = <&eqep2>;
__overlay__ {
count_mode = <0>; /* 0 - Quadrature mode, normal 90 phase offset cha & chb. 1 - Direction mode. cha input = clock, chb input = direction */
swap_inputs = <0>; /* Are channel A and channel B swapped? (0 - no, 1 - yes) */
invert_qa = <1>; /* Should we invert the channel A input? */
invert_qb = <1>; /* Should we invert the channel B input? I invert these because my encoder outputs drive transistors that pull down the pins */
invert_qi = <0>; /* Should we invert the index input? */
invert_qs = <0>; /* Should we invert the strobe input? */
status = "okay";
};
};
/****************************************
PRU
****************************************/
fragment#31 {
target = <&pruss>;
__overlay__ {
status = "okay";
};
};
};
I added my custom overlay to /boot/uEnv.txt and disabled the video and audio overlays
uname_r=4.19.94-ti-r42
#uuid=
#dtb=
###U-Boot Overlays###
###Documentation: http://elinux.org/Beagleboard:BeagleBoneBlack_Debian#U-Boot_Overlays
###Master Enable
enable_uboot_overlays=1
###
###Additional custom capes
uboot_overlay_addr4=/lib/firmware/CustomCape-00A0.dtbo
###
###Custom Cape
#dtb_overlay=/lib/firmware/<file8>.dtbo
###
###Disable auto loading of virtual capes (emmc/video/wireless/adc)
#disable_uboot_overlay_emmc=1
disable_uboot_overlay_video=1
disable_uboot_overlay_audio=1
#disable_uboot_overlay_wireless=1
#disable_uboot_overlay_adc=1
###
###PRUSS OPTIONS
###pru_rproc (4.19.x-ti kernel)
uboot_overlay_pru=/lib/firmware/AM335X-PRU-RPROC-4-19-TI-00A0.dtbo
###
###Cape Universal Enable
enable_uboot_cape_universal=1
###
###U-Boot Overlays###
cmdline=coherent_pool=1M net.ifnames=0 lpj=1990656 rng_core.default_quality=100 quiet
I make no claims of optimality or even correctness, but this configuration boots with or without the Motor Cape
installed and I can read all four encoders with rc_test_encoders. When the Motor Cape is installed, uBoot
is correctly picking up and applying the BBORG_MOTOR-00A2 overlay. I honestly thought that I would need a lot more
configuration of the PRU to get the PRU-based encoder counter from the Robot Control Library working, but this seeems
to do the trick.
I would welcome any feedback on how I should have done this, or how I could improve upon what I currently have.
Helpful Tip: Watch the serial terminal!
I am embarrassed that I even attempted to debug device tree booting issues without first having a serial terminal
open to the beaglebone so that I could observe the boot sequence. With the help of some 5-minute epoxy, I was
eventually able to make a 90-degree header to bring the JTAG port out from under an installed cape.
https://elinux.org/Beagleboard:BeagleBone_Black_Serial