Hardware IO: BeagleBone Black

Using hardware I/O on the BeagleBone Black is a bit complex, since the hardware itself is complex.

Since the BeagleBone's pins have multiple possible uses, you need to select the pin mode you'd like to use before you attempt to use the pins. This is done using a complex Linux feature called device tree overlays, which instruct both the hardware and Linux kernel how to make pins behave, and how they should be operated.

This is a very complex system, and we spent a ton of time getting Scarlet to be able to take care of most of the work for you. That functionality is primarily in the BBBPinManager and BBBPin classes.

As far as we have been able to find, Scarlet seems to be the only library that has the ability to custom-generate device tree overlays on the fly.

Preparation

Before you apply the device tree overlay, you need to tell BBBPinManager about all of the pins you want to use, and how you want to use them. We very strongly recommend that you lay these all out near beginning of program execution, and do not attempt to change them once the overlay has been applied. More on that in the Removal section below. To add pin usages, simply call the relevant method. They are outlined on each of the Using pages, but here's a simple example for ADC:
BBBPinManager.AddMappingADC(BBBPin.P9_36);

This simply adds the pin to BBBPinManager's internal list of pin assignments. The pin is not ready for use until you generate and apply the device tree overlay. If you attempted to initialize an AnalogueInBBB object with this pin before then, you would receive an exception.

Application

Sometime between your program beginning execution, and you needing to use GPIO/SPI/I2C/ADC/etc pins, you need to generate and apply the device tree overlay. This is done by a (single) call to this method:
BBBPinManager.ApplyPinSettings();

If you do not need to make changes to the device tree, for example if this is the second time your program is running with no pin assignment changes, you must still call ApplyPinSettings()! It also initializes internal data structures and objects for PWM, I2C, SPI, etc to be usable. Just use the appropriate application mode as below:

Here's an explanation of the different application modes:

Mode	Applied if no DT present?	Applied if Scarlet DT present?	Explanation
NO_CHANGES	No	No	This commits changes only to Scarlet's internal systems, and does not attempt to make changes to the device tree. This is useful if you have applied the overlay previously, don't need any changes, but want to run your program repeatedly.
APPLY_IF_NONE	Yes	No	Only applies the device tree if this is the first time a Scarlet application has run on the device since reboot. This is the recommended mode. You will need to reboot the BBB or use a different mode if you are actively developing your application and need to change/add pin assignments.
REMOVE_AND_APPLY	Yes	Yes (Previous removed)	This will remove all previous Scarlet DTs (Please read the below section on Removal!), then apply the current device tree. This is not recommended.
APPLY_REGARDLESS	Yes	Yes (Previous left)	This will leave previous Scarlet DTs in place, and simply add the new one if it is different. This is preferred over REMOVE_AND_APPLY, but may still cause strange behaviour. Reboot if things are not working correctly.

This method can take a bit of time to complete, as it needs to do quite a bit of work, and then it will wait until the kernel finishes setting up devices and processing the changes before returning execution. Usually it will be 10-200ms.

Once this is done, you are ready to initialize GPIOs, ADC lines, sensors, and other items that use the hardware.

Removal (Danger!) 🛑

The big problem with device tree overlays, is that once applied, they cannot be changed, and removing one is problematic at best.
Removing a device tree overlay can be done with this method, but read the following warnings before doing so:
BBBPinManager.RemovePinSettings();

Note that Scarlet does not remove device tree overlays upon exiting. If you edit your code to use a different pin or change how a pin is used, you can try to apply the new overlay on top of the old one, attempt to remove the old one, or (preferably) reboot the BBB first.

⚠️ WARNINGS:

• Removing a device tree overlay can cause system instability, kernel panic (like a blue screen on Windows), or cause unexpected and undefined behaviour.
• Removing a device tree overlay that contains SPI or I2C-related settings seems to always cause a kernel panic.
• The only reliable and supported way to remove a device tree overlay is to reboot the BeagleBone.

Other notes:

• This will remove all Scarlet device tree overlays.
• These issues do not appear to be limited to Scarlet or the current version of the BBB OS. It has been a known issue for a while, and fixing it requires an immense amount of effort on the BBB/Debian developers. As such, it does not appear to be a priority for them.
• Other libraries will simply leave device tree overlays applied, and add more if needs change. Most do not even have functionality for removing overlays.