usage notes

README.md

@@ -1,7 +1,7 @@
 # MangoPI MQ Pro Device Trees for Bluetooth and GPIO
 ### The MQ pro is a single core allwinner D1 64bit 1Ghz, 1Gb risc-v based Pi-Zero-alike.
 
-This is a guide for enableing bluetooth and using the MangoPi MQ pro's IO capabilities when running Ubuntu 24.04.
+This is a guide for enabling bluetooth and using the MangoPi MQ pro's IO capabilities when running Ubuntu 24.04.
 
 `24.04` is a LTS+ release from Ubuntu, and should provide 5+ years of updates etc. As such it makes a very good choice for this board as a unattended headless device.
 
@@ -32,9 +32,8 @@ My MQ PRO is connected to a Waveshare LORA hat, I want to make it work but the d
 # Device Trees
 TODO: general explanation,
 
-My pre-compiled device-trees are in the [here](./precompiled-trees). 
-- I still need to firm up and document how to deploy them!
-- I still need to work out how to make this all permanent and able to survive a kernel upgrade.
+My pre-compiled device-trees are in the [here](./precompiled-trees), along with install notes.
+- I may modify this in the future as I learn how to handle kernel upgrades properly, my current install method is probably sub-optimal. But it should work.
 
 ## Roll Your Own Device Tree
 Hopefully you can find what you want in the precompiled trees, or use the vanilla tree and dynamically create your devices on it via PinCTL.
@@ -47,6 +46,9 @@ You need one of the new device trees provided (*except the original Nezha one*)
 Once that is in place you still need the correct firmware for this particular device, a copy of this is in the [bluetooth firmware](./bt-fw) folder.
 * Copy the two firmware (`.bin`) files to `/usr/lib/firmware/` on the MQ PRO and reboot.
 
+# Using GPIO
+This is beyond the scope of this document, I use GPIOd to do this. But have also used direct pinmux control via the `/sys/class/gpio` tree.
+
 # Allwinner D1 GPIO pins
 The **D1** SOC runs at 3v3, and you must not exceed this on any of the GPIO pins. The drive current is also very limited, a maximum of 4mA on any individual pin, and 6mA total across a bank of pins (eg the 12 pins in the `*PB*` bank combined cannot draw more than 6mA!).
 

precompiled-trees/README.md

@@ -27,3 +27,38 @@ Each folder contains a `.dtb` file, which is the compiled device tree itself, pl
 * Included for completeness, this is the default device tree you get with the Ubuntu image.
 * Has the console uart, 1x I2C. 1xSPI
 * 15 unassigned GPIO pins, 3 pre-assigned to pinctl
+
+# Examining the current DTB pin mappings:
+In the [tools](../tools) folder there is a python script called `list-pins.py`.
+
+To run it you need to be in that directory, then run `python3 list-pins.py MangoPi-MQ-Pro` to see a map of the current pin assignments (the same map I use in `.gpio` files in the folders above.) 
+
+# Install and use
+Installing is simple, clone this repo on to the MQ pro and, as root, copy the desired `.dtb` file to the `/boot/dbts` folder.
+
+Then make a soft link in the root of the /boot folder named `dtb-mqpro` that points to the file you just copied.
+
+Finally, edit the `/boot/grub/grub.cfg` file to use the new DTB for the default 'Ubuntu' target.
+
+Reboot!
+
+After rebooting you can re-run **list-pins.py** from above to verify the new mappings.
+
+If you have errors rebooting (maybe a corrupt file if you rebuilt it etc..) you need to either boot using a USB serial adapter on the console pins and select the recover image (or edit the command and revert to the generic `.dtb`). Or remove the SD card, mount the /boot partition and edit the `grub/grub.cfg` file there.
+
+## Making Permanent:
+(As Root) Edit: `/etc/grub.d/10_linux` line 458 to say:
+```
+  for i in "dtb-mqpro" "dtb-${version}" "dtb-${alt_version}" "dtb"; do
+```
+
+Note that we are adding `dtb-mqpro` to the start of this list, this is the 'search list' for the DTB files, the full section reads:
+```bash
+  dtb=
+  for i in "dtb-mqpro" "dtb-${version}" "dtb-${alt_version}" "dtb"; do
+    if test -e "${dirname}/${i}" ; then
+      dtb="$i"
+      break
+    fi
+  done
+```