random-mirrors/easytarget-MQ-Pro-IO
1
0
Fork 0
mirror of https://github.com/easytarget/MQ-Pro-IO.git synced 2025-10-13 17:25:52 +01:00
Code Issues Packages Projects Releases Wiki Activity

doc work

Browse Source
This commit is contained in:
Owen 2024-08-30 15:25:40 +02:00
parent fe4de5e43d
commit 53f4de3e3e
5 changed files with 106 additions and 192 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
README.md
View File

@ -1,12 +1,11 @@
# 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.
### The MQ pro is a single core RISC-V allwinner D1 64bit 1Ghz, 1Gb SBC, in a Pi-Zero form factor.
## This is a guide for enabling bluetooth and using the MangoPi MQ pro's IO capabilities when running Ubuntu 24.04.1
-----------------------------
# WORK IN PROGRESS
# Currently being re-written for the 24.04.1 release.
## There are also major changes to how the device tree is handled
# (STILL) A WORK IN PROGRESS
- Currently being re-written for the 24.04.1 release.
`24.04.1` is a LTS+ release from Ubuntu, and should provide 5+ years of updates. As such it makes a good choice for an unattended headless device.
@ -21,7 +20,6 @@ Once the Lichee image is booted you can swap the device tree it uses for the MQ-
-----------------------------
This is a guide for enabling bluetooth and using the MangoPi MQ pro's IO capabilities when running Ubuntu 24.04.1
## Installing Ubuntu
There is *no* specific image provided by Ubuntu for the MQ PRO, but they *do* provide an image for the 'Sipeed Lichee RV' which installs and boots on the MQ Pro with almost everything working.
@ -29,13 +27,13 @@ There is *no* specific image provided by Ubuntu for the MQ PRO, but they *do* pr
- I had issues getting a successful first boot with a cheap SD card, using a brand-name (Kingston) high speed card solved all the issues.
- I am also using a high wear resistance card since I want this to run for years in a hard-to-reach location.
- EXPAND!!!,
notes about hdmi console, usb ethernet adapters, presetup wifi etc.
`
The HDMI console with a USB kbd and mouse works well, install `gpm` to get a working mouse in it. Once i had bluetooth working I was able to attach and use a bluetooth kbd+mouse.
- EXPAND!!!,
notes about hdmi console, usb ethernet adapters, presetup wifi etc.
### steps:
--- See the raw log at the end of this doc.
- AT PRESENT: See the raw log at the end of this doc.
<EDITED LOG HERE>
# My Motivation:

86
alt-trees/README.md
View File

@ -1,6 +1,14 @@
# Precompiled device trees:
Each folder contains a `.dtb` file, which is the compiled device tree itself, plus a `.dts` with the original source and a `.gpio` file showing the GPIO pin mappings.
# Alternate pre-populated device trees:
Each folder contains a `.dts` file and a README showing the GPIO pin mappings.
Copy the desired '.dts' file to the [build-trees](../build-trees) folder and follow the readme there to build the device-tree binaries.
There are instructions at the end of that document on how you can use a custom 'dtb' and make it permanent across reboots and kernel upgrades.
The issue with using these trees is that **if** the upstream device tree or includes is modified you need to manually rebuild these trees, and any changes to the upstream <FIX THIS: WHICH IS THE SOURCE??> file need to be detected and applied too.
- Fortunately this should not be an issue in practice; the kernel *should* remain very stable going forward. Ubuntu 24.04.1 is a LTS release..
The authors personal advice is to use this only if needed; or as a learning excercise.
## Common
[The common (generic) device tree I will use in my project, suitable for many occasions](./common)
@ -17,77 +25,3 @@ Each folder contains a `.dtb` file, which is the compiled device tree itself, pl
[SPI plus Serial interfaces](./spi)
* Has 3x UART (plus the console uart), 3x I2C. 1xSPI
* 8 unassigned GPIO pins
## SunXI
[Vanilla, unpopulated, upstream](./sunxi)
* Has the console uart, nothing more
*26 unassigned GPIO pins!*
## AllWinner Nezha
[DO NOT USE](./allwinner-nezha)
* 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
# Getting the DTB files
Clone this repo:
```console
$ git clone https://github.com/easytarget/MQ-Pro-IO.git
$ cd MQ-Pro-IO
```
# Install the Device Tree
Installing is, in principle, 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.
```console
$ sudo cp precompiled-trees/generic/6.8.0-31-generic.dtb /boot/dtbs/
$ cd /boot
$ sudo ln -s dtbs/6.8.0-31-generic.dtb dtb-mqpro
```
Finally, edit the `/boot/grub/grub.cfg` file to use the new DTB for the default 'Ubuntu' target:
* `sudo vi /boot/grub/grub.cfg`
* Look for the first block that begins with: `menuentry 'Ubuntu'`
* Comment out the existing entry and add a new one:
```console
# devicetree /boot/dtb-6.8.0-31-generic
devicetree /boot/dtb-mqpro
```
Reboot!
After rebooting you can run **list-pins.py** (see below) 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 recovery image, or, in grub, edit the command and revert to the generic `/boot/dtb`.
As a last resort you may have to remove the SD card, mount the `/boot` partition and edit `grub/grub.cfg` there.
* !! The 'default' dtb supplied by ubuntu should always be softlinked as `/boot/dtb`, so putting `devicetree /boot/dtb` in grub in place of the custom `.dtb` should work and is predictable (no version numbers etc).
## Examining the 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`
* This produces the same map I use in the documentation and `.gpio` files in the folders above.
* The data used to assemble the `.gpio` map files identifies which interface a pin is attached to, but not it's specific function for the interface.
* eg it can say 'pinX and pinY are mapped to UART2', but cannot identify which pin is the TX and which is the RX; a limitation of the data, my apologies..
* You therefore need to reference the [D1 pin mapping table](../reference/d1-pins.pdf) to get the exact functions for pins when running this for yourself.
* The `.gpio` files uploaded here *have* been manually edited to note full pin function for convenience.
# 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
```
When Grub next rebuilds it *should* make the new DTB the default for all entries now. (this is untested, as of this writing there have not been any kernel upgrades to test them on)

33
alt-trees/sun20i-d1-mangopi-mq-pro/README.md
View File

@ -1,33 +0,0 @@
```
MangoPI MQ Pro GPIO header (dtb name: MangoPi MQ Pro)
Gpio Header:
func des pin pin des func
3v3 1 --o o-- 2 5v
free (205) PG13 3 --o o-- 4 5v
free (204) PG12 5 --o o-- 6 gnd
free (39) PB7 7 --o o-- 8 PB8 uart0.tx (2500000.serial:40)
gnd 9 --o o-- 10 PB9 uart0.rx (2500000.serial:41)
free (117) PD21 11 --o o-- 12 PB5 free (37)
free (118) PD22 13 --o o-- 14 gnd
free (32) PB0 15 --o o-- 16 PB1 free (33)
3v3 17 --o o-- 18 PD14 free (110)
free (108) PD12 19 --o o-- 20 gnd
free (109) PD13 21 --o o-- 22 PC1 free (65)
free (107) PD11 23 --o o-- 24 PD10 free (106)
gnd 25 --o o-- 26 PD15 free (111)
free (145) PE17 27 --o o-- 28 PE16 free (144)
free (42) PB10 29 --o o-- 30 gnd
free (43) PB11 31 --o o-- 32 PC0 free (64)
free (44) PB12 33 --o o-- 34 gnd
free (38) PB6 35 --o o-- 36 PB2 free (34)
free (113) PD17 37 --o o-- 38 PB3 free (35)
gnd 39 --o o-- 40 PB4 free (36)
Other gpio outputs of interest:
-- PD18: Blue Status Led - free (114)
Notes:
- I2C pins 3,5,27 and 28 (PG13, PG12, PE17 and PE16) have 10K pullup resistors to 3v3
- The Status LED (PD18) is common with the LED_PWM pin on the DSI/LVDS output
```

33
alt-trees/sun20i-d1-nezha/README.md
View File

@ -1,33 +0,0 @@
```
MangoPI MQ Pro GPIO header (dtb name: Allwinner D1 Nezha)
Gpio Header:
func des pin pin des func
3v3 1 --o o-- 2 5v
free (205) PG13 3 --o o-- 4 5v
gpio (2000000.pinctrl:204) PG12 5 --o o-- 6 gnd
free (39) PB7 7 --o o-- 8 PB8 uart0.tx (2500000.serial:40)
gnd 9 --o o-- 10 PB9 uart0.rx (2500000.serial:41)
gpio (2000000.pinctrl:117) PD21 11 --o o-- 12 PB5 free (37)
free (118) PD22 13 --o o-- 14 gnd
i2c2.sck (2502800.i2c:32) PB0 15 --o o-- 16 PB1 i2c2.sda (2502800.i2c:33)
3v3 17 --o o-- 18 PD14 spi1.hold (4026000.spi:110)
spi1.mosi (4026000.spi:108) PD12 19 --o o-- 20 gnd
spi1.miso (4026000.spi:109) PD13 21 --o o-- 22 PC1 free (65)
spi1.clk (4026000.spi:107) PD11 23 --o o-- 24 PD10 spi1.cs (4026000.spi:106)
gnd 25 --o o-- 26 PD15 spi1.wp (4026000.spi:111)
free (145) PE17 27 --o o-- 28 PE16 free (144)
free (42) PB10 29 --o o-- 30 gnd
free (43) PB11 31 --o o-- 32 PC0 ledc (2008000.led-controller:64)
free (44) PB12 33 --o o-- 34 gnd
free (38) PB6 35 --o o-- 36 PB2 free (34)
free (113) PD17 37 --o o-- 38 PB3 free (35)
gnd 39 --o o-- 40 PB4 free (36)
Other gpio outputs of interest:
-- PD18: Blue Status Led - free (114)
Notes:
- I2C pins 3,5,27 and 28 (PG13, PG12, PE17 and PE16) have 10K pullup resistors to 3v3
- The Status LED (PD18) is common with the LED_PWM pin on the DSI/LVDS output
```

128
build-trees/README.md
View File

@ -1,43 +1,56 @@
# NOTE
# Being refactored at the moment. I want to make sure the dtsi and generic image are taken for currnet kernel;
## Ignore this: (until I properly update, some of this needs moving to source/README.md)
## Preparation / requirements
### Compile and make tooling
You need `build-essential` installed:
```console
# Install build-essentials (lots of packages, will take some time)
apt install build-essentials
apt install build-essential`
```
*This will take a while.. as will most commands described here!*
# Enable source repos:
# As root edit the file: /etc/apt/sources.list.d/ubuntu.sources
# There should be two repo definitions, for both find the lines that say:
By default the Device Tree compiler (`/usr/bin/dtc`) should already be installed in Ubuntu server, as should the linux-headers for the kernel.
### Enable source repos:
As root edit the file: `/etc/apt/sources.list.d/ubuntu.sources`
There should be two repo definitions, find the lines in them that say:
```console
Types: deb
# add 'deb-src' so it now says
```
And add `deb-src` so it now says:
```console
Types: deb deb-src
# Save and exit editor.
```
Save and exit editor.
# As root, run
apt update
# you should see a load of new (source) repos being updated.
# - adding all these source repos slows apt down,
# not much that can be done about this on such a slow machine.
Run
```console
sudo apt update
```
You should see a load of new (source) repos being updated, it is slow, let it finish.
# Now we can install the linux sources
# This can be done as a normal user
# note that the command used here `apt source` will download the sources to the current working folder, not a fixed location.
## Install the linux sources
This can be done as a normal user
- Note that the command used here `apt source` will download the sources to the current working folder, not a fixed location.
We download the sources into the [sources](../sources) repo in this folder:
```console
cd source
apt source linux-riscv
# Go for a coffee.. ignore the 'git clone' suggestion.
# This will take some time, and place the sources in the current
# directory.
# It will use ~1.6Gb of space.. so be prepared..
# If you re-run the command in this folder it will only update as needed, but is still somewhat slow since it verifies the existing downloads when updating.
```
Go for a coffee.. unless you are a developer you can ignore the 'git clone' suggestion.
- This will use ~1.6Gb of space.. so be prepared.
# Updating sources
If you re-run the command in this folder it will only download and update as needed, but is still somewhat slow since it verifies the existing downloads when updating.
----------------------------------------------------
# Rebuild dts tree for MQ pro..
### The following is wrong! It will be updated asap
```
Start by `cd`'ing into this [device tree](device-tree) folder and editing your device tree.
You can use the generic `sun20i-d1-mangopi-mq-pro.generic.dts` already in the device tree folder as a basis, or start with one of the ones provided with my precompiled trees.
@ -45,6 +58,7 @@ You can use the generic `sun20i-d1-mangopi-mq-pro.generic.dts` already in the de
You may also need to modify `sun20i-d1.dtsi` since this is where pin mappings are declared; eg UART pin sets are defined in this include file and then used in the main tree file.
A full-on tutorial for device tree editing is far beyond the scope of both this document and author.
```
#### Terms
* `.dts` is a top-level Device Tree Source file.
@ -52,15 +66,15 @@ A full-on tutorial for device tree editing is far beyond the scope of both this
* `.dtb` is the binary compiled device tree, this is what we are building here, and is supplied to the kernel at boot time.
## Building the MQ PRO device tree (`.dtb`)
By default the Device Tree compiler (`/usr/bin/dtc`) should already be installed in Ubuntu server, as should the linux-headers for the kernel.
## Compile the mq-pro dts with the current kernel headers
Example here is against the 'default' 6.8.0-31 linux kernel from the Ubuntu 24.04 release
* cd into the `dtspp` folder and clean: `rm *.dts *.dtsi`
* run `preprocess.sh` to precompile the files in the parent folder against the latest linux-headers.
* still in the `dtspp` folder run:
```dtc sun20i-d1-mangopi-mq-pro.generic.dts > dtb-6.8.0-31-mqpro-generic.dtb```
modify the version to reflect the current headers
<Describe `make-trees.sh`>
-----------------------
# Test Installing self-built DTB's
### Move dtb into the boot tree
* move the `.dtb` file into the `/boot` folder:
`sudo mv dtb-6.8.0-31-mqpro-generic /boot/dtbs`
* make a soft link in `/boot` to this:
@ -76,29 +90,63 @@ Initially we will test the new dtb:
* If the reboot fails you can either attach a serial adapter to the GPIO pins and select the fallback kernel from the advanced options menu, and then restore the grub config backup once logged in.
Or (if no serial available) remove the SD card, mount it on another computer and restore the file there.
### Check that we have the correct device tree
### Quick check that we have the correct device tree!
`dtc -I fs /sys/firmware/devicetree/base | grep 'model'`
* ignore all the 'not a phandle reference' warnings
* you should see `model = "MangoPi MQ Pro"` at the end
### Make this permanent in grub
This is covered in the 'precompiled trees' readme [here](../precompiled-trees#making-permanent).
----------------------------------------------------
## Pin Map tool
After rebooting you can run **list-pins.py** (see below) to verify the new mappings.
### Bonus
The onboard (blue) status LED can be controlled via the sys tree:
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 recovery image, or, in grub, edit the command and revert to the generic `/boot/dtb`.
As a last resort you may have to remove the SD card, mount the `/boot` partition and edit `grub/grub.cfg` there.
* !! The 'default' dtb supplied by ubuntu should always be softlinked as `/boot/dtb`, so putting `devicetree /boot/dtb` in grub in place of the custom `.dtb` should work and is predictable (no version numbers etc).
`sudo sh -c "echo 1 > /sys/devices/platform/leds/leds/blue\:status/brightness"` to turn on
## Examining the DTB pin mappings:
In the [tools](../tools) folder there is a python script called `list-pins.py`.
`sudo sh -c "echo 0 > /sys/devices/platform/leds/leds/blue\:status/brightness"` to turn off
To run the pin list tool you need to be in the tools directory, then run:
```console
python3 list-pins.py MangoPi-MQ-Pro
```
* The script requires root acces (via sudo) to read the pin maps.
* Running the script produces the same map I use in this documentation.
* The data used to assemble the `.gpio` map files identifies which interface a pin is attached to, but not it's specific function for the interface.
* eg it can say 'pinX and pinY are mapped to UART2', but cannot identify which pin is the TX and which is the RX; a limitation of the data, my apologies..
* You therefore need to reference the [D1 pin mapping table](../reference/d1-pins.pdf) to get the exact functions for pins when running this for yourself.
* The README files uploaded for alternate device trees *have been manually edited* to note full pin function for convenience.
-----------------------------------------------------
You can make it flash as wifi traffic is seen with:
# Making Permanent:
<this needs expanding/fixing>
<can we do this via flash-kernel? it appears to have an 'override' dtb file config. ?????>
## Old method
(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
```
When Grub next rebuilds it *should* make the new DTB the default for all entries now. (this is untested, as of this writing there have not been any kernel upgrades to test them on)
`sudo sh -c "echo phy0rx > /sys/devices/platform/leds/leds/blue\:status/trigger"`
# references/links:
https://manpages.ubuntu.com/manpages/focal/man1/dtc.1.html
https://forum.armbian.com/topic/29626-mango-pi-mq-pro-d1-device-tree-try-to-okay-serial/
https://github.com/torvalds/linux/tree/master/arch/riscv/boot/dts/allwinner
https://github.com/ners/MangoPi/tree/d2589d8211a2f9ae57d88f2e2c4d6a449d668f9e/MangoPi/linux/arch/riscv/boot/dts/allwinner
DTS version that is used in the official armbian image?
DTS version that is used in the official armbian image?
https://github.com/smaeul/u-boot/tree/329e94f16ff84f9cf9341f8dfdff7af1b1e6ee9a/arch/riscv/dts