PINE64 - User contributions [en]

User:Talpa/Using rkdeveloptool

2023-01-15T20:10:40Z

Talpa: Information about sending the SPL when in Maskrom mode

= Using rkdeveloptool =

rkdeveloptool is a command line tool that can communicate with a some Rockchip SOCs like the RK3566 in the PineNote when they are in Maskrom/Rockusb mode.

rkdeveloptool can among other things read and write to the eMMC inside the PineNote.

It is therefor useful for [[PineNote_Development/Backup | backups]] and installing an OS to the PineNote.

== About the boot process of the PineNote ==
When the RK3566 is powered on it checks the attached storage devices in the ''boot order'':

* SPI NOR flash
* SPI NAND flash
* eMMC
* SD-Card

In the case of the PineNote there is only the eMMC.

If the SOC finds a storage device with a valid ID BLOCK it proceeds to boot from the device.

If no usable storage device is found the ROM in the SOC enters Maskrom mode and awaits a connection over USB

The PineNote additionally has a magnet sensor that is read by U-Boot during startup and if it detects a magnet U-Boot places the device in USB download mode

== Compiling rkdeveloptool ==

Pine64 develops a [https://gitlab.com/pine64-org/quartz-bsp/rkdeveloptool forked version] of the rkdeveloptool by RockChip, the following describes how to build the fork:

You will need to have ''libusb 1.0'', its development headers and ''scdoc'' installed.

git clone https://gitlab.com/pine64-org/quartz-bsp/rkdeveloptool.git
cd rkdeveloptool
mkdir build
cd build
cmake ..

This sets up all the build files. You can then compile with <code>make</code> inside the build directory.

After you're done, you'll likely also need to install the udev rules, or else your user won't have permission to access the USB devices:

sudo cp 99-rk-rockusb.rules /etc/udev/rules.d/
sudo udevadm control --reload

Copying the udev rules is also performed automatically when you <code>make install</code>.

== Entering Maskrom/Rockusb Mode ==

There are three ways to get into Maskrom/Rockusb mode:

The first two will result in Rockusb mode where drivers for the eMMC are loaded and rkdeveloptool can be used without further action.
This mode can be identified by ''Loader'' in the output when running <code>rkdeveloptool list</code>
rkdeveloptool list
DevNo=1 Vid=0x2207,Pid=0x350a,LocationID=402 Loader

The last method is used to recover from a bad u-boot and leaves the device in ''Maskrom''.
Here rkdevelop must first be used to upload the loader code with the driver for the eMMC.
This mode can be identified by ''Maskrom'' in the output when running <code>rkdeveloptool list</code>
rkdeveloptool list-devices
DevNo=1 Vid=0x2207,Pid=0x350a,LocationID=10e Maskrom

=== The magnet way ===

[[File:PineNoteMagnetOnBack.jpg|right|500px|PineNote with magnet on circle]]

# Remove the USB-C cable if connected
# Turn the PineNote off (press the power button for 5 seconds), and flip it around so that the display faces down
# Place a magnet in the correct place on the back of the PineNote, use one of the following methods:
#* Place a magnet on the small circle printed on the back, the pens magnetic cap can be used for this.
#* Lay the pen on the right side, with its tip pointing towards the speaker grill, and its magnet pointing towards the upper right corner of the label on the back (or place the magnetic cap from the pen on the spot marked on the back).
# Connect the PineNote to the PC using a USB-C cable, this will wake it up and boot. Wait for it to show up in <code>lsusb</code>.

It should now be in Loader mode, according to <code>rkdeveloptool list-devices</code> (note that ''Loader'' here indicates U-Boot's Rockusb; separately, booting with an erased eMMC displays ''Maskrom'' (not ''Loader'') from the RK3566).

In case it doesn't work the first time just try again.

=== The U-Boot way ===
# Interrupt the U-Boot startup using ''ctrl-c'' (while attached using an UART dongle)
# While in U-Boot use the command <code>rockusb 0 mmc 0</code> to start Rockusb mode.

One benefit from this is, that if you have an UART dongle that allows to simultaneous having an UART and USB connection, there is no need to plug and unplug cables and flipping the PineNote around and placing magnets.

This is especially helpful when changing back and forth between U-Boot and Rockusb, for example when trying to develop on U-Boot.

=== Shorting test points ===
{{Warning | This has the potential to damage you PineNote}}

If the bootloader is broken/corrupted, you cannot get to Maskrom without opening up the device (it can be opened using spudger and a bit of patience).

Ensure the device is off by pressing and holding the power button for 5 seconds.

Once inside, short TP1301 (GND) and TP1302 (eMMC_D0/FLASH_D0), this is how it looks on board view (credit to Caleb):

[[File:PineNote_Maskrom_TP.png|500px]]

Perform the short using one of:
* A small tweezers
* The programming pogo pins for a PineTime (mask the two unused pins with tape), the spring loaded nature of pogo pins helps getting a good contact
When shorting the test pads take great care to not short / touch other components or scratch the PCB as this '''may damage your PineNote'''.

While keeping the test pads shorted plug the device to the computer and if you see the device with VID=2207/PID=350a then it should be in Maskrom mode, you can verify by typing <code>rkdeveloptool list-devices</code>.

Jan 07 15:04:13 melttower kernel: usb 1-14: New USB device found, idVendor=2207, idProduct=350a, bcdDevice= 1.00
Jan 07 15:04:13 melttower kernel: usb 1-14: New USB device strings: Mfr=0, Product=0, SerialNumber=0

$ rkdeveloptool list-devices
DevNo=1 Vid=0x2207,Pid=0x350a,LocationID=10e Maskrom

==== Sending the loader to the RK3566 (Not needed in "Loader"/rockusb mode) ====
In Maskrom you must first send a SPL (Secondary program loader) with contains the drivers for accessing the eMMC.

The spl_loader .bin file can be obtained by compiling the downstream u-boot, the version number may or may not match the one displayed below depending on the sources used.

The spl .bin file is send and executed using the ''rkdeveloptool boot'' command, see below:

rkdeveloptool boot rk356x_spl_loader_v1.08.111.bin

This should output "Downloading bootloader succeeded".

We can now verify that this worked using e.g. the "read flash info" command:

rkdeveloptool read-flash-info

[[Category:PineNote]]

User:Talpa/Using rkdeveloptool

2023-01-15T19:55:25Z

Talpa: Mentions the two different modes

= Using rkdeveloptool =

rkdeveloptool is a command line tool that can communicate with a some Rockchip SOCs like the RK3566 in the PineNote when they are in Maskrom/Rockusb mode.

rkdeveloptool can among other things read and write to the eMMC inside the PineNote.

It is therefor useful for [[PineNote_Development/Backup | backups]] and installing an OS to the PineNote.

== About the boot process of the PineNote ==
When the RK3566 is powered on it checks the attached storage devices in the ''boot order'':

* SPI NOR flash
* SPI NAND flash
* eMMC
* SD-Card

In the case of the PineNote there is only the eMMC.

If the SOC finds a storage device with a valid ID BLOCK it proceeds to boot from the device.

If no usable storage device is found the ROM in the SOC enters Maskrom mode and awaits a connection over USB

The PineNote additionally has a magnet sensor that is read by U-Boot during startup and if it detects a magnet U-Boot places the device in USB download mode

== Compiling rkdeveloptool ==

Pine64 develops a [https://gitlab.com/pine64-org/quartz-bsp/rkdeveloptool forked version] of the rkdeveloptool by RockChip, the following describes how to build the fork:

You will need to have ''libusb 1.0'', its development headers and ''scdoc'' installed.

git clone https://gitlab.com/pine64-org/quartz-bsp/rkdeveloptool.git
cd rkdeveloptool
mkdir build
cd build
cmake ..

This sets up all the build files. You can then compile with <code>make</code> inside the build directory.

After you're done, you'll likely also need to install the udev rules, or else your user won't have permission to access the USB devices:

sudo cp 99-rk-rockusb.rules /etc/udev/rules.d/
sudo udevadm control --reload

Copying the udev rules is also performed automatically when you <code>make install</code>.

== Entering Maskrom/Rockusb Mode ==

There are three ways to get into Maskrom/Rockusb mode:

The first two will result in Rockusb mode where drivers for the eMMC are loaded and rkdeveloptool can be used without further action.
This mode can be identified by ''Loader'' in the output when running <code>rkdeveloptool list</code>
rkdeveloptool list
DevNo=1 Vid=0x2207,Pid=0x350a,LocationID=402 Loader

The last method is used to recover from a bad u-boot and leaves the device in ''Maskrom''.
Here rkdevelop must first be used to upload the loader code with the driver for the eMMC.
This mode can be identified by ''Maskrom'' in the output when running <code>rkdeveloptool list</code>
rkdeveloptool list-devices
DevNo=1 Vid=0x2207,Pid=0x350a,LocationID=10e Maskrom

=== The magnet way ===

[[File:PineNoteMagnetOnBack.jpg|right|500px|PineNote with magnet on circle]]

# Remove the USB-C cable if connected
# Turn the PineNote off (press the power button for 5 seconds), and flip it around so that the display faces down
# Place a magnet in the correct place on the back of the PineNote, use one of the following methods:
#* Place a magnet on the small circle printed on the back, the pens magnetic cap can be used for this.
#* Lay the pen on the right side, with its tip pointing towards the speaker grill, and its magnet pointing towards the upper right corner of the label on the back (or place the magnetic cap from the pen on the spot marked on the back).
# Connect the PineNote to the PC using a USB-C cable, this will wake it up and boot. Wait for it to show up in <code>lsusb</code>.

It should now be in Loader mode, according to <code>rkdeveloptool list-devices</code> (note that ''Loader'' here indicates U-Boot's Rockusb; separately, booting with an erased eMMC displays ''Maskrom'' (not ''Loader'') from the RK3566).

In case it doesn't work the first time just try again.

=== The U-Boot way ===
# Interrupt the U-Boot startup using ''ctrl-c'' (while attached using an UART dongle)
# While in U-Boot use the command <code>rockusb 0 mmc 0</code> to start Rockusb mode.

One benefit from this is, that if you have an UART dongle that allows to simultaneous having an UART and USB connection, there is no need to plug and unplug cables and flipping the PineNote around and placing magnets.

This is especially helpful when changing back and forth between U-Boot and Rockusb, for example when trying to develop on U-Boot.

=== Shorting test points ===
{{Warning | This has the potential to damage you PineNote}}

If the bootloader is broken/corrupted, you cannot get to Maskrom without opening up the device (it can be opened using spudger and a bit of patience).

Ensure the device is off by pressing and holding the power button for 5 seconds.

Once inside, short TP1301 (GND) and TP1302 (eMMC_D0/FLASH_D0), this is how it looks on board view (credit to Caleb):

[[File:PineNote_Maskrom_TP.png|500px]]

Perform the short using one of:
* A small tweezers
* The programming pogo pins for a PineTime (mask the two unused pins with tape), the spring loaded nature of pogo pins helps getting a good contact
When shorting the test pads take great care to not short / touch other components or scratch the PCB as this '''may damage your PineNote'''.

While keeping the test pads shorted plug the device to the computer and if you see the device with VID=2207/PID=350a then it should be in Maskrom mode, you can verify by typing <code>rkdeveloptool list-devices</code>.

Jan 07 15:04:13 melttower kernel: usb 1-14: New USB device found, idVendor=2207, idProduct=350a, bcdDevice= 1.00
Jan 07 15:04:13 melttower kernel: usb 1-14: New USB device strings: Mfr=0, Product=0, SerialNumber=0

$ rkdeveloptool list-devices
DevNo=1 Vid=0x2207,Pid=0x350a,LocationID=10e Maskrom

If nothing shows up, you can try to hold down the power button for 5 seconds and then try again.

[[Category:PineNote]]

User:Talpa/Using rkdeveloptool

2023-01-15T19:00:48Z

Talpa: Added a image with a PineNote with a magnet on the back

= Using rkdeveloptool =

rkdeveloptool is a command line tool that can communicate with a some Rockchip SOCs like the RK3566 in the PineNote when they are in maskrom/rockusb mode.

rkdeveloptool can among other things read and write to the eMMC inside the PineNote.

It is therefor useful for [[PineNote_Development/Backup | backups]] and installing an OS to the PineNote.

== About the boot process of the PineNote ==
When the RK3566 is powered on it checks the attached storage devices in the ''boot order'':

* SPI NOR flash
* SPI NAND flash
* eMMC
* SD-Card

''In the case of the PineNote there is only the eMMC''

If the SOC finds a storage device with a valid ID BLOCK it proceeds to boot from the device.

If no usable storage device is found the ROM in the SOC enters maskrom mode and awaits a connection over USB

The PineNote additionally has a magnet sensor that is read by U-Boot during startup and if it detects a magnet U-Boot places the device in USB download mode

== Compiling rkdeveloptool ==

Pine64 develops a [https://gitlab.com/pine64-org/quartz-bsp/rkdeveloptool forked version] of the rkdeveloptool by RockChip, the following describes how to build the fork:

You will need to have libusb 1.0, its development headers and scdoc installed.

git clone https://gitlab.com/pine64-org/quartz-bsp/rkdeveloptool.git
cd rkdeveloptool
mkdir build
cd build
cmake ..

This sets up all the build files. You can then compile with <code>make</code> inside the build directory.

After you're done, you'll likely also need to install the udev rules, or else your user won't have permission to access the USB devices:

sudo cp 99-rk-rockusb.rules /etc/udev/rules.d/
sudo udevadm control --reload

Copying the udev rules is also performed automatically when you <code>make install</code>.

== Entering Maskrom/Rockusb Mode ==

There are three ways to get into Maskrom/Rockusb mode:

=== The magnet way ===
[[File:PineNoteMagnetOnBack.jpg|right|500px|PineNote with magnet on circle]]
# Remove the USB-C cable if connected
# Turn the PineNote off (press the power button for 5 seconds), and flip it around so that the display faces down
# Place a magnet in the correct place on the back of the PineNote, use one of the following methods:
#* Place a magnet on the small circle printed on the back, the pens magnetic cap can be used for this.
#* Lay the pen on the right side, with its tip pointing towards the speaker grill, and its magnet pointing towards the upper right corner of the label on the back (or place the magnetic cap from the pen on the spot marked on the back).
# Connect the PineNote to the PC using a USB-C cable, this will wake it up and boot. Wait for it to show up in <code>lsusb</code>.

It should now be in Loader mode, according to <code>rkdeveloptool list-devices</code> (note that ''Loader'' here indicates U-Boot's Rockusb; separately, booting with an erased eMMC displays ''Maskrom'' (not ''Loader'') from the RK3566).

In case it doesn't work the first time just try again.

=== The u-boot way ===
# Interrupt the u-boot startup using ''ctrl-c'' (while attached using an UART dongle)
# While in u-boot use the command <code>rockusb 0 mmc 0</code> to start Rockusb mode.

One benefit from this is, that if you have an UART dongle that allows to simultaneous having an UART and USB connection, there is no need to plug and unplug cables and flipping the PineNote around and placing magnets.

This is especially helpful when changing back and forth between U-Boot and Rockusb, for instance when trying to develop u-boot.

=== Shorting test points ===
{{Warning | This has the potential to damage you PineNote}}

If the bootloader is broken/corrupted, you cannot get to Maskrom without opening up the device (it can be opened using spudger and a bit of patience).

Ensure the device is off by pressing and holding the power button for 5 seconds.

Once inside, short TP1301 (GND) and TP1302 (eMMC_D0/FLASH_D0), this is how it looks on board view (credit to Caleb):

[[File:PineNote_Maskrom_TP.png|500px]]

Perform the short using one of:
* A small tweezers
* The programming pogo pins for a PineTime (mask the two unused pins with tape), the spring loaded nature of pogo pins helps getting a good contact
When shorting the test pads take great care to not short / touch other components or scratch the PCB as this '''may damage your PineNote'''.

While keeping the test pads shorted plug the device to the computer and if you see the device with VID=2207/PID=350a then it should be in Maskrom mode, you can verify by typing <code>rkdeveloptool list-devices</code>.

Jan 07 15:04:13 melttower kernel: usb 1-14: New USB device found, idVendor=2207, idProduct=350a, bcdDevice= 1.00
Jan 07 15:04:13 melttower kernel: usb 1-14: New USB device strings: Mfr=0, Product=0, SerialNumber=0

$ rkdeveloptool list-devices
DevNo=1 Vid=0x2207,Pid=0x350a,LocationID=10e Maskrom

If nothing shows up, you can try to hold down the power button for 5 seconds and then try again.

[[Category:PineNote]]

File:PineNoteMagnetOnBack.jpg

2023-01-15T18:55:58Z

Talpa: Image of a PineNote with a 25% opacity magnet on the printed circle

== Summary ==
Image of a PineNote with a 25% opacity magnet on the printed circle
== Licensing ==
{{cc-by-sa-4.0}}

User:Talpa/Using rkdeveloptool

2023-01-15T18:48:43Z

Talpa: Added using the circle and ensuring that the device is off before trying to get into rockusb

= Using rkdeveloptool =

rkdeveloptool is a command line tool that can communicate with a some Rockchip SOCs like the RK3566 in the PineNote when they are in maskrom/rockusb mode.

rkdeveloptool can among other things read and write to the eMMC inside the PineNote.

It is therefor useful for [[PineNote_Development/Backup | backups]] and installing an OS to the PineNote.

== About the boot process of the PineNote ==
When the RK3566 is powered on it checks the attached storage devices in the ''boot order'':

* SPI NOR flash
* SPI NAND flash
* eMMC
* SD-Card

''In the case of the PineNote there is only the eMMC''

If the SOC finds a storage device with a valid ID BLOCK it proceeds to boot from the device.

If no usable storage device is found the ROM in the SOC enters maskrom mode and awaits a connection over USB

The PineNote additionally has a magnet sensor that is read by U-Boot during startup and if it detects a magnet U-Boot places the device in USB download mode

== Compiling rkdeveloptool ==

Pine64 develops a [https://gitlab.com/pine64-org/quartz-bsp/rkdeveloptool forked version] of the rkdeveloptool by RockChip, the following describes how to build the fork:

You will need to have libusb 1.0, its development headers and scdoc installed.

git clone https://gitlab.com/pine64-org/quartz-bsp/rkdeveloptool.git
cd rkdeveloptool
mkdir build
cd build
cmake ..

This sets up all the build files. You can then compile with <code>make</code> inside the build directory.

After you're done, you'll likely also need to install the udev rules, or else your user won't have permission to access the USB devices:

sudo cp 99-rk-rockusb.rules /etc/udev/rules.d/
sudo udevadm control --reload

Copying the udev rules is also performed automatically when you <code>make install</code>.

== Entering Maskrom/Rockusb Mode ==

There are three ways to get into Maskrom/Rockusb mode:

=== The magnet way ===

# Remove the USB-C cable if connected
# Turn the PineNote off (press the power button for 5 seconds), and flip it around so that the display faces down
# Place a magnet in the correct place on the back of the PineNote, use one of the following methods:
#* Place a magnet on the small circle printed on the back, the pens magnetic cap can be used for this.
#* Lay the pen on the right side, with its tip pointing towards the speaker grill, and its magnet pointing towards the upper right corner of the label on the back (or place the magnetic cap from the pen on the spot marked on the back).
# Connect the PineNote to the PC using a USB-C cable, this will wake it up and boot. Wait for it to show up in <code>lsusb</code>.

It should now be in Loader mode, according to <code>rkdeveloptool list-devices</code> (note that ''Loader'' here indicates U-Boot's Rockusb; separately, booting with an erased eMMC displays ''Maskrom'' (not ''Loader'') from the RK3566).

In case it doesn't work the first time just try again.

=== The u-boot way ===
# Interrupt the u-boot startup using ''ctrl-c'' (while attached using an UART dongle)
# While in u-boot use the command <code>rockusb 0 mmc 0</code> to start Rockusb mode.

One benefit from this is, that if you have an UART dongle that allows to simultaneous having an UART and USB connection, there is no need to plug and unplug cables and flipping the PineNote around and placing magnets.

This is especially helpful when changing back and forth between U-Boot and Rockusb, for instance when trying to develop u-boot.

=== Shorting test points ===
{{Warning | This has the potential to damage you PineNote}}

If the bootloader is broken/corrupted, you cannot get to Maskrom without opening up the device (it can be opened using spudger and a bit of patience).

Ensure the device is off by pressing and holding the power button for 5 seconds.

Once inside, short TP1301 (GND) and TP1302 (eMMC_D0/FLASH_D0), this is how it looks on board view (credit to Caleb):

[[File:PineNote_Maskrom_TP.png|500px]]

Perform the short using one of:
* A small tweezers
* The programming pogo pins for a PineTime (mask the two unused pins with tape), the spring loaded nature helps get a good contact
When shorting the test pads take great care to not short / touch other components or scratch the PCB as this '''may damage your PineNote'''.

While keeping the test pads shorted plug the device to the computer and if you see the device with VID=2207/PID=350a then it should be in Maskrom mode, you can verify by typing <code>rkdeveloptool list-devices</code>.

Jan 07 15:04:13 melttower kernel: usb 1-14: New USB device found, idVendor=2207, idProduct=350a, bcdDevice= 1.00
Jan 07 15:04:13 melttower kernel: usb 1-14: New USB device strings: Mfr=0, Product=0, SerialNumber=0

$ rkdeveloptool list-devices
DevNo=1 Vid=0x2207,Pid=0x350a,LocationID=10e Maskrom

If nothing shows up, you can try to hold down the power button for 5 seconds and then try again.

[[Category:PineNote]]

User:Talpa/Using rkdeveloptool

2023-01-15T13:52:04Z

Talpa: Copied in the how to get into rockusb mode and added some warnings

= Using rkdeveloptool =

rkdeveloptool is a command line tool that can communicate with a some Rockchip SOCs like the RK3566 in the PineNote when they are in maskrom/rockusb mode.

rkdeveloptool can among other things read and write to the eMMC inside the PineNote.

It is therefor useful for [[PineNote_Development/Backup | backups]] and installing an OS to the PineNote.

== About the boot process of the PineNote ==
When the RK3566 is powered on it checks the attached storage devices in the ''boot order'':

SPI NOR flash
SPI NAND flash
eMMC
SD-Card

''In the case of the PineNote there is only the eMMC''

If the SOC finds a storage device with a valid ID BLOCK it proceeds to boot from the device.

If no usable storage device is found the ROM in the SOC enters maskrom mode and awaits a connection over USB

The PineNote additionally has a magnet sensor that is read by U-Boot during startup and if it detects a magnet U-Boot places the device in USB download mode

== Compiling rkdeveloptool ==

Pine64 develops a [https://gitlab.com/pine64-org/quartz-bsp/rkdeveloptool forked version] of the rkdeveloptool by RockChip, the following describes how to build the fork:

You will need to have libusb 1.0, its development headers and scdoc installed.

git clone https://gitlab.com/pine64-org/quartz-bsp/rkdeveloptool.git
cd rkdeveloptool
mkdir build
cd build
cmake ..

This sets up all the build files. You can then compile with <code>make</code> inside the build directory.

After you're done, you'll likely also need to install the udev rules, or else your user won't have permission to access the USB devices:

sudo cp 99-rk-rockusb.rules /etc/udev/rules.d/
sudo udevadm control --reload

Copying the udev rules is also performed automatically when you <code>make install</code>.

== Entering Maskrom/Rockusb Mode ==

There are three ways to get into Maskrom/Rockusb mode:

=== The magnet way ===

# Flip the device around so that the display faces down
# Lay the pen on the right side, with its tip pointing towards the speaker grill, and its magnet pointing towards the upper right corner of the label on the back (or place the magnetic cap from the pen on the spot marked on the back).
# Turn the device on and wait for it to show up in <code>lsusb</code>. It should now be in Loader mode, according to <code>rkdeveloptool list-devices</code> (note that ''Loader'' here indicates U-Boot's Rockusb; separately, booting with an erased eMMC displays ''Maskrom'' (not ''Loader'') from the RK3566).
# Unplug the device and plug it back in. It should now be in Rockusb mode.

This can be a bit fiddly to get right and may need a few tries.

=== The u-boot way ===
# Interrupt the u-boot startup using ''ctrl-c'' (while attached using an UART dongle)
# While in u-boot use the command <code>rockusb 0 mmc 0</code> to start Rockusb mode.

One benefit from this is, that if you have an UART dongle that allows to simultaneous having an UART and USB connection, there is no need to plug and unplug cables and flipping the PineNote around and placing magnets.

This is especially helpful when changing back and forth between U-Boot and Rockusb, for instance when trying to develop u-boot.

=== Shorting test points ===
{{Warning | This has the potential to damage you PineNote}}

If the bootloader is broken/corrupted, you cannot get to Maskrom without opening up the device (it can be opened using spudger and a bit of patience).

Ensure the device is off by pressing and holding the power button for 5 seconds.

Once inside, short TP1301 (GND) and TP1302 (eMMC_D0/FLASH_D0), this is how it looks on board view (credit to Caleb):

[[File:PineNote_Maskrom_TP.png|500px]]

Perform the short using one of:
* A small tweezers
* The programming pogo pins for a PineTime (mask the two unused pins with tape), the spring loaded nature helps get a good contact
When shorting the test pads take great care to not short / touch other components or scratch the PCB as this '''may damage your PineNote'''.

While keeping the test pads shorted plug the device to the computer and if you see the device with VID=2207/PID=350a then it should be in Maskrom mode, you can verify by typing <code>rkdeveloptool list-devices</code>.

Jan 07 15:04:13 melttower kernel: usb 1-14: New USB device found, idVendor=2207, idProduct=350a, bcdDevice= 1.00
Jan 07 15:04:13 melttower kernel: usb 1-14: New USB device strings: Mfr=0, Product=0, SerialNumber=0

$ rkdeveloptool list-devices
DevNo=1 Vid=0x2207,Pid=0x350a,LocationID=10e Maskrom

If nothing shows up, you can try to hold down the power button for 5 seconds and then try again.

[[Category:PineNote]]

User:Talpa/Using rkdeveloptool

2023-01-15T13:24:52Z

Talpa: Copied more of the build instructions

= Using rkdeveloptool =

rkdeveloptool is a command line tool that can communicate with a some Rockchip SOCs like the RK3566 in the PineNote when they are in maskrom/download mode.

rkdeveloptool can among other things read and write to the eMMC inside the PineNote.

It is therefor useful for [[PineNote_Development/Backup | backups]] and installing an OS to the PineNote.

== About the boot process of the PineNote ==
When the RK3566 is powered on it checks the attached storage devices in the ''boot order'':

SPI NOR flash
SPI NAND flash
eMMC
SD-Card

''In the case of the PineNote there is only the eMMC''

If the SOC finds a storage device with a valid ID BLOCK it proceeds to boot from the device.

If no usable storage device is found the ROM in the SOC enters maskrom mode and awaits a connection over USB

The PineNote additionally has a magnet sensor that is read by U-Boot during startup and if it detects a magnet U-Boot places the device in USB download mode

== Compiling rkdeveloptool ==

Pine64 develops a [https://gitlab.com/pine64-org/quartz-bsp/rkdeveloptool forked version] of the rkdeveloptool by RockChip, the following describes how to build the fork:

You will need to have libusb 1.0, its development headers and scdoc installed.

git clone https://gitlab.com/pine64-org/quartz-bsp/rkdeveloptool.git
cd rkdeveloptool
mkdir build
cd build
cmake ..

This sets up all the build files. You can then compile with <code>make</code> inside the build directory.

After you're done, you'll likely also need to install the udev rules, or else your user won't have permission to access the USB devices:

sudo cp 99-rk-rockusb.rules /etc/udev/rules.d/
sudo udevadm control --reload

Copying the udev rules is also performed automatically when you <code>make install</code>.

[[Category:PineNote]]

User:Talpa/Using rkdeveloptool

2023-01-15T13:07:30Z

Talpa: Initial page dedicated to using rkdeveloptool

User:Talpa/Backup

2023-01-15T12:15:10Z

Talpa:

= Backup =

{{Info|A backup of the content of the internal eMMC before any of the irreplaceable '''unique''' data gets messed up is '''mandatory'''.}}
The '''first 64 sectors''' of the eMMC and the '''''waveform'' partition''' contains irreplaceable data unique to your PineNote and must be backed up.

Depending of your personal level of data hoarder you may want to backup more than this or even just everything (the large ''userdata'' partition is supposed to be able to be repopulated as empty space by Android)

In any case it is easier to restore/extract data from a backup than not having one if you need one.

=== Manually using rkdeveloptool ===
Dorian has some nice [https://github.com/DorianRudolph/pinenotes notes regarding the PineNote]

Don't forget to install a patched U-Boo for reading beyond 32MB and to respect the 2GB limit/bug of the current rkdeveloptool as per his notes

Build rkdeveloptool:

git clone https://gitlab.com/pine64-org/quartz-bsp/rkdeveloptool.git
cd rkdeveloptool
mkdir build
cd build
cmake ..

Download mode
Enter the download mode by placing the pen as pictured below. A magnet placed where the pen's cap is should also work (haven't tried). I guess the dot on the case also indicates the position of the sensor.

placing pen on the back

<code>lsusb</code> should now recognize the PineNote as:

2207:350a Fuzhou Rockchip Electronics Company USB download gadget

List partitions:

> rkdeveloptool list-partitions
# LBA start (sectors) LBA end (sectors) Size (bytes) Name
00 16384 24575 4194304 uboot
01 24576 32767 4194304 trust
02 32768 36863 2097152 waveform
03 36864 45055 4194304 misc
04 45056 53247 4194304 dtbo
05 53248 55295 1048576 vbmeta
06 55296 137215 41943040 boot
07 137216 145407 4194304 security
08 145408 407551 134217728 recovery
09 407552 1193983 402653184 backup
10 1193984 3291135 1073741824 cache
11 3291136 3323903 16777216 metadata
12 3323904 9697279 3263168512 super
13 9697280 9730047 16777216 logo
14 9730048 9861119 67108864 device
15 9861120 241827775 118766927872 userdata

{{Warning|this process is very new! Proceed at your own risk.}}

See [https://github.com/m-weigand/pinenote-debian-recipes/releases/tag/v0.1 instructions on this artifact]. It will instruct you on extracting the rootfs into an empty ext4 partition. This can be done from Linux or Android. Further instructions on building your own rootfs [https://github.com/m-weigand/pinenote-debian-recipes can be found here].

=== Automated backup using a script and rkdeveloptool ===
[https://github.com/talpadk/pinenote-backup pinenote-backup] is a python script for detecting the partitions and automating the backup of partitions or the whole disk.

It also requires a patched u-boot but automatically handles the 2GB limit by splitting up larger reads into smaller ones

=== Using the factory Android installation ===
TODO

=== Using a user installed Linux ===
A Linux installed to the cache partition should be able to easily backup everything over WiFi or to a USB stick/disk using ''dd''.

However the user would need to backup the cache partition themself (if they want that).

And more importantly they would only be getting the backup ''after'' they started playing with the content of the eMMC.

[[Category:PineNote]]

User:Talpa/Backup

2023-01-15T12:07:54Z

Talpa:

= Backup =

{{Info|A backup of the content of the internal eMMC before any of the '''unique''' data gets messed up is '''mandatory'''.}}
Especially the first 64 sectors of the eMMC and the ''waveform'' partition contains data '''unique''' irreplaceable data to your PineNote and must be backed up.

Depending of your personal level of data hoarder you may want to backup more than this or even just everything (the large ''userdata'' partition is supposed to be able to be repopulated as empty space by Android)

In any case it is easier to restore/extract data from a backup than not having one if you need one.

=== Manually using rkdeveloptool ===
Dorian has some nice [https://github.com/DorianRudolph/pinenotes notes regarding the PineNote]

Don't forget to install a patched U-Boo for reading beyond 32MB and to respect the 2GB limit/bug of the current rkdeveloptool as per his notes

Build rkdeveloptool:

git clone https://gitlab.com/pine64-org/quartz-bsp/rkdeveloptool.git
cd rkdeveloptool
mkdir build
cd build
cmake ..

Download mode
Enter the download mode by placing the pen as pictured below. A magnet placed where the pen's cap is should also work (haven't tried). I guess the dot on the case also indicates the position of the sensor.

placing pen on the back

<code>lsusb</code> should now recognize the PineNote as:

2207:350a Fuzhou Rockchip Electronics Company USB download gadget

List partitions:

> rkdeveloptool list-partitions
# LBA start (sectors) LBA end (sectors) Size (bytes) Name
00 16384 24575 4194304 uboot
01 24576 32767 4194304 trust
02 32768 36863 2097152 waveform
03 36864 45055 4194304 misc
04 45056 53247 4194304 dtbo
05 53248 55295 1048576 vbmeta
06 55296 137215 41943040 boot
07 137216 145407 4194304 security
08 145408 407551 134217728 recovery
09 407552 1193983 402653184 backup
10 1193984 3291135 1073741824 cache
11 3291136 3323903 16777216 metadata
12 3323904 9697279 3263168512 super
13 9697280 9730047 16777216 logo
14 9730048 9861119 67108864 device
15 9861120 241827775 118766927872 userdata

{{Warning|this process is very new! Proceed at your own risk.}}

See [https://github.com/m-weigand/pinenote-debian-recipes/releases/tag/v0.1 instructions on this artifact]. It will instruct you on extracting the rootfs into an empty ext4 partition. This can be done from Linux or Android. Further instructions on building your own rootfs [https://github.com/m-weigand/pinenote-debian-recipes can be found here].

=== Automated backup using a script and rkdeveloptool ===
[https://github.com/talpadk/pinenote-backup pinenote-backup] is a python script for detecting the partitions and automating the backup of partitions or the whole disk.

It also requires a patched u-boot but automatically handles the 2GB limit by splitting up larger reads into smaller ones

=== Using the factory Android installation ===
TODO

=== Using a user installed Linux ===
A Linux installed to the cache partition should be able to easily backup everything over WiFi or to a USB stick/disk using ''dd''.

However the user would need to backup the cache partition themself (if they want that).

And more importantly they would only be getting the backup ''after'' they started playing with the content of the eMMC.

User:Talpa/Backup

2023-01-15T12:07:37Z

Talpa: Reduced amount of text and insists on backing up the 64 first sectors (they contain the vendor storage data)

= Backup =

{{Info|A backup of the content of the internal eMMC before any of the '''unique''' data gets messed up is '''mandatory'''.
Especially the first 64 sectors of the eMMC and the ''waveform'' partition contains data '''unique''' irreplaceable data to your PineNote and must be backed up.

Depending of your personal level of data hoarder you may want to backup more than this or even just everything (the large ''userdata'' partition is supposed to be able to be repopulated as empty space by Android)

In any case it is easier to restore/extract data from a backup than not having one if you need one.

=== Manually using rkdeveloptool ===
Dorian has some nice [https://github.com/DorianRudolph/pinenotes notes regarding the PineNote]

Don't forget to install a patched U-Boo for reading beyond 32MB and to respect the 2GB limit/bug of the current rkdeveloptool as per his notes

Build rkdeveloptool:

git clone https://gitlab.com/pine64-org/quartz-bsp/rkdeveloptool.git
cd rkdeveloptool
mkdir build
cd build
cmake ..

Download mode
Enter the download mode by placing the pen as pictured below. A magnet placed where the pen's cap is should also work (haven't tried). I guess the dot on the case also indicates the position of the sensor.

placing pen on the back

<code>lsusb</code> should now recognize the PineNote as:

2207:350a Fuzhou Rockchip Electronics Company USB download gadget

List partitions:

> rkdeveloptool list-partitions
# LBA start (sectors) LBA end (sectors) Size (bytes) Name
00 16384 24575 4194304 uboot
01 24576 32767 4194304 trust
02 32768 36863 2097152 waveform
03 36864 45055 4194304 misc
04 45056 53247 4194304 dtbo
05 53248 55295 1048576 vbmeta
06 55296 137215 41943040 boot
07 137216 145407 4194304 security
08 145408 407551 134217728 recovery
09 407552 1193983 402653184 backup
10 1193984 3291135 1073741824 cache
11 3291136 3323903 16777216 metadata
12 3323904 9697279 3263168512 super
13 9697280 9730047 16777216 logo
14 9730048 9861119 67108864 device
15 9861120 241827775 118766927872 userdata

{{Warning|this process is very new! Proceed at your own risk.}}

See [https://github.com/m-weigand/pinenote-debian-recipes/releases/tag/v0.1 instructions on this artifact]. It will instruct you on extracting the rootfs into an empty ext4 partition. This can be done from Linux or Android. Further instructions on building your own rootfs [https://github.com/m-weigand/pinenote-debian-recipes can be found here].

=== Automated backup using a script and rkdeveloptool ===
[https://github.com/talpadk/pinenote-backup pinenote-backup] is a python script for detecting the partitions and automating the backup of partitions or the whole disk.

It also requires a patched u-boot but automatically handles the 2GB limit by splitting up larger reads into smaller ones

=== Using the factory Android installation ===
TODO

=== Using a user installed Linux ===
A Linux installed to the cache partition should be able to easily backup everything over WiFi or to a USB stick/disk using ''dd''.

However the user would need to backup the cache partition themself (if they want that).

And more importantly they would only be getting the backup ''after'' they started playing with the content of the eMMC.

User:Talpa/Backup

2023-01-15T11:57:26Z

Talpa: Copy of the moved backup instructions

== Backup ==

{{Info|A backup of the content of the internal eMMC before anything gets messed is '''mandatory'''.}}

Especially the ''waveform'' partition contains data '''unique''' to your PineNote and is a prime candidate for backup.

But other partitions like U-Boot (need for any operation of the device) or the un-partitioned space at the beginning containing the GPT partition table (and presumably the VCOM setting for the e-ink display and maybe device mac addresses) contains data you may wish to backup.

Depending of your personal level of data hoarder you may want to backup more than this or even just everything (the large ''userdata'' partition is supposed to be able to be repopulated as empty space by Android)

In any case it is easier to restore/extract data from a backup than not having one if you need one.

=== Manually using rkdeveloptool ===
Dorian has some nice [https://github.com/DorianRudolph/pinenotes notes regarding the PineNote]

Don't forget to install a patched U-Boo for reading beyond 32MB and to respect the 2GB limit/bug of the current rkdeveloptool as per his notes

Build rkdeveloptool:

git clone https://gitlab.com/pine64-org/quartz-bsp/rkdeveloptool.git
cd rkdeveloptool
mkdir build
cd build
cmake ..

Download mode
Enter the download mode by placing the pen as pictured below. A magnet placed where the pen's cap is should also work (haven't tried). I guess the dot on the case also indicates the position of the sensor.

placing pen on the back

<code>lsusb</code> should now recognize the PineNote as:

2207:350a Fuzhou Rockchip Electronics Company USB download gadget

List partitions:

> rkdeveloptool list-partitions
# LBA start (sectors) LBA end (sectors) Size (bytes) Name
00 16384 24575 4194304 uboot
01 24576 32767 4194304 trust
02 32768 36863 2097152 waveform
03 36864 45055 4194304 misc
04 45056 53247 4194304 dtbo
05 53248 55295 1048576 vbmeta
06 55296 137215 41943040 boot
07 137216 145407 4194304 security
08 145408 407551 134217728 recovery
09 407552 1193983 402653184 backup
10 1193984 3291135 1073741824 cache
11 3291136 3323903 16777216 metadata
12 3323904 9697279 3263168512 super
13 9697280 9730047 16777216 logo
14 9730048 9861119 67108864 device
15 9861120 241827775 118766927872 userdata

{{Warning|this process is very new! Proceed at your own risk.}}

See [https://github.com/m-weigand/pinenote-debian-recipes/releases/tag/v0.1 instructions on this artifact]. It will instruct you on extracting the rootfs into an empty ext4 partition. This can be done from Linux or Android. Further instructions on building your own rootfs [https://github.com/m-weigand/pinenote-debian-recipes can be found here].

=== Automated backup using a script and rkdeveloptool ===
[https://github.com/talpadk/pinenote-backup pinenote-backup] is a python script for detecting the partitions and automating the backup of partitions or the whole disk.

It also requires a patched u-boot but automatically handles the 2GB limit by splitting up larger reads into smaller ones

=== Using the factory Android installation ===
TODO

=== Using a user installed Linux ===
A Linux installed to the cache partition should be able to easily backup everything over WiFi or to a USB stick/disk using ''dd''.

However the user would need to backup the cache partition themself (if they want that).

And more importantly they would only be getting the backup ''after'' they started playing with the content of the eMMC.

PineNote Development

2022-12-30T12:09:04Z

Talpa: Additional information on getting WiFi and BT driver blobs

This article seeks to provide general development information for the [[PineNote]]. If you are new and down to try a new installation process, the easiest way to get linux is likely to [https://wiki.pine64.org/wiki/PineNote_Development/Installing_Debian install Debian] -- NOTE THAT THIS INSTALLATION PROCESS IS VERY NEW. While many people have been using the kernel that will be installed safely at this point, the instructions for installing Debian via rootfs are very new. Take backups!

The more stable recommended approach is described below:

Start with [https://github.com/DorianRudolph/pinenotes Dorian's guide] which will guide you through getting Arch installed. For instructions on building the latest kernel, see [[PineNote Development/Building Kernel]]. For helpful configurations, see [[PineNote Development/Apps]]. For ways to pitch in, see [[PineNote Development/TODOs]]. To boot Linux by default instead of Android, see [[PineNote Development/Booting Linux]]. [https://www.youtube.com/watch?v=ZCLyJfbzbrU Here is a video] of a user running Manjaro and some apps on their PineNote on 9/10/2022.

= More Information =
== High-level developer new to embedded linux? ==
Here are some resources I have found helpful in learning to develop on embedded linux devices:
* Great youtube series introducing you to the kernel and lower-level components of Linux: https://www.youtube.com/watch?v=WiZ05pnHZqM
* https://embetronicx.com/
* https://bootlin.com/training/
* https://www.nand2tetris.org

== Notes Written by Some Developers ==

* https://github.com/m-weigand/mw_pinenote_misc (Not super legible "notes", but very helpful repo with patches, videos, etc)
** specifically see this section for helpful install/configure scripts: https://github.com/m-weigand/mw_pinenote_misc/tree/main/rockchip_ebc/patches#compiling.
* https://github.com/0cc4m/pinenote-misc
** patch for enabling gpu: https://github.com/0cc4m/pinenote-misc/blob/main/mesa-archlinux-arm/mesa/rockchip_ebc.patch
** prebuilt pkg's: https://github.com/0cc4m/pinenote-misc/releases
* https://pwarren.id.au/pinenote/build_notes.txt
* https://github.com/DorianRudolph/pinenotes
* https://github.com/tpwrules/nixos-pinenote

== Alternative to patching of mesa ==
Mesa needs to be patched to add the driver entry point. The alternative to this, is the renaming of the ebc driver to an existing mesa driver entry point. A good existing name can be "repaper". To change the driver name, edit in the kernel tree the following files: 
- replace "rockchip-ebc" with "repaper" in the two places in the file: drivers/gpu/drm/rockchip/rockchip_ebc.c 
- preventive, replace "repaper" with "repaper-disabled" in the two places in the file: drivers/gpu/drm/tiny/repaper.c 

== Building the most recent kernel ==
See [https://wiki.pine64.org/wiki/PineNote_Development/Building_Kernel here].

== Video of Factory Android OS ==

[https://www.youtube.com/watch?v=DWuTGgQHw98 PineNote Developer Edition w/Tech Demo Android OS (Video Only)]

Informal walkthrough of the factory Android installation on the PineNote Developer Edition, recorded by a community member (Apr 2022). This is useful to look back at the original OS after erasing it from your device, or to get some additional detail before your device arrives.

The video also includes a chapter at the end showing [https://www.youtube.com/watch?v=DWuTGgQHw98&t=802s how to enable Android Debug Bridge (`adb`) over USB]. Once enabled, keep the device powered and connect a USB cable directly to the PineNote (i.e. no UART breakout) to a computer running `adb`.

== Emulator for Developing/Testing Pinenote Apps ==
https://github.com/michaelshiel/picom-epaper

= Flashing Software =
Currently, the only ways to flash software are from the factory Android installation (UART shell, adb, or fastboot) or by using rkdeveloptool.

== Backup of the content of the internal MMC before you mess anything up ==
Especially the '''waveform''' partition contains data '''unique''' to your PineNote and is a prime candidate for backup.

But other partitions like uboot (need for any operation of the device) or the un-partitioned space at the beginning containing the GPT partition table (and presumably the VCOM setting for the e-ink display and maybe device mac addresses) contains data you may wish to backup.

Depending of your personal level of data hoarder you may want to backup more than this or even just everything (the large userdata partition is supposed to be able to be repopulated as empty space by Android)

In any case it is easier to restore/extract data from a backup than not having one if you need one.

=== Manually using rkdeveloptool ===
Dorian has some nice [https://github.com/DorianRudolph/pinenotes notes regarding the PineNote]

Don't forget to install a patched uboot for reading beyond 32MB and to respect the 2GB limit/bug of the current rkdeveloptool as per his notes

=== Automated backup using a script and rkdeveloptool ===
[https://github.com/talpadk/pinenote-backup pinenote-backup] is a python script for detecting the partitions and automating the backup of partitions or the whole disk

I also requires a patched u-boot but automatically handles the 2GB limit by splitting up larger reads into smaller ones

=== Using the factory Android installation ===
For any one knowing how and with which caveats: Write ME

=== Using a user installed Linux ===
A Linux installed to the cache partition should be able to easily backup everything over WiFi or to a USB stick/disk using dd

However the user would need to backup the cache partition themself (if they want that).

And more importantly they would only be getting the backup ''after'' they started playing with the content of the MMC.

== Side-by-side setup ==

It is possible to set up a partition for mainline development without disturbing the factory Android installation. This allows updating a mainline kernel, DTB, and initramfs over Wi-Fi until WiFi or USB OTG is working in mainline Linux.

=== Without Repartitioning ===

The recommended partition for this is <tt>mmcblk0p11</tt> aka <tt>/cache</tt>. It is large and already formatted as <tt>ext4</tt>, so it is readable from U-Boot. Here are some general steps:

# From the UART or adb shell, set up your chroot in <tt>/cache</tt>. I used the Alpine Linux rootfs tarball.
# Copy in your kernel and DTB, using for example <tt>scp</tt> or <tt>wget</tt> inside the chroot.
# Finally, create and boot an <code>extlinux.conf</code> as described below.

=== With Repartitioning ===

It is possible to shrink the <tt>userdata</tt> partition, and create a new partition at the end for use with mainline Linux. This provides much more space than <tt>cache</tt>. However, because <tt>userdata</tt> is formatted with <tt>f2fs</tt>, and that filesystem cannot be shrunk, resizing the partition requires wiping <tt>userdata</tt>.

# Back up any necessary files from userdata
# Boot to a mainline kernel from <tt>mmcblk0p11</tt>, either using that partition as rootfs (see above), or using an initramfs with repartitioning tools
# Modify the partition table with your favorite tool, e.g. <tt>fdisk</tt>, <tt>gdisk</tt>, or <tt>parted</tt>
# Reboot into <tt>fastboot</tt> and wipe <tt>userdata</tt>.
# Reboot into Android, where you can now chroot in and install your favorite distribution to the new partition.

== Using rkdeveloptool ==

rkdeveloptool is a command line utility built on libusb.

=== Downloading and Building rkdeveloptool ===

PINE64 develops [https://gitlab.com/pine64-org/quartz-bsp/rkdeveloptool its own updated fork of rkdeveloptool on GitLab].

You will need to have libusb 1.0, its development headers and scdoc installed.

<pre>
git clone https://gitlab.com/pine64-org/quartz-bsp/rkdeveloptool.git
cd rkdeveloptool
mkdir build
cd build
cmake ..
</pre>

This sets up all the build files. You can then compile with <code>make</code> inside the build directory.

After you're done, you'll likely also need to install the udev rules, or else your user won't have permission to access the USB devices:

<pre>
sudo cp 99-rk-rockusb.rules /etc/udev/rules.d/
sudo udevadm control --reload
</pre>

Copying the udev rules is also performed automatically when you <code>make install</code>.

=== Building Downstream U-Boot ===

While in maskrom mode, we need to have a u-boot to download onto the device for any of the other commands to work. To build you'll also need to install device-tree-compiler.

You also need to install Python and pyelftools.

 Note that rkbin is a >5GB download! This will take some time to clone and process the deltas.

<pre>
git clone -b quartz64 https://gitlab.com/pgwipeout/u-boot-rockchip.git
git clone -b rkbin https://github.com/JeffyCN/rockchip_mirrors.git rkbin
cd u-boot-rockchip
# If using Arch Linux, export CROSS_COMPILE=aarch64-linux-gnu-
export CROSS_COMPILE=aarch64-none-linux-gnu-
make rk3566-quartz64_defconfig
./make.sh
</pre>

<blockquote>
In the version I cloned (current as of 2022-01-02), I had to make a change to one line to get a clean compilation:

<pre>
diff --git a/lib/avb/libavb/avb_slot_verify.c b/lib/avb/libavb/avb_slot_verify.c
index 123701fc3b..64a1ce6450 100644
--- a/lib/avb/libavb/avb_slot_verify.c
+++ b/lib/avb/libavb/avb_slot_verify.c
@@ -296,7 +296,7 @@ static AvbSlotVerifyResult load_and_verify_hash_partition(
bool image_preloaded = false;
uint8_t* digest;
size_t digest_len;
- const char* found;
+ const char* found = NULL;
uint64_t image_size;
size_t expected_digest_len = 0;
uint8_t expected_digest_buf[AVB_SHA512_DIGEST_SIZE];
</pre>

For systems where the global python executable points to python2, compilation fails with an error related to pyelftools not being installed (even if it is). To fix this:
<pre>
diff --git a/make.sh b/make.sh
index 2bba05b4e4..cfe5b0afd5 100755
--- a/make.sh
+++ b/make.sh
@@ -758,7 +758,7 @@ function pack_fit_image()
fi

if [ "${ARM64_TRUSTZONE}" == "y" ]; then
- if ! python -c "import elftools" ; then
+ if ! python3 -c "import elftools" ; then
echo "ERROR: No python 'pyelftools', please: pip install pyelftools"
exit 1
fi
</pre>
</blockquote>

=== Entering Maskrom/Rockusb Mode ===

There are three ways to get into Maskrom/Rockusb mode:

==== The easy way ====

# Flip the device around so that the display faces down
# Lay the pen on the right side, with its tip pointing towards the speaker grill, and its magnet pointing towards the upper right corner of the label on the back (or place the magnetic cap from the pen on the spot marked on the back).
# Turn the device on and wait for it to show up in <code>lsusb</code>. It should now be in Loader mode, according to <code>rkdeveloptool list-devices</code> (note that "Loader" here indicates U-Boot's Rockusb; separately, booting with an erased eMMC displays "Maskrom" [not "Loader"] from the RK3566).
# Unplug the device and plug it back in. It should now be in Rockusb mode.

This can be a bit fiddly to get right, and may need a few tries.

==== The u-boot way ====
# Interrupt the u-boot startup using ctrl-c (while attached using an UART dongle)
# While in u-boot use the command "rockusb 0 mmc 0" to start rockusb mode.

One benefit from this is, that if you have an UART dongle that allows to simultaneous having an UART and USB connection, there is no need to plug and unplug cables and flipping the PineNote around and placing magnets.

This is especially helpful when changing back and forth between u-boot and rockusb, for instance when trying to develop u-boot.

==== Shorting test points ====

If the bootloader is broken/corrupted, you cannot get to Maskrom without opening up the device (it can be opened using spudger and a bit of patience).

Once inside, short TP1301 (GND) and TP1302 (eMMC_D0/FLASH_D0) with a small tweezers, this is how it looks on board view (credit to Caleb):

[[File:PineNote_Maskrom_TP.png|500px]]

Then plug the device to the computer and if you see the device with VID=2207/PID=350a then it should be in Maskrom mode, you can verify by typing <code>rkdeveloptool list-devices</code>.

<nowiki>Jan 07 15:04:13 melttower kernel: usb 1-14: New USB device found, idVendor=2207, idProduct=350a, bcdDevice= 1.00
Jan 07 15:04:13 melttower kernel: usb 1-14: New USB device strings: Mfr=0, Product=0, SerialNumber=0

$ rkdeveloptool list-devices
DevNo=1 Vid=0x2207,Pid=0x350a,LocationID=10e Maskrom</nowiki>

If nothing shows up, you can try to hold down the power button for 5 seconds and then try again.

=== Running rkdeveloptool ===

First, you'll want to make sure the device you've connected is in maskrom mode:

<pre>
./rkdeveloptool list
</pre>

It should output something like <code>DevNo=1 Vid=0x2207,Pid=0x350a,LocationID=202 Maskrom</code>. If it doesn't, see [[PineNote Development#Entering Maskrom Mode]].

You can now download u-boot onto it:
<pre>
./rkdeveloptool boot ../u-boot-rockchip/rk356x_spl_loader_v1.08.111.bin
</pre>

This should output <code>Downloading bootloader succeeded.</code>.

We can now verify that this worked using e.g. the "read flash info" command:

<pre>
./rkdeveloptool read-flash-info
</pre>

'''TODO:''' finish this section

=== Creating a mainline boot image ===

You can create a filesystem image that replaces the Android boot or recovery partition by doing roughly the following:

# Erase boot and dtbo with rkdeveloptool or fastboot (back them up first!!!)
# Create an ext2 partition image and mount it (fallocate, mkfs.ext2)
# Build your mainline kernel
# Copy the kernel, dtb and an initramfs to the root of the mounted image (use any old postmarketOS initramfs)
# Create a file in the root of the mounted image called <code>extlinux.conf</code> as described below
# Unmount the image and then use rkdeveloptool to flash it to the "recovery" partition on the pinenote (it's about the right size until we get around to replacing the partition layout).

== Using fastboot ==

Follow the steps for "Creating a mainline boot.img", but instead of flashing it with rkdeveloptool, use fastboot. You can enter fastboot in either of two ways:

# Use "reboot bootloader" from adb or a UART console.
# Get a U-Boot prompt and run <code>fastboot usb 0</code>.

= Mainline development =

== Status ==

Some work happening here: https://gitlab.com/calebccff/linux, the idea is to import the parts of the eink/ebc drivers which are open source and use the downstream u-boot framebuffer driver as a reference to create a basic framebuffer driver.

Currently mainline struggles to boot due to weird issues while probing fixed regulators (?). It also fails to detect eMMC.

Further work is being done here: https://github.com/smaeul/linux/commits/rk356x-ebc-dev. This has a complete device tree, with working eMMC. Pen input also works out of the box. Wi-Fi and BT work with firmware copied from the factory Android image.

== How to boot mainline ==

UART is currently REQUIRED for this to work! We depend on u-boot falling back to console. Once we have a prebuilt u-boot which will use extlinux by default, UART won't be needed anymore.

You can compile a u-boot that uses extlinux by default by following the instructions [https://github.com/JoshuaMulliken/pinenote_uboot/blob/aa9ecbd3d3e716f163f5a900824630f24e9f04ba/README.md#changing-default-boot-order here].

=== Getting to a U-Boot prompt ===

You can get to a U-Boot prompt by:

# Holding Ctrl-C while the display panel initializes.
# Wiping the "boot" partition.

=== Using sysboot ===

<code>extlinux.conf</code> should have the following contents:

<pre>
timeout 10
default MAINLINE
menu title boot prev kernel

label MAINLINE
kernel /vmlinuz
fdt /rk3566-pinenote.dtb
initrd /initramfs
append earlycon console=tty0 console=ttyS2,1500000n8 fw_devlink=off PMOS_NO_OUTPUT_REDIRECT
</pre>

At the u-boot console, run the following command to boot your mainline kernel:

<pre>
sysboot ${devtype} ${devnum}:9 any ${scriptaddr} extlinux.conf
</pre>

=== Booting with individual commands ===

Booting with individual commands can be useful when you need to temporarily add some kernel command line arguments. Use these or similar commands at the U-Boot shell:

load mmc 0:b ${kernel_addr_r} boot/Image
load mmc 0:b ${fdt_addr_r} boot/rk3566-pinenote.dtb
setenv bootargs ignore_loglevel root=/dev/mmcblk0p11 rootwait init=/bin/bash
booti ${kernel_addr_r} - ${fdt_addr_r}

== Configuration ==

=== Firmware for WiFi & Bluetooth and Waveform data ===

==== Using Maximilian's Debian image ====
If the Android partition (super) and waveform partition (waveform) is left intact the image extracts the WiFi, BT driver and waveform from the partitions on first run.

For instance if you repartitions the userdata partition and installs the image there.

==== Getting it from the Android install manually ====
Copy WiFi/BT firmware from Android:
mkdir -p /cache/lib/firmware/brcm
cp /vendor/etc/firmware/fw_bcm43455c0_ag_cy.bin /cache/lib/firmware/brcm/brcmfmac43455-sdio.bin
cp /vendor/etc/firmware/nvram_ap6255_cy.txt /cache/lib/firmware/brcm/brcmfmac43455-sdio.txt
cp /cache/lib/firmware/BCM4345C0.hcd /cache/lib/firmware/brcm/BCM4345C0.hcd

Copy waveform partition (via previously dumped file):
adb root
adb push waveform.img /cache/lib/firmware/waveform.bin

Or via dd within Linux:
dd if=/dev/mmcblk0p3 of=/lib/firmware/waveform.bin bs=1k count=2048

==== Getting the Wifi and Bluetooth driver blobs from "other" sources ====
===== WiFi =====
The WiFi firmware .bin blob can be obtained by installing the Debian package firmware-brcm80211 (in the non-free section)

The WiFi brcmfmac43455-sdio.txt file can according to Eugen be sourced from https://git.kernel.org/pub/scm/linux/kernel/git/firmware/linux-firmware.git/tree/brcm/brcmfmac43455-sdio.AW-CM256SM.txt needs a renaming when copying it to /lib/firmware/brcm/brcmfmac43455-sdio.txt)

''The content of the upstream .txt is different than the Android configuration, but is supposed to work.''

As you don't have WiFi yet you need to get the firmware-brcm80211*.deb and brcmfmac43455-sdio.txt file on the PineNote by other means, for instance using an USB stick

===== Bluetooth =====

Once you have WiFi working you can get BCM4345C0.hcd by installing the bluez-firmware
sudo apt install bluez-firmware

=== Configuring the E-ink refresh mode ===
https://github.com/m-weigand/mw_pinenote_misc/tree/main/rockchip_ebc/patches contains information on how/where to write in /sys to alter the refresh mode

https://github.com/m-weigand/mw_pinenote_misc/tree/main/gnome_extension contains the gnome extension used in Maximilian image

=== Touchscreen and Pen In X.org ===

By default the pen config is flipped 180° (which makes it unusable) and the touchscreen doesn't work. Placing the following config in <code>/etc/X11/xorg.conf.d/50-touchscreen.conf</code> will fix both problems:

<pre>
Section "InputClass"
Identifier "evdev touchscreen"
MatchProduct "tt21000"
MatchIsTouchscreen "on"
Driver "evdev"
EndSection
Section "InputClass"
Identifier "RotateTouch"
MatchProduct "w9013"
Option "TransformationMatrix" "-1 0 1 0 -1 1 0 0 1"
EndSection
</pre>

PineNote Development

2022-12-30T11:36:21Z

Talpa: Links to information about changing the e-ink refresh mode

This article seeks to provide general development information for the [[PineNote]]. If you are new and down to try a new installation process, the easiest way to get linux is likely to [https://wiki.pine64.org/wiki/PineNote_Development/Installing_Debian install Debian] -- NOTE THAT THIS INSTALLATION PROCESS IS VERY NEW. While many people have been using the kernel that will be installed safely at this point, the instructions for installing Debian via rootfs are very new. Take backups!

The more stable recommended approach is described below:

Start with [https://github.com/DorianRudolph/pinenotes Dorian's guide] which will guide you through getting Arch installed. For instructions on building the latest kernel, see [[PineNote Development/Building Kernel]]. For helpful configurations, see [[PineNote Development/Apps]]. For ways to pitch in, see [[PineNote Development/TODOs]]. To boot Linux by default instead of Android, see [[PineNote Development/Booting Linux]]. [https://www.youtube.com/watch?v=ZCLyJfbzbrU Here is a video] of a user running Manjaro and some apps on their PineNote on 9/10/2022.

= More Information =
== High-level developer new to embedded linux? ==
Here are some resources I have found helpful in learning to develop on embedded linux devices:
* Great youtube series introducing you to the kernel and lower-level components of Linux: https://www.youtube.com/watch?v=WiZ05pnHZqM
* https://embetronicx.com/
* https://bootlin.com/training/
* https://www.nand2tetris.org

== Notes Written by Some Developers ==

* https://github.com/m-weigand/mw_pinenote_misc (Not super legible "notes", but very helpful repo with patches, videos, etc)
** specifically see this section for helpful install/configure scripts: https://github.com/m-weigand/mw_pinenote_misc/tree/main/rockchip_ebc/patches#compiling.
* https://github.com/0cc4m/pinenote-misc
** patch for enabling gpu: https://github.com/0cc4m/pinenote-misc/blob/main/mesa-archlinux-arm/mesa/rockchip_ebc.patch
** prebuilt pkg's: https://github.com/0cc4m/pinenote-misc/releases
* https://pwarren.id.au/pinenote/build_notes.txt
* https://github.com/DorianRudolph/pinenotes
* https://github.com/tpwrules/nixos-pinenote

== Alternative to patching of mesa ==
Mesa needs to be patched to add the driver entry point. The alternative to this, is the renaming of the ebc driver to an existing mesa driver entry point. A good existing name can be "repaper". To change the driver name, edit in the kernel tree the following files: 
- replace "rockchip-ebc" with "repaper" in the two places in the file: drivers/gpu/drm/rockchip/rockchip_ebc.c 
- preventive, replace "repaper" with "repaper-disabled" in the two places in the file: drivers/gpu/drm/tiny/repaper.c 

== Building the most recent kernel ==
See [https://wiki.pine64.org/wiki/PineNote_Development/Building_Kernel here].

== Video of Factory Android OS ==

[https://www.youtube.com/watch?v=DWuTGgQHw98 PineNote Developer Edition w/Tech Demo Android OS (Video Only)]

Informal walkthrough of the factory Android installation on the PineNote Developer Edition, recorded by a community member (Apr 2022). This is useful to look back at the original OS after erasing it from your device, or to get some additional detail before your device arrives.

The video also includes a chapter at the end showing [https://www.youtube.com/watch?v=DWuTGgQHw98&t=802s how to enable Android Debug Bridge (`adb`) over USB]. Once enabled, keep the device powered and connect a USB cable directly to the PineNote (i.e. no UART breakout) to a computer running `adb`.

== Emulator for Developing/Testing Pinenote Apps ==
https://github.com/michaelshiel/picom-epaper

= Flashing Software =
Currently, the only ways to flash software are from the factory Android installation (UART shell, adb, or fastboot) or by using rkdeveloptool.

== Backup of the content of the internal MMC before you mess anything up ==
Especially the '''waveform''' partition contains data '''unique''' to your PineNote and is a prime candidate for backup.

But other partitions like uboot (need for any operation of the device) or the un-partitioned space at the beginning containing the GPT partition table (and presumably the VCOM setting for the e-ink display and maybe device mac addresses) contains data you may wish to backup.

Depending of your personal level of data hoarder you may want to backup more than this or even just everything (the large userdata partition is supposed to be able to be repopulated as empty space by Android)

In any case it is easier to restore/extract data from a backup than not having one if you need one.

=== Manually using rkdeveloptool ===
Dorian has some nice [https://github.com/DorianRudolph/pinenotes notes regarding the PineNote]

Don't forget to install a patched uboot for reading beyond 32MB and to respect the 2GB limit/bug of the current rkdeveloptool as per his notes

=== Automated backup using a script and rkdeveloptool ===
[https://github.com/talpadk/pinenote-backup pinenote-backup] is a python script for detecting the partitions and automating the backup of partitions or the whole disk

I also requires a patched u-boot but automatically handles the 2GB limit by splitting up larger reads into smaller ones

=== Using the factory Android installation ===
For any one knowing how and with which caveats: Write ME

=== Using a user installed Linux ===
A Linux installed to the cache partition should be able to easily backup everything over WiFi or to a USB stick/disk using dd

However the user would need to backup the cache partition themself (if they want that).

And more importantly they would only be getting the backup ''after'' they started playing with the content of the MMC.

== Side-by-side setup ==

It is possible to set up a partition for mainline development without disturbing the factory Android installation. This allows updating a mainline kernel, DTB, and initramfs over Wi-Fi until WiFi or USB OTG is working in mainline Linux.

=== Without Repartitioning ===

The recommended partition for this is <tt>mmcblk0p11</tt> aka <tt>/cache</tt>. It is large and already formatted as <tt>ext4</tt>, so it is readable from U-Boot. Here are some general steps:

# From the UART or adb shell, set up your chroot in <tt>/cache</tt>. I used the Alpine Linux rootfs tarball.
# Copy in your kernel and DTB, using for example <tt>scp</tt> or <tt>wget</tt> inside the chroot.
# Finally, create and boot an <code>extlinux.conf</code> as described below.

=== With Repartitioning ===

It is possible to shrink the <tt>userdata</tt> partition, and create a new partition at the end for use with mainline Linux. This provides much more space than <tt>cache</tt>. However, because <tt>userdata</tt> is formatted with <tt>f2fs</tt>, and that filesystem cannot be shrunk, resizing the partition requires wiping <tt>userdata</tt>.

# Back up any necessary files from userdata
# Boot to a mainline kernel from <tt>mmcblk0p11</tt>, either using that partition as rootfs (see above), or using an initramfs with repartitioning tools
# Modify the partition table with your favorite tool, e.g. <tt>fdisk</tt>, <tt>gdisk</tt>, or <tt>parted</tt>
# Reboot into <tt>fastboot</tt> and wipe <tt>userdata</tt>.
# Reboot into Android, where you can now chroot in and install your favorite distribution to the new partition.

== Using rkdeveloptool ==

rkdeveloptool is a command line utility built on libusb.

=== Downloading and Building rkdeveloptool ===

PINE64 develops [https://gitlab.com/pine64-org/quartz-bsp/rkdeveloptool its own updated fork of rkdeveloptool on GitLab].

You will need to have libusb 1.0, its development headers and scdoc installed.

<pre>
git clone https://gitlab.com/pine64-org/quartz-bsp/rkdeveloptool.git
cd rkdeveloptool
mkdir build
cd build
cmake ..
</pre>

This sets up all the build files. You can then compile with <code>make</code> inside the build directory.

After you're done, you'll likely also need to install the udev rules, or else your user won't have permission to access the USB devices:

<pre>
sudo cp 99-rk-rockusb.rules /etc/udev/rules.d/
sudo udevadm control --reload
</pre>

Copying the udev rules is also performed automatically when you <code>make install</code>.

=== Building Downstream U-Boot ===

While in maskrom mode, we need to have a u-boot to download onto the device for any of the other commands to work. To build you'll also need to install device-tree-compiler.

You also need to install Python and pyelftools.

 Note that rkbin is a >5GB download! This will take some time to clone and process the deltas.

<pre>
git clone -b quartz64 https://gitlab.com/pgwipeout/u-boot-rockchip.git
git clone -b rkbin https://github.com/JeffyCN/rockchip_mirrors.git rkbin
cd u-boot-rockchip
# If using Arch Linux, export CROSS_COMPILE=aarch64-linux-gnu-
export CROSS_COMPILE=aarch64-none-linux-gnu-
make rk3566-quartz64_defconfig
./make.sh
</pre>

<blockquote>
In the version I cloned (current as of 2022-01-02), I had to make a change to one line to get a clean compilation:

<pre>
diff --git a/lib/avb/libavb/avb_slot_verify.c b/lib/avb/libavb/avb_slot_verify.c
index 123701fc3b..64a1ce6450 100644
--- a/lib/avb/libavb/avb_slot_verify.c
+++ b/lib/avb/libavb/avb_slot_verify.c
@@ -296,7 +296,7 @@ static AvbSlotVerifyResult load_and_verify_hash_partition(
bool image_preloaded = false;
uint8_t* digest;
size_t digest_len;
- const char* found;
+ const char* found = NULL;
uint64_t image_size;
size_t expected_digest_len = 0;
uint8_t expected_digest_buf[AVB_SHA512_DIGEST_SIZE];
</pre>

For systems where the global python executable points to python2, compilation fails with an error related to pyelftools not being installed (even if it is). To fix this:
<pre>
diff --git a/make.sh b/make.sh
index 2bba05b4e4..cfe5b0afd5 100755
--- a/make.sh
+++ b/make.sh
@@ -758,7 +758,7 @@ function pack_fit_image()
fi

if [ "${ARM64_TRUSTZONE}" == "y" ]; then
- if ! python -c "import elftools" ; then
+ if ! python3 -c "import elftools" ; then
echo "ERROR: No python 'pyelftools', please: pip install pyelftools"
exit 1
fi
</pre>
</blockquote>

=== Entering Maskrom/Rockusb Mode ===

There are three ways to get into Maskrom/Rockusb mode:

==== The easy way ====

# Flip the device around so that the display faces down
# Lay the pen on the right side, with its tip pointing towards the speaker grill, and its magnet pointing towards the upper right corner of the label on the back (or place the magnetic cap from the pen on the spot marked on the back).
# Turn the device on and wait for it to show up in <code>lsusb</code>. It should now be in Loader mode, according to <code>rkdeveloptool list-devices</code> (note that "Loader" here indicates U-Boot's Rockusb; separately, booting with an erased eMMC displays "Maskrom" [not "Loader"] from the RK3566).
# Unplug the device and plug it back in. It should now be in Rockusb mode.

This can be a bit fiddly to get right, and may need a few tries.

==== The u-boot way ====
# Interrupt the u-boot startup using ctrl-c (while attached using an UART dongle)
# While in u-boot use the command "rockusb 0 mmc 0" to start rockusb mode.

One benefit from this is, that if you have an UART dongle that allows to simultaneous having an UART and USB connection, there is no need to plug and unplug cables and flipping the PineNote around and placing magnets.

This is especially helpful when changing back and forth between u-boot and rockusb, for instance when trying to develop u-boot.

==== Shorting test points ====

If the bootloader is broken/corrupted, you cannot get to Maskrom without opening up the device (it can be opened using spudger and a bit of patience).

Once inside, short TP1301 (GND) and TP1302 (eMMC_D0/FLASH_D0) with a small tweezers, this is how it looks on board view (credit to Caleb):

[[File:PineNote_Maskrom_TP.png|500px]]

Then plug the device to the computer and if you see the device with VID=2207/PID=350a then it should be in Maskrom mode, you can verify by typing <code>rkdeveloptool list-devices</code>.

<nowiki>Jan 07 15:04:13 melttower kernel: usb 1-14: New USB device found, idVendor=2207, idProduct=350a, bcdDevice= 1.00
Jan 07 15:04:13 melttower kernel: usb 1-14: New USB device strings: Mfr=0, Product=0, SerialNumber=0

$ rkdeveloptool list-devices
DevNo=1 Vid=0x2207,Pid=0x350a,LocationID=10e Maskrom</nowiki>

If nothing shows up, you can try to hold down the power button for 5 seconds and then try again.

=== Running rkdeveloptool ===

First, you'll want to make sure the device you've connected is in maskrom mode:

<pre>
./rkdeveloptool list
</pre>

It should output something like <code>DevNo=1 Vid=0x2207,Pid=0x350a,LocationID=202 Maskrom</code>. If it doesn't, see [[PineNote Development#Entering Maskrom Mode]].

You can now download u-boot onto it:
<pre>
./rkdeveloptool boot ../u-boot-rockchip/rk356x_spl_loader_v1.08.111.bin
</pre>

This should output <code>Downloading bootloader succeeded.</code>.

We can now verify that this worked using e.g. the "read flash info" command:

<pre>
./rkdeveloptool read-flash-info
</pre>

'''TODO:''' finish this section

=== Creating a mainline boot image ===

You can create a filesystem image that replaces the Android boot or recovery partition by doing roughly the following:

# Erase boot and dtbo with rkdeveloptool or fastboot (back them up first!!!)
# Create an ext2 partition image and mount it (fallocate, mkfs.ext2)
# Build your mainline kernel
# Copy the kernel, dtb and an initramfs to the root of the mounted image (use any old postmarketOS initramfs)
# Create a file in the root of the mounted image called <code>extlinux.conf</code> as described below
# Unmount the image and then use rkdeveloptool to flash it to the "recovery" partition on the pinenote (it's about the right size until we get around to replacing the partition layout).

== Using fastboot ==

Follow the steps for "Creating a mainline boot.img", but instead of flashing it with rkdeveloptool, use fastboot. You can enter fastboot in either of two ways:

# Use "reboot bootloader" from adb or a UART console.
# Get a U-Boot prompt and run <code>fastboot usb 0</code>.

= Mainline development =

== Status ==

Some work happening here: https://gitlab.com/calebccff/linux, the idea is to import the parts of the eink/ebc drivers which are open source and use the downstream u-boot framebuffer driver as a reference to create a basic framebuffer driver.

Currently mainline struggles to boot due to weird issues while probing fixed regulators (?). It also fails to detect eMMC.

Further work is being done here: https://github.com/smaeul/linux/commits/rk356x-ebc-dev. This has a complete device tree, with working eMMC. Pen input also works out of the box. Wi-Fi and BT work with firmware copied from the factory Android image.

== How to boot mainline ==

UART is currently REQUIRED for this to work! We depend on u-boot falling back to console. Once we have a prebuilt u-boot which will use extlinux by default, UART won't be needed anymore.

You can compile a u-boot that uses extlinux by default by following the instructions [https://github.com/JoshuaMulliken/pinenote_uboot/blob/aa9ecbd3d3e716f163f5a900824630f24e9f04ba/README.md#changing-default-boot-order here].

=== Getting to a U-Boot prompt ===

You can get to a U-Boot prompt by:

# Holding Ctrl-C while the display panel initializes.
# Wiping the "boot" partition.

=== Using sysboot ===

<code>extlinux.conf</code> should have the following contents:

<pre>
timeout 10
default MAINLINE
menu title boot prev kernel

label MAINLINE
kernel /vmlinuz
fdt /rk3566-pinenote.dtb
initrd /initramfs
append earlycon console=tty0 console=ttyS2,1500000n8 fw_devlink=off PMOS_NO_OUTPUT_REDIRECT
</pre>

At the u-boot console, run the following command to boot your mainline kernel:

<pre>
sysboot ${devtype} ${devnum}:9 any ${scriptaddr} extlinux.conf
</pre>

=== Booting with individual commands ===

Booting with individual commands can be useful when you need to temporarily add some kernel command line arguments. Use these or similar commands at the U-Boot shell:

load mmc 0:b ${kernel_addr_r} boot/Image
load mmc 0:b ${fdt_addr_r} boot/rk3566-pinenote.dtb
setenv bootargs ignore_loglevel root=/dev/mmcblk0p11 rootwait init=/bin/bash
booti ${kernel_addr_r} - ${fdt_addr_r}

== Configuration ==

=== Firmware ===

Copy WiFi/BT firmware from Android:
mkdir -p /cache/lib/firmware/brcm
cp /vendor/etc/firmware/fw_bcm43455c0_ag_cy.bin /cache/lib/firmware/brcm/brcmfmac43455-sdio.bin
cp /vendor/etc/firmware/nvram_ap6255_cy.txt /cache/lib/firmware/brcm/brcmfmac43455-sdio.txt
cp /cache/lib/firmware/BCM4345C0.hcd /cache/lib/firmware/brcm/BCM4345C0.hcd

Copy waveform partition (via previously dumped file):
adb root
adb push waveform.img /cache/lib/firmware/waveform.bin

Or via dd within Linux:
dd if=/dev/mmcblk0p3 of=/lib/firmware/waveform.bin bs=1k count=2048

=== Configuring the E-ink refresh mode ===
https://github.com/m-weigand/mw_pinenote_misc/tree/main/rockchip_ebc/patches contains information on how/where to write in /sys to alter the refresh mode

https://github.com/m-weigand/mw_pinenote_misc/tree/main/gnome_extension contains the gnome extension used in Maximilian image

=== Touchscreen and Pen In X.org ===

By default the pen config is flipped 180° (which makes it unusable) and the touchscreen doesn't work. Placing the following config in <code>/etc/X11/xorg.conf.d/50-touchscreen.conf</code> will fix both problems:

<pre>
Section "InputClass"
Identifier "evdev touchscreen"
MatchProduct "tt21000"
MatchIsTouchscreen "on"
Driver "evdev"
EndSection
Section "InputClass"
Identifier "RotateTouch"
MatchProduct "w9013"
Option "TransformationMatrix" "-1 0 1 0 -1 1 0 0 1"
EndSection
</pre>

PineNote Development

2022-12-25T14:40:29Z

Talpa: Some notes on backing up the MMC

This article seeks to provide general development information for the [[PineNote]]. If you are new and down to try a new installation process, the easiest way to get linux is likely to [https://wiki.pine64.org/wiki/PineNote_Development/Installing_Debian install Debian] -- NOTE THAT THIS INSTALLATION PROCESS IS VERY NEW. While many people have been using the kernel that will be installed safely at this point, the instructions for installing Debian via rootfs are very new. Take backups!

The more stable recommended approach is described below:

Start with [https://github.com/DorianRudolph/pinenotes Dorian's guide] which will guide you through getting Arch installed. For instructions on building the latest kernel, see [[PineNote Development/Building Kernel]]. For helpful configurations, see [[PineNote Development/Apps]]. For ways to pitch in, see [[PineNote Development/TODOs]]. To boot Linux by default instead of Android, see [[PineNote Development/Booting Linux]]. [https://www.youtube.com/watch?v=ZCLyJfbzbrU Here is a video] of a user running Manjaro and some apps on their PineNote on 9/10/2022.

= More Information =
== High-level developer new to embedded linux? ==
Here are some resources I have found helpful in learning to develop on embedded linux devices:
* Great youtube series introducing you to the kernel and lower-level components of Linux: https://www.youtube.com/watch?v=WiZ05pnHZqM
* https://embetronicx.com/
* https://bootlin.com/training/
* https://www.nand2tetris.org

== Notes Written by Some Developers ==

* https://github.com/m-weigand/mw_pinenote_misc (Not super legible "notes", but very helpful repo with patches, videos, etc)
** specifically see this section for helpful install/configure scripts: https://github.com/m-weigand/mw_pinenote_misc/tree/main/rockchip_ebc/patches#compiling.
* https://github.com/0cc4m/pinenote-misc
** patch for enabling gpu: https://github.com/0cc4m/pinenote-misc/blob/main/mesa-archlinux-arm/mesa/rockchip_ebc.patch
** prebuilt pkg's: https://github.com/0cc4m/pinenote-misc/releases
* https://pwarren.id.au/pinenote/build_notes.txt
* https://github.com/DorianRudolph/pinenotes
* https://github.com/tpwrules/nixos-pinenote

== Alternative to patching of mesa ==
Mesa needs to be patched to add the driver entry point. The alternative to this, is the renaming of the ebc driver to an existing mesa driver entry point. A good existing name can be "repaper". To change the driver name, edit in the kernel tree the following files: 
- replace "rockchip-ebc" with "repaper" in the two places in the file: drivers/gpu/drm/rockchip/rockchip_ebc.c 
- preventive, replace "repaper" with "repaper-disabled" in the two places in the file: drivers/gpu/drm/tiny/repaper.c 

== Building the most recent kernel ==
See [https://wiki.pine64.org/wiki/PineNote_Development/Building_Kernel here].

== Video of Factory Android OS ==

[https://www.youtube.com/watch?v=DWuTGgQHw98 PineNote Developer Edition w/Tech Demo Android OS (Video Only)]

Informal walkthrough of the factory Android installation on the PineNote Developer Edition, recorded by a community member (Apr 2022). This is useful to look back at the original OS after erasing it from your device, or to get some additional detail before your device arrives.

The video also includes a chapter at the end showing [https://www.youtube.com/watch?v=DWuTGgQHw98&t=802s how to enable Android Debug Bridge (`adb`) over USB]. Once enabled, keep the device powered and connect a USB cable directly to the PineNote (i.e. no UART breakout) to a computer running `adb`.

== Emulator for Developing/Testing Pinenote Apps ==
https://github.com/michaelshiel/picom-epaper

= Flashing Software =
Currently, the only ways to flash software are from the factory Android installation (UART shell, adb, or fastboot) or by using rkdeveloptool.

== Backup of the content of the internal MMC before you mess anything up ==
Especially the '''waveform''' partition contains data '''unique''' to your PineNote and is a prime candidate for backup.

But other partitions like uboot (need for any operation of the device) or the un-partitioned space at the beginning containing the GPT partition table (and presumably the VCOM setting for the e-ink display and maybe device mac addresses) contains data you may wish to backup.

Depending of your personal level of data hoarder you may want to backup more than this or even just everything (the large userdata partition is supposed to be able to be repopulated as empty space by Android)

In any case it is easier to restore/extract data from a backup than not having one if you need one.

=== Manually using rkdeveloptool ===
Dorian has some nice [https://github.com/DorianRudolph/pinenotes notes regarding the PineNote]

Don't forget to install a patched uboot for reading beyond 32MB and to respect the 2GB limit/bug of the current rkdeveloptool as per his notes

=== Automated backup using a script and rkdeveloptool ===
[https://github.com/talpadk/pinenote-backup pinenote-backup] is a python script for detecting the partitions and automating the backup of partitions or the whole disk

I also requires a patched u-boot but automatically handles the 2GB limit by splitting up larger reads into smaller ones

=== Using the factory Android installation ===
For any one knowing how and with which caveats: Write ME

=== Using a user installed Linux ===
A Linux installed to the cache partition should be able to easily backup everything over WiFi or to a USB stick/disk using dd

However the user would need to backup the cache partition themself (if they want that).

And more importantly they would only be getting the backup ''after'' they started playing with the content of the MMC.

== Side-by-side setup ==

It is possible to set up a partition for mainline development without disturbing the factory Android installation. This allows updating a mainline kernel, DTB, and initramfs over Wi-Fi until WiFi or USB OTG is working in mainline Linux.

=== Without Repartitioning ===

The recommended partition for this is <tt>mmcblk0p11</tt> aka <tt>/cache</tt>. It is large and already formatted as <tt>ext4</tt>, so it is readable from U-Boot. Here are some general steps:

# From the UART or adb shell, set up your chroot in <tt>/cache</tt>. I used the Alpine Linux rootfs tarball.
# Copy in your kernel and DTB, using for example <tt>scp</tt> or <tt>wget</tt> inside the chroot.
# Finally, create and boot an <code>extlinux.conf</code> as described below.

=== With Repartitioning ===

It is possible to shrink the <tt>userdata</tt> partition, and create a new partition at the end for use with mainline Linux. This provides much more space than <tt>cache</tt>. However, because <tt>userdata</tt> is formatted with <tt>f2fs</tt>, and that filesystem cannot be shrunk, resizing the partition requires wiping <tt>userdata</tt>.

# Back up any necessary files from userdata
# Boot to a mainline kernel from <tt>mmcblk0p11</tt>, either using that partition as rootfs (see above), or using an initramfs with repartitioning tools
# Modify the partition table with your favorite tool, e.g. <tt>fdisk</tt>, <tt>gdisk</tt>, or <tt>parted</tt>
# Reboot into <tt>fastboot</tt> and wipe <tt>userdata</tt>.
# Reboot into Android, where you can now chroot in and install your favorite distribution to the new partition.

== Using rkdeveloptool ==

rkdeveloptool is a command line utility built on libusb.

=== Downloading and Building rkdeveloptool ===

PINE64 develops [https://gitlab.com/pine64-org/quartz-bsp/rkdeveloptool its own updated fork of rkdeveloptool on GitLab].

You will need to have libusb 1.0, its development headers and scdoc installed.

<pre>
git clone https://gitlab.com/pine64-org/quartz-bsp/rkdeveloptool.git
cd rkdeveloptool
mkdir build
cd build
cmake ..
</pre>

This sets up all the build files. You can then compile with <code>make</code> inside the build directory.

After you're done, you'll likely also need to install the udev rules, or else your user won't have permission to access the USB devices:

<pre>
sudo cp 99-rk-rockusb.rules /etc/udev/rules.d/
sudo udevadm control --reload
</pre>

Copying the udev rules is also performed automatically when you <code>make install</code>.

=== Building Downstream U-Boot ===

While in maskrom mode, we need to have a u-boot to download onto the device for any of the other commands to work. To build you'll also need to install device-tree-compiler.

You also need to install Python and pyelftools.

 Note that rkbin is a >5GB download! This will take some time to clone and process the deltas.

<pre>
git clone -b quartz64 https://gitlab.com/pgwipeout/u-boot-rockchip.git
git clone -b rkbin https://github.com/JeffyCN/rockchip_mirrors.git rkbin
cd u-boot-rockchip
# If using Arch Linux, export CROSS_COMPILE=aarch64-linux-gnu-
export CROSS_COMPILE=aarch64-none-linux-gnu-
make rk3566-quartz64_defconfig
./make.sh
</pre>

<blockquote>
In the version I cloned (current as of 2022-01-02), I had to make a change to one line to get a clean compilation:

<pre>
diff --git a/lib/avb/libavb/avb_slot_verify.c b/lib/avb/libavb/avb_slot_verify.c
index 123701fc3b..64a1ce6450 100644
--- a/lib/avb/libavb/avb_slot_verify.c
+++ b/lib/avb/libavb/avb_slot_verify.c
@@ -296,7 +296,7 @@ static AvbSlotVerifyResult load_and_verify_hash_partition(
bool image_preloaded = false;
uint8_t* digest;
size_t digest_len;
- const char* found;
+ const char* found = NULL;
uint64_t image_size;
size_t expected_digest_len = 0;
uint8_t expected_digest_buf[AVB_SHA512_DIGEST_SIZE];
</pre>

For systems where the global python executable points to python2, compilation fails with an error related to pyelftools not being installed (even if it is). To fix this:
<pre>
diff --git a/make.sh b/make.sh
index 2bba05b4e4..cfe5b0afd5 100755
--- a/make.sh
+++ b/make.sh
@@ -758,7 +758,7 @@ function pack_fit_image()
fi

if [ "${ARM64_TRUSTZONE}" == "y" ]; then
- if ! python -c "import elftools" ; then
+ if ! python3 -c "import elftools" ; then
echo "ERROR: No python 'pyelftools', please: pip install pyelftools"
exit 1
fi
</pre>
</blockquote>

=== Entering Maskrom/Rockusb Mode ===

There are three ways to get into Maskrom/Rockusb mode:

==== The easy way ====

# Flip the device around so that the display faces down
# Lay the pen on the right side, with its tip pointing towards the speaker grill, and its magnet pointing towards the upper right corner of the label on the back (or place the magnetic cap from the pen on the spot marked on the back).
# Turn the device on and wait for it to show up in <code>lsusb</code>. It should now be in Loader mode, according to <code>rkdeveloptool list-devices</code> (note that "Loader" here indicates U-Boot's Rockusb; separately, booting with an erased eMMC displays "Maskrom" [not "Loader"] from the RK3566).
# Unplug the device and plug it back in. It should now be in Rockusb mode.

This can be a bit fiddly to get right, and may need a few tries.

==== The u-boot way ====
# Interrupt the u-boot startup using ctrl-c (while attached using an UART dongle)
# While in u-boot use the command "rockusb 0 mmc 0" to start rockusb mode.

One benefit from this is, that if you have an UART dongle that allows to simultaneous having an UART and USB connection, there is no need to plug and unplug cables and flipping the PineNote around and placing magnets.

This is especially helpful when changing back and forth between u-boot and rockusb, for instance when trying to develop u-boot.

==== Shorting test points ====

If the bootloader is broken/corrupted, you cannot get to Maskrom without opening up the device (it can be opened using spudger and a bit of patience).

Once inside, short TP1301 (GND) and TP1302 (eMMC_D0/FLASH_D0) with a small tweezers, this is how it looks on board view (credit to Caleb):

[[File:PineNote_Maskrom_TP.png|500px]]

Then plug the device to the computer and if you see the device with VID=2207/PID=350a then it should be in Maskrom mode, you can verify by typing <code>rkdeveloptool list-devices</code>.

<nowiki>Jan 07 15:04:13 melttower kernel: usb 1-14: New USB device found, idVendor=2207, idProduct=350a, bcdDevice= 1.00
Jan 07 15:04:13 melttower kernel: usb 1-14: New USB device strings: Mfr=0, Product=0, SerialNumber=0

$ rkdeveloptool list-devices
DevNo=1 Vid=0x2207,Pid=0x350a,LocationID=10e Maskrom</nowiki>

If nothing shows up, you can try to hold down the power button for 5 seconds and then try again.

=== Running rkdeveloptool ===

First, you'll want to make sure the device you've connected is in maskrom mode:

<pre>
./rkdeveloptool list
</pre>

It should output something like <code>DevNo=1 Vid=0x2207,Pid=0x350a,LocationID=202 Maskrom</code>. If it doesn't, see [[PineNote Development#Entering Maskrom Mode]].

You can now download u-boot onto it:
<pre>
./rkdeveloptool boot ../u-boot-rockchip/rk356x_spl_loader_v1.08.111.bin
</pre>

This should output <code>Downloading bootloader succeeded.</code>.

We can now verify that this worked using e.g. the "read flash info" command:

<pre>
./rkdeveloptool read-flash-info
</pre>

'''TODO:''' finish this section

=== Creating a mainline boot image ===

You can create a filesystem image that replaces the Android boot or recovery partition by doing roughly the following:

# Erase boot and dtbo with rkdeveloptool or fastboot (back them up first!!!)
# Create an ext2 partition image and mount it (fallocate, mkfs.ext2)
# Build your mainline kernel
# Copy the kernel, dtb and an initramfs to the root of the mounted image (use any old postmarketOS initramfs)
# Create a file in the root of the mounted image called <code>extlinux.conf</code> as described below
# Unmount the image and then use rkdeveloptool to flash it to the "recovery" partition on the pinenote (it's about the right size until we get around to replacing the partition layout).

== Using fastboot ==

Follow the steps for "Creating a mainline boot.img", but instead of flashing it with rkdeveloptool, use fastboot. You can enter fastboot in either of two ways:

# Use "reboot bootloader" from adb or a UART console.
# Get a U-Boot prompt and run <code>fastboot usb 0</code>.

= Mainline development =

== Status ==

Some work happening here: https://gitlab.com/calebccff/linux, the idea is to import the parts of the eink/ebc drivers which are open source and use the downstream u-boot framebuffer driver as a reference to create a basic framebuffer driver.

Currently mainline struggles to boot due to weird issues while probing fixed regulators (?). It also fails to detect eMMC.

Further work is being done here: https://github.com/smaeul/linux/commits/rk356x-ebc-dev. This has a complete device tree, with working eMMC. Pen input also works out of the box. Wi-Fi and BT work with firmware copied from the factory Android image.

== How to boot mainline ==

UART is currently REQUIRED for this to work! We depend on u-boot falling back to console. Once we have a prebuilt u-boot which will use extlinux by default, UART won't be needed anymore.

You can compile a u-boot that uses extlinux by default by following the instructions [https://github.com/JoshuaMulliken/pinenote_uboot/blob/aa9ecbd3d3e716f163f5a900824630f24e9f04ba/README.md#changing-default-boot-order here].

=== Getting to a U-Boot prompt ===

You can get to a U-Boot prompt by:

# Holding Ctrl-C while the display panel initializes.
# Wiping the "boot" partition.

=== Using sysboot ===

<code>extlinux.conf</code> should have the following contents:

<pre>
timeout 10
default MAINLINE
menu title boot prev kernel

label MAINLINE
kernel /vmlinuz
fdt /rk3566-pinenote.dtb
initrd /initramfs
append earlycon console=tty0 console=ttyS2,1500000n8 fw_devlink=off PMOS_NO_OUTPUT_REDIRECT
</pre>

At the u-boot console, run the following command to boot your mainline kernel:

<pre>
sysboot ${devtype} ${devnum}:9 any ${scriptaddr} extlinux.conf
</pre>

=== Booting with individual commands ===

Booting with individual commands can be useful when you need to temporarily add some kernel command line arguments. Use these or similar commands at the U-Boot shell:

load mmc 0:b ${kernel_addr_r} boot/Image
load mmc 0:b ${fdt_addr_r} boot/rk3566-pinenote.dtb
setenv bootargs ignore_loglevel root=/dev/mmcblk0p11 rootwait init=/bin/bash
booti ${kernel_addr_r} - ${fdt_addr_r}

== Configuration ==

=== Firmware ===

Copy WiFi/BT firmware from Android:
mkdir -p /cache/lib/firmware/brcm
cp /vendor/etc/firmware/fw_bcm43455c0_ag_cy.bin /cache/lib/firmware/brcm/brcmfmac43455-sdio.bin
cp /vendor/etc/firmware/nvram_ap6255_cy.txt /cache/lib/firmware/brcm/brcmfmac43455-sdio.txt
cp /cache/lib/firmware/BCM4345C0.hcd /cache/lib/firmware/brcm/BCM4345C0.hcd

Copy waveform partition (via previously dumped file):
adb root
adb push waveform.img /cache/lib/firmware/waveform.bin

Or via dd within Linux:
dd if=/dev/mmcblk0p3 of=/lib/firmware/waveform.bin bs=1k count=2048

=== Touchscreen and Pen In X.org ===

By default the pen config is flipped 180° (which makes it unusable) and the touchscreen doesn't work. Placing the following config in <code>/etc/X11/xorg.conf.d/50-touchscreen.conf</code> will fix both problems:

<pre>
Section "InputClass"
Identifier "evdev touchscreen"
MatchProduct "tt21000"
MatchIsTouchscreen "on"
Driver "evdev"
EndSection
Section "InputClass"
Identifier "RotateTouch"
MatchProduct "w9013"
Option "TransformationMatrix" "-1 0 1 0 -1 1 0 0 1"
EndSection
</pre>

PineNote Development

2022-12-10T19:52:38Z

Talpa: Description of what the test points TP1301 and TP1302 are

This article seeks to provide general development information for the [[PineNote]]. If you are new and down to try a new installation process, the easiest way to get linux is likely to [https://wiki.pine64.org/wiki/PineNote_Development/Installing_Debian install Debian] -- NOTE THAT THIS INSTALLATION PROCESS IS VERY NEW. While many people have been using the kernel that will be installed safely at this point, the instructions for installing Debian via rootfs are very new. Take backups!

The more stable recommended approach is described below:

Start with [https://github.com/DorianRudolph/pinenotes Dorian's guide] which will guide you through getting Arch installed. For instructions on building the latest kernel, see [[PineNote Development/Building Kernel]]. For helpful configurations, see [[PineNote Development/Apps]]. For ways to pitch in, see [[PineNote Development/TODOs]]. To boot Linux by default instead of Android, see [[PineNote Development/Booting Linux]]. [https://www.youtube.com/watch?v=ZCLyJfbzbrU Here is a video] of a user running Manjaro and some apps on their PineNote on 9/10/2022.

= More Information =
== High-level developer new to embedded linux? ==
Here are some resources I have found helpful in learning to develop on embedded linux devices:
* Great youtube series introducing you to the kernel and lower-level components of Linux: https://www.youtube.com/watch?v=WiZ05pnHZqM
* https://embetronicx.com/
* https://bootlin.com/training/
* https://www.nand2tetris.org

== Notes Written by Some Developers ==

* https://github.com/m-weigand/mw_pinenote_misc (Not super legible "notes", but very helpful repo with patches, videos, etc)
** specifically see this section for helpful install/configure scripts: https://github.com/m-weigand/mw_pinenote_misc/tree/main/rockchip_ebc/patches#compiling.
* https://github.com/0cc4m/pinenote-misc
** patch for enabling gpu: https://github.com/0cc4m/pinenote-misc/blob/main/mesa-archlinux-arm/mesa/rockchip_ebc.patch
** prebuilt pkg's: https://github.com/0cc4m/pinenote-misc/releases
* https://pwarren.id.au/pinenote/build_notes.txt
* https://github.com/DorianRudolph/pinenotes
* https://github.com/tpwrules/nixos-pinenote

== Alternative to patching of mesa ==
Mesa needs to be patched to add the driver entry point. The alternative to this, is the renaming of the ebc driver to an existing mesa driver entry point. A good existing name can be "repaper". To change the driver name, edit in the kernel tree the following files: 
- replace "rockchip-ebc" with "repaper" in the two places in the file: drivers/gpu/drm/rockchip/rockchip_ebc.c 
- preventive, replace "repaper" with "repaper-disabled" in the two places in the file: drivers/gpu/drm/tiny/repaper.c 

== Building the most recent kernel ==
See [https://wiki.pine64.org/wiki/PineNote_Development/Building_Kernel here].

== Video of Factory Android OS ==

[https://www.youtube.com/watch?v=DWuTGgQHw98 PineNote Developer Edition w/Tech Demo Android OS (Video Only)]

Informal walkthrough of the factory Android installation on the PineNote Developer Edition, recorded by a community member (Apr 2022). This is useful to look back at the original OS after erasing it from your device, or to get some additional detail before your device arrives.

The video also includes a chapter at the end showing [https://www.youtube.com/watch?v=DWuTGgQHw98&t=802s how to enable Android Debug Bridge (`adb`) over USB]. Once enabled, keep the device powered and connect a USB cable directly to the PineNote (i.e. no UART breakout) to a computer running `adb`.

== Emulator for Developing/Testing Pinenote Apps ==
https://github.com/michaelshiel/picom-epaper

= Flashing Software =

Currently, the only ways to flash software are from the factory Android installation (UART shell, adb, or fastboot) or by using rkdeveloptool.

== Side-by-side setup ==

It is possible to set up a partition for mainline development without disturbing the factory Android installation. This allows updating a mainline kernel, DTB, and initramfs over Wi-Fi until WiFi or USB OTG is working in mainline Linux.

=== Without Repartitioning ===

The recommended partition for this is <tt>mmcblk0p11</tt> aka <tt>/cache</tt>. It is large and already formatted as <tt>ext4</tt>, so it is readable from U-Boot. Here are some general steps:

# From the UART or adb shell, set up your chroot in <tt>/cache</tt>. I used the Alpine Linux rootfs tarball.
# Copy in your kernel and DTB, using for example <tt>scp</tt> or <tt>wget</tt> inside the chroot.
# Finally, create and boot an <code>extlinux.conf</code> as described below.

=== With Repartitioning ===

It is possible to shrink the <tt>userdata</tt> partition, and create a new partition at the end for use with mainline Linux. This provides much more space than <tt>cache</tt>. However, because <tt>userdata</tt> is formatted with <tt>f2fs</tt>, and that filesystem cannot be shrunk, resizing the partition requires wiping <tt>userdata</tt>.

# Back up any necessary files from userdata
# Boot to a mainline kernel from <tt>mmcblk0p11</tt>, either using that partition as rootfs (see above), or using an initramfs with repartitioning tools
# Modify the partition table with your favorite tool, e.g. <tt>fdisk</tt>, <tt>gdisk</tt>, or <tt>parted</tt>
# Reboot into <tt>fastboot</tt> and wipe <tt>userdata</tt>.
# Reboot into Android, where you can now chroot in and install your favorite distribution to the new partition.

== Using rkdeveloptool ==

rkdeveloptool is a command line utility built on libusb.

=== Downloading and Building rkdeveloptool ===

PINE64 develops [https://gitlab.com/pine64-org/quartz-bsp/rkdeveloptool its own updated fork of rkdeveloptool on GitLab].

You will need to have libusb 1.0, its development headers and scdoc installed.

<pre>
git clone https://gitlab.com/pine64-org/quartz-bsp/rkdeveloptool.git
cd rkdeveloptool
mkdir build
cd build
cmake ..
</pre>

This sets up all the build files. You can then compile with <code>make</code> inside the build directory.

After you're done, you'll likely also need to install the udev rules, or else your user won't have permission to access the USB devices:

<pre>
sudo cp 99-rk-rockusb.rules /etc/udev/rules.d/
sudo udevadm control --reload
</pre>

Copying the udev rules is also performed automatically when you <code>make install</code>.

=== Building Downstream U-Boot ===

While in maskrom mode, we need to have a u-boot to download onto the device for any of the other commands to work. To build you'll also need to install device-tree-compiler.

You also need to install Python and pyelftools.

 Note that rkbin is a >5GB download! This will take some time to clone and process the deltas.

<pre>
git clone -b quartz64 https://gitlab.com/pgwipeout/u-boot-rockchip.git
git clone -b rkbin https://github.com/JeffyCN/rockchip_mirrors.git rkbin
cd u-boot-rockchip
# If using Arch Linux, export CROSS_COMPILE=aarch64-linux-gnu-
export CROSS_COMPILE=aarch64-none-linux-gnu-
make rk3566-quartz64_defconfig
./make.sh
</pre>

<blockquote>
In the version I cloned (current as of 2022-01-02), I had to make a change to one line to get a clean compilation:

<pre>
diff --git a/lib/avb/libavb/avb_slot_verify.c b/lib/avb/libavb/avb_slot_verify.c
index 123701fc3b..64a1ce6450 100644
--- a/lib/avb/libavb/avb_slot_verify.c
+++ b/lib/avb/libavb/avb_slot_verify.c
@@ -296,7 +296,7 @@ static AvbSlotVerifyResult load_and_verify_hash_partition(
bool image_preloaded = false;
uint8_t* digest;
size_t digest_len;
- const char* found;
+ const char* found = NULL;
uint64_t image_size;
size_t expected_digest_len = 0;
uint8_t expected_digest_buf[AVB_SHA512_DIGEST_SIZE];
</pre>

For systems where the global python executable points to python2, compilation fails with an error related to pyelftools not being installed (even if it is). To fix this:
<pre>
diff --git a/make.sh b/make.sh
index 2bba05b4e4..cfe5b0afd5 100755
--- a/make.sh
+++ b/make.sh
@@ -758,7 +758,7 @@ function pack_fit_image()
fi

if [ "${ARM64_TRUSTZONE}" == "y" ]; then
- if ! python -c "import elftools" ; then
+ if ! python3 -c "import elftools" ; then
echo "ERROR: No python 'pyelftools', please: pip install pyelftools"
exit 1
fi
</pre>
</blockquote>

=== Entering Maskrom/Rockusb Mode ===

There are three ways to get into Maskrom/Rockusb mode:

==== The easy way ====

# Flip the device around so that the display faces down
# Lay the pen on the right side, with its tip pointing towards the speaker grill, and its magnet pointing towards the upper right corner of the label on the back (or place the magnetic cap from the pen on the spot marked on the back).
# Turn the device on and wait for it to show up in <code>lsusb</code>. It should now be in Loader mode, according to <code>rkdeveloptool list-devices</code> (note that "Loader" here indicates U-Boot's Rockusb; separately, booting with an erased eMMC displays "Maskrom" [not "Loader"] from the RK3566).
# Unplug the device and plug it back in. It should now be in Rockusb mode.

This can be a bit fiddly to get right, and may need a few tries.

==== The u-boot way ====
# Interrupt the u-boot startup using ctrl-c (while attached using an UART dongle)
# While in u-boot use the command "rockusb 0 mmc 0" to start rockusb mode.

One benefit from this is, that if you have an UART dongle that allows to simultaneous having an UART and USB connection, there is no need to plug and unplug cables and flipping the PineNote around and placing magnets.

This is especially helpful when changing back and forth between u-boot and rockusb, for instance when trying to develop u-boot.

==== Shorting test points ====

If the bootloader is broken/corrupted, you cannot get to Maskrom without opening up the device (it can be opened using spudger and a bit of patience).

Once inside, short TP1301 (GND) and TP1302 (eMMC_D0/FLASH_D0) with a small tweezers, this is how it looks on board view (credit to Caleb):

[[File:PineNote_Maskrom_TP.png|500px]]

Then plug the device to the computer and if you see the device with VID=2207/PID=350a then it should be in Maskrom mode, you can verify by typing <code>rkdeveloptool list-devices</code>.

<nowiki>Jan 07 15:04:13 melttower kernel: usb 1-14: New USB device found, idVendor=2207, idProduct=350a, bcdDevice= 1.00
Jan 07 15:04:13 melttower kernel: usb 1-14: New USB device strings: Mfr=0, Product=0, SerialNumber=0

$ rkdeveloptool list-devices
DevNo=1 Vid=0x2207,Pid=0x350a,LocationID=10e Maskrom</nowiki>

If nothing shows up, you can try to hold down the power button for 5 seconds and then try again.

=== Running rkdeveloptool ===

First, you'll want to make sure the device you've connected is in maskrom mode:

<pre>
./rkdeveloptool list
</pre>

It should output something like <code>DevNo=1 Vid=0x2207,Pid=0x350a,LocationID=202 Maskrom</code>. If it doesn't, see [[PineNote Development#Entering Maskrom Mode]].

You can now download u-boot onto it:
<pre>
./rkdeveloptool boot ../u-boot-rockchip/rk356x_spl_loader_v1.08.111.bin
</pre>

This should output <code>Downloading bootloader succeeded.</code>.

We can now verify that this worked using e.g. the "read flash info" command:

<pre>
./rkdeveloptool read-flash-info
</pre>

'''TODO:''' finish this section

=== Creating a mainline boot image ===

You can create a filesystem image that replaces the Android boot or recovery partition by doing roughly the following:

# Erase boot and dtbo with rkdeveloptool or fastboot (back them up first!!!)
# Create an ext2 partition image and mount it (fallocate, mkfs.ext2)
# Build your mainline kernel
# Copy the kernel, dtb and an initramfs to the root of the mounted image (use any old postmarketOS initramfs)
# Create a file in the root of the mounted image called <code>extlinux.conf</code> as described below
# Unmount the image and then use rkdeveloptool to flash it to the "recovery" partition on the pinenote (it's about the right size until we get around to replacing the partition layout).

== Using fastboot ==

Follow the steps for "Creating a mainline boot.img", but instead of flashing it with rkdeveloptool, use fastboot. You can enter fastboot in either of two ways:

# Use "reboot bootloader" from adb or a UART console.
# Get a U-Boot prompt and run <code>fastboot usb 0</code>.

= Mainline development =

== Status ==

Some work happening here: https://gitlab.com/calebccff/linux, the idea is to import the parts of the eink/ebc drivers which are open source and use the downstream u-boot framebuffer driver as a reference to create a basic framebuffer driver.

Currently mainline struggles to boot due to weird issues while probing fixed regulators (?). It also fails to detect eMMC.

Further work is being done here: https://github.com/smaeul/linux/commits/rk356x-ebc-dev. This has a complete device tree, with working eMMC. Pen input also works out of the box. Wi-Fi and BT work with firmware copied from the factory Android image.

== How to boot mainline ==

UART is currently REQUIRED for this to work! We depend on u-boot falling back to console. Once we have a prebuilt u-boot which will use extlinux by default, UART won't be needed anymore.

You can compile a u-boot that uses extlinux by default by following the instructions [https://github.com/JoshuaMulliken/pinenote_uboot/blob/aa9ecbd3d3e716f163f5a900824630f24e9f04ba/README.md#changing-default-boot-order here].

=== Getting to a U-Boot prompt ===

You can get to a U-Boot prompt by:

# Holding Ctrl-C while the display panel initializes.
# Wiping the "boot" partition.

=== Using sysboot ===

<code>extlinux.conf</code> should have the following contents:

<pre>
timeout 10
default MAINLINE
menu title boot prev kernel

label MAINLINE
kernel /vmlinuz
fdt /rk3566-pinenote.dtb
initrd /initramfs
append earlycon console=tty0 console=ttyS2,1500000n8 fw_devlink=off PMOS_NO_OUTPUT_REDIRECT
</pre>

At the u-boot console, run the following command to boot your mainline kernel:

<pre>
sysboot ${devtype} ${devnum}:9 any ${scriptaddr} extlinux.conf
</pre>

=== Booting with individual commands ===

Booting with individual commands can be useful when you need to temporarily add some kernel command line arguments. Use these or similar commands at the U-Boot shell:

load mmc 0:b ${kernel_addr_r} boot/Image
load mmc 0:b ${fdt_addr_r} boot/rk3566-pinenote.dtb
setenv bootargs ignore_loglevel root=/dev/mmcblk0p11 rootwait init=/bin/bash
booti ${kernel_addr_r} - ${fdt_addr_r}

== Configuration ==

=== Firmware ===

Copy WiFi/BT firmware from Android:
mkdir -p /cache/lib/firmware/brcm
cp /vendor/etc/firmware/fw_bcm43455c0_ag_cy.bin /cache/lib/firmware/brcm/brcmfmac43455-sdio.bin
cp /vendor/etc/firmware/nvram_ap6255_cy.txt /cache/lib/firmware/brcm/brcmfmac43455-sdio.txt
cp /cache/lib/firmware/BCM4345C0.hcd /cache/lib/firmware/brcm/BCM4345C0.hcd

Copy waveform partition (via previously dumped file):
adb root
adb push waveform.img /cache/lib/firmware/waveform.bin

Or via dd within Linux:
dd if=/dev/mmcblk0p3 of=/lib/firmware/waveform.bin bs=1k count=2048

=== Touchscreen and Pen In X.org ===

By default the pen config is flipped 180° (which makes it unusable) and the touchscreen doesn't work. Placing the following config in <code>/etc/X11/xorg.conf.d/50-touchscreen.conf</code> will fix both problems:

<pre>
Section "InputClass"
Identifier "evdev touchscreen"
MatchProduct "tt21000"
MatchIsTouchscreen "on"
Driver "evdev"
EndSection
Section "InputClass"
Identifier "RotateTouch"
MatchProduct "w9013"
Option "TransformationMatrix" "-1 0 1 0 -1 1 0 0 1"
EndSection
</pre>

PineNote Development

2022-12-10T13:06:46Z

Talpa: /* The u-boot way */

This article seeks to provide general development information for the [[PineNote]]. If you are new and down to try a new installation process, the easiest way to get linux is likely to [https://wiki.pine64.org/wiki/PineNote_Development/Installing_Debian install Debian] -- NOTE THAT THIS INSTALLATION PROCESS IS VERY NEW. While many people have been using the kernel that will be installed safely at this point, the instructions for installing Debian via rootfs are very new. Take backups!

The more stable recommended approach is described below:

Start with [https://github.com/DorianRudolph/pinenotes Dorian's guide] which will guide you through getting Arch installed. For instructions on building the latest kernel, see [[PineNote Development/Building Kernel]]. For helpful configurations, see [[PineNote Development/Apps]]. For ways to pitch in, see [[PineNote Development/TODOs]]. To boot Linux by default instead of Android, see [[PineNote Development/Booting Linux]]. [https://www.youtube.com/watch?v=ZCLyJfbzbrU Here is a video] of a user running Manjaro and some apps on their PineNote on 9/10/2022.

= More Information =
== High-level developer new to embedded linux? ==
Here are some resources I have found helpful in learning to develop on embedded linux devices:
* Great youtube series introducing you to the kernel and lower-level components of Linux: https://www.youtube.com/watch?v=WiZ05pnHZqM
* https://embetronicx.com/
* https://bootlin.com/training/
* https://www.nand2tetris.org

== Notes Written by Some Developers ==

* https://github.com/m-weigand/mw_pinenote_misc (Not super legible "notes", but very helpful repo with patches, videos, etc)
** specifically see this section for helpful install/configure scripts: https://github.com/m-weigand/mw_pinenote_misc/tree/main/rockchip_ebc/patches#compiling.
* https://github.com/0cc4m/pinenote-misc
** patch for enabling gpu: https://github.com/0cc4m/pinenote-misc/blob/main/mesa-archlinux-arm/mesa/rockchip_ebc.patch
** prebuilt pkg's: https://github.com/0cc4m/pinenote-misc/releases
* https://pwarren.id.au/pinenote/build_notes.txt
* https://github.com/DorianRudolph/pinenotes
* https://github.com/tpwrules/nixos-pinenote

== Alternative to patching of mesa ==
Mesa needs to be patched to add the driver entry point. The alternative to this, is the renaming of the ebc driver to an existing mesa driver entry point. A good existing name can be "repaper". To change the driver name, edit in the kernel tree the following files: 
- replace "rockchip-ebc" with "repaper" in the two places in the file: drivers/gpu/drm/rockchip/rockchip_ebc.c 
- preventive, replace "repaper" with "repaper-disabled" in the two places in the file: drivers/gpu/drm/tiny/repaper.c 

== Building the most recent kernel ==
See [https://wiki.pine64.org/wiki/PineNote_Development/Building_Kernel here].

== Video of Factory Android OS ==

[https://www.youtube.com/watch?v=DWuTGgQHw98 PineNote Developer Edition w/Tech Demo Android OS (Video Only)]

Informal walkthrough of the factory Android installation on the PineNote Developer Edition, recorded by a community member (Apr 2022). This is useful to look back at the original OS after erasing it from your device, or to get some additional detail before your device arrives.

The video also includes a chapter at the end showing [https://www.youtube.com/watch?v=DWuTGgQHw98&t=802s how to enable Android Debug Bridge (`adb`) over USB]. Once enabled, keep the device powered and connect a USB cable directly to the PineNote (i.e. no UART breakout) to a computer running `adb`.

== Emulator for Developing/Testing Pinenote Apps ==
https://github.com/michaelshiel/picom-epaper

= Flashing Software =

Currently, the only ways to flash software are from the factory Android installation (UART shell, adb, or fastboot) or by using rkdeveloptool.

== Side-by-side setup ==

It is possible to set up a partition for mainline development without disturbing the factory Android installation. This allows updating a mainline kernel, DTB, and initramfs over Wi-Fi until WiFi or USB OTG is working in mainline Linux.

=== Without Repartitioning ===

The recommended partition for this is <tt>mmcblk0p11</tt> aka <tt>/cache</tt>. It is large and already formatted as <tt>ext4</tt>, so it is readable from U-Boot. Here are some general steps:

# From the UART or adb shell, set up your chroot in <tt>/cache</tt>. I used the Alpine Linux rootfs tarball.
# Copy in your kernel and DTB, using for example <tt>scp</tt> or <tt>wget</tt> inside the chroot.
# Finally, create and boot an <code>extlinux.conf</code> as described below.

=== With Repartitioning ===

It is possible to shrink the <tt>userdata</tt> partition, and create a new partition at the end for use with mainline Linux. This provides much more space than <tt>cache</tt>. However, because <tt>userdata</tt> is formatted with <tt>f2fs</tt>, and that filesystem cannot be shrunk, resizing the partition requires wiping <tt>userdata</tt>.

# Back up any necessary files from userdata
# Boot to a mainline kernel from <tt>mmcblk0p11</tt>, either using that partition as rootfs (see above), or using an initramfs with repartitioning tools
# Modify the partition table with your favorite tool, e.g. <tt>fdisk</tt>, <tt>gdisk</tt>, or <tt>parted</tt>
# Reboot into <tt>fastboot</tt> and wipe <tt>userdata</tt>.
# Reboot into Android, where you can now chroot in and install your favorite distribution to the new partition.

== Using rkdeveloptool ==

rkdeveloptool is a command line utility built on libusb.

=== Downloading and Building rkdeveloptool ===

PINE64 develops [https://gitlab.com/pine64-org/quartz-bsp/rkdeveloptool its own updated fork of rkdeveloptool on GitLab].

You will need to have libusb 1.0, its development headers and scdoc installed.

<pre>
git clone https://gitlab.com/pine64-org/quartz-bsp/rkdeveloptool.git
cd rkdeveloptool
mkdir build
cd build
cmake ..
</pre>

This sets up all the build files. You can then compile with <code>make</code> inside the build directory.

After you're done, you'll likely also need to install the udev rules, or else your user won't have permission to access the USB devices:

<pre>
sudo cp 99-rk-rockusb.rules /etc/udev/rules.d/
sudo udevadm control --reload
</pre>

Copying the udev rules is also performed automatically when you <code>make install</code>.

=== Building Downstream U-Boot ===

While in maskrom mode, we need to have a u-boot to download onto the device for any of the other commands to work. To build you'll also need to install device-tree-compiler.

You also need to install Python and pyelftools.

 Note that rkbin is a >5GB download! This will take some time to clone and process the deltas.

<pre>
git clone -b quartz64 https://gitlab.com/pgwipeout/u-boot-rockchip.git
git clone -b rkbin https://github.com/JeffyCN/rockchip_mirrors.git rkbin
cd u-boot-rockchip
# If using Arch Linux, export CROSS_COMPILE=aarch64-linux-gnu-
export CROSS_COMPILE=aarch64-none-linux-gnu-
make rk3566-quartz64_defconfig
./make.sh
</pre>

<blockquote>
In the version I cloned (current as of 2022-01-02), I had to make a change to one line to get a clean compilation:

<pre>
diff --git a/lib/avb/libavb/avb_slot_verify.c b/lib/avb/libavb/avb_slot_verify.c
index 123701fc3b..64a1ce6450 100644
--- a/lib/avb/libavb/avb_slot_verify.c
+++ b/lib/avb/libavb/avb_slot_verify.c
@@ -296,7 +296,7 @@ static AvbSlotVerifyResult load_and_verify_hash_partition(
bool image_preloaded = false;
uint8_t* digest;
size_t digest_len;
- const char* found;
+ const char* found = NULL;
uint64_t image_size;
size_t expected_digest_len = 0;
uint8_t expected_digest_buf[AVB_SHA512_DIGEST_SIZE];
</pre>

For systems where the global python executable points to python2, compilation fails with an error related to pyelftools not being installed (even if it is). To fix this:
<pre>
diff --git a/make.sh b/make.sh
index 2bba05b4e4..cfe5b0afd5 100755
--- a/make.sh
+++ b/make.sh
@@ -758,7 +758,7 @@ function pack_fit_image()
fi

if [ "${ARM64_TRUSTZONE}" == "y" ]; then
- if ! python -c "import elftools" ; then
+ if ! python3 -c "import elftools" ; then
echo "ERROR: No python 'pyelftools', please: pip install pyelftools"
exit 1
fi
</pre>
</blockquote>

=== Entering Maskrom/Rockusb Mode ===

There are three ways to get into Maskrom/Rockusb mode:

==== The easy way ====

# Flip the device around so that the display faces down
# Lay the pen on the right side, with its tip pointing towards the speaker grill, and its magnet pointing towards the upper right corner of the label on the back (or place the magnetic cap from the pen on the spot marked on the back).
# Turn the device on and wait for it to show up in <code>lsusb</code>. It should now be in Loader mode, according to <code>rkdeveloptool list-devices</code> (note that "Loader" here indicates U-Boot's Rockusb; separately, booting with an erased eMMC displays "Maskrom" [not "Loader"] from the RK3566).
# Unplug the device and plug it back in. It should now be in Rockusb mode.

This can be a bit fiddly to get right, and may need a few tries.

==== The u-boot way ====
# Interrupt the u-boot startup using ctrl-c (while attached using an UART dongle)
# While in u-boot use the command "rockusb 0 mmc 0" to start rockusb mode.

One benefit from this is, that if you have an UART dongle that allows to simultaneous having an UART and USB connection, there is no need to plug and unplug cables and flipping the PineNote around and placing magnets.

This is especially helpful when changing back and forth between u-boot and rockusb, for instance when trying to develop u-boot.

==== Shorting test points ====

If the bootloader is broken/corrupted, you cannot get to Maskrom without opening up the device (it can be opened using spudger and a bit of patience).

Once inside, short TP1301 and TP1302 with a small tweezers, this is how it looks on board view (credit to Caleb):

[[File:PineNote_Maskrom_TP.png|500px]]

Then plug the device to the computer and if you see the device with VID=2207/PID=350a then it should be in Maskrom mode, you can verify by typing <code>rkdeveloptool list-devices</code>.

<nowiki>Jan 07 15:04:13 melttower kernel: usb 1-14: New USB device found, idVendor=2207, idProduct=350a, bcdDevice= 1.00
Jan 07 15:04:13 melttower kernel: usb 1-14: New USB device strings: Mfr=0, Product=0, SerialNumber=0

$ rkdeveloptool list-devices
DevNo=1 Vid=0x2207,Pid=0x350a,LocationID=10e Maskrom</nowiki>

If nothing shows up, you can try to hold down the power button for 5 seconds and then try again.

=== Running rkdeveloptool ===

First, you'll want to make sure the device you've connected is in maskrom mode:

<pre>
./rkdeveloptool list
</pre>

It should output something like <code>DevNo=1 Vid=0x2207,Pid=0x350a,LocationID=202 Maskrom</code>. If it doesn't, see [[PineNote Development#Entering Maskrom Mode]].

You can now download u-boot onto it:
<pre>
./rkdeveloptool boot ../u-boot-rockchip/rk356x_spl_loader_v1.08.111.bin
</pre>

This should output <code>Downloading bootloader succeeded.</code>.

We can now verify that this worked using e.g. the "read flash info" command:

<pre>
./rkdeveloptool read-flash-info
</pre>

'''TODO:''' finish this section

=== Creating a mainline boot image ===

You can create a filesystem image that replaces the Android boot or recovery partition by doing roughly the following:

# Erase boot and dtbo with rkdeveloptool or fastboot (back them up first!!!)
# Create an ext2 partition image and mount it (fallocate, mkfs.ext2)
# Build your mainline kernel
# Copy the kernel, dtb and an initramfs to the root of the mounted image (use any old postmarketOS initramfs)
# Create a file in the root of the mounted image called <code>extlinux.conf</code> as described below
# Unmount the image and then use rkdeveloptool to flash it to the "recovery" partition on the pinenote (it's about the right size until we get around to replacing the partition layout).

== Using fastboot ==

Follow the steps for "Creating a mainline boot.img", but instead of flashing it with rkdeveloptool, use fastboot. You can enter fastboot in either of two ways:

# Use "reboot bootloader" from adb or a UART console.
# Get a U-Boot prompt and run <code>fastboot usb 0</code>.

= Mainline development =

== Status ==

Some work happening here: https://gitlab.com/calebccff/linux, the idea is to import the parts of the eink/ebc drivers which are open source and use the downstream u-boot framebuffer driver as a reference to create a basic framebuffer driver.

Currently mainline struggles to boot due to weird issues while probing fixed regulators (?). It also fails to detect eMMC.

Further work is being done here: https://github.com/smaeul/linux/commits/rk356x-ebc-dev. This has a complete device tree, with working eMMC. Pen input also works out of the box. Wi-Fi and BT work with firmware copied from the factory Android image.

== How to boot mainline ==

UART is currently REQUIRED for this to work! We depend on u-boot falling back to console. Once we have a prebuilt u-boot which will use extlinux by default, UART won't be needed anymore.

You can compile a u-boot that uses extlinux by default by following the instructions [https://github.com/JoshuaMulliken/pinenote_uboot/blob/aa9ecbd3d3e716f163f5a900824630f24e9f04ba/README.md#changing-default-boot-order here].

=== Getting to a U-Boot prompt ===

You can get to a U-Boot prompt by:

# Holding Ctrl-C while the display panel initializes.
# Wiping the "boot" partition.

=== Using sysboot ===

<code>extlinux.conf</code> should have the following contents:

<pre>
timeout 10
default MAINLINE
menu title boot prev kernel

label MAINLINE
kernel /vmlinuz
fdt /rk3566-pinenote.dtb
initrd /initramfs
append earlycon console=tty0 console=ttyS2,1500000n8 fw_devlink=off PMOS_NO_OUTPUT_REDIRECT
</pre>

At the u-boot console, run the following command to boot your mainline kernel:

<pre>
sysboot ${devtype} ${devnum}:9 any ${scriptaddr} extlinux.conf
</pre>

=== Booting with individual commands ===

Booting with individual commands can be useful when you need to temporarily add some kernel command line arguments. Use these or similar commands at the U-Boot shell:

load mmc 0:b ${kernel_addr_r} boot/Image
load mmc 0:b ${fdt_addr_r} boot/rk3566-pinenote.dtb
setenv bootargs ignore_loglevel root=/dev/mmcblk0p11 rootwait init=/bin/bash
booti ${kernel_addr_r} - ${fdt_addr_r}

== Configuration ==

=== Firmware ===

Copy WiFi/BT firmware from Android:
mkdir -p /cache/lib/firmware/brcm
cp /vendor/etc/firmware/fw_bcm43455c0_ag_cy.bin /cache/lib/firmware/brcm/brcmfmac43455-sdio.bin
cp /vendor/etc/firmware/nvram_ap6255_cy.txt /cache/lib/firmware/brcm/brcmfmac43455-sdio.txt
cp /cache/lib/firmware/BCM4345C0.hcd /cache/lib/firmware/brcm/BCM4345C0.hcd

Copy waveform partition (via previously dumped file):
adb root
adb push waveform.img /cache/lib/firmware/waveform.bin

Or via dd within Linux:
dd if=/dev/mmcblk0p3 of=/lib/firmware/waveform.bin bs=1k count=2048

=== Touchscreen and Pen In X.org ===

By default the pen config is flipped 180° (which makes it unusable) and the touchscreen doesn't work. Placing the following config in <code>/etc/X11/xorg.conf.d/50-touchscreen.conf</code> will fix both problems:

<pre>
Section "InputClass"
Identifier "evdev touchscreen"
MatchProduct "tt21000"
MatchIsTouchscreen "on"
Driver "evdev"
EndSection
Section "InputClass"
Identifier "RotateTouch"
MatchProduct "w9013"
Option "TransformationMatrix" "-1 0 1 0 -1 1 0 0 1"
EndSection
</pre>

PineNote Development

2022-12-10T13:04:02Z

Talpa: /* The u-boot way */

This article seeks to provide general development information for the [[PineNote]]. If you are new and down to try a new installation process, the easiest way to get linux is likely to [https://wiki.pine64.org/wiki/PineNote_Development/Installing_Debian install Debian] -- NOTE THAT THIS INSTALLATION PROCESS IS VERY NEW. While many people have been using the kernel that will be installed safely at this point, the instructions for installing Debian via rootfs are very new. Take backups!

The more stable recommended approach is described below:

Start with [https://github.com/DorianRudolph/pinenotes Dorian's guide] which will guide you through getting Arch installed. For instructions on building the latest kernel, see [[PineNote Development/Building Kernel]]. For helpful configurations, see [[PineNote Development/Apps]]. For ways to pitch in, see [[PineNote Development/TODOs]]. To boot Linux by default instead of Android, see [[PineNote Development/Booting Linux]]. [https://www.youtube.com/watch?v=ZCLyJfbzbrU Here is a video] of a user running Manjaro and some apps on their PineNote on 9/10/2022.

= More Information =
== High-level developer new to embedded linux? ==
Here are some resources I have found helpful in learning to develop on embedded linux devices:
* Great youtube series introducing you to the kernel and lower-level components of Linux: https://www.youtube.com/watch?v=WiZ05pnHZqM
* https://embetronicx.com/
* https://bootlin.com/training/
* https://www.nand2tetris.org

== Notes Written by Some Developers ==

* https://github.com/m-weigand/mw_pinenote_misc (Not super legible "notes", but very helpful repo with patches, videos, etc)
** specifically see this section for helpful install/configure scripts: https://github.com/m-weigand/mw_pinenote_misc/tree/main/rockchip_ebc/patches#compiling.
* https://github.com/0cc4m/pinenote-misc
** patch for enabling gpu: https://github.com/0cc4m/pinenote-misc/blob/main/mesa-archlinux-arm/mesa/rockchip_ebc.patch
** prebuilt pkg's: https://github.com/0cc4m/pinenote-misc/releases
* https://pwarren.id.au/pinenote/build_notes.txt
* https://github.com/DorianRudolph/pinenotes
* https://github.com/tpwrules/nixos-pinenote

== Alternative to patching of mesa ==
Mesa needs to be patched to add the driver entry point. The alternative to this, is the renaming of the ebc driver to an existing mesa driver entry point. A good existing name can be "repaper". To change the driver name, edit in the kernel tree the following files: 
- replace "rockchip-ebc" with "repaper" in the two places in the file: drivers/gpu/drm/rockchip/rockchip_ebc.c 
- preventive, replace "repaper" with "repaper-disabled" in the two places in the file: drivers/gpu/drm/tiny/repaper.c 

== Building the most recent kernel ==
See [https://wiki.pine64.org/wiki/PineNote_Development/Building_Kernel here].

== Video of Factory Android OS ==

[https://www.youtube.com/watch?v=DWuTGgQHw98 PineNote Developer Edition w/Tech Demo Android OS (Video Only)]

Informal walkthrough of the factory Android installation on the PineNote Developer Edition, recorded by a community member (Apr 2022). This is useful to look back at the original OS after erasing it from your device, or to get some additional detail before your device arrives.

The video also includes a chapter at the end showing [https://www.youtube.com/watch?v=DWuTGgQHw98&t=802s how to enable Android Debug Bridge (`adb`) over USB]. Once enabled, keep the device powered and connect a USB cable directly to the PineNote (i.e. no UART breakout) to a computer running `adb`.

== Emulator for Developing/Testing Pinenote Apps ==
https://github.com/michaelshiel/picom-epaper

= Flashing Software =

Currently, the only ways to flash software are from the factory Android installation (UART shell, adb, or fastboot) or by using rkdeveloptool.

== Side-by-side setup ==

It is possible to set up a partition for mainline development without disturbing the factory Android installation. This allows updating a mainline kernel, DTB, and initramfs over Wi-Fi until WiFi or USB OTG is working in mainline Linux.

=== Without Repartitioning ===

The recommended partition for this is <tt>mmcblk0p11</tt> aka <tt>/cache</tt>. It is large and already formatted as <tt>ext4</tt>, so it is readable from U-Boot. Here are some general steps:

# From the UART or adb shell, set up your chroot in <tt>/cache</tt>. I used the Alpine Linux rootfs tarball.
# Copy in your kernel and DTB, using for example <tt>scp</tt> or <tt>wget</tt> inside the chroot.
# Finally, create and boot an <code>extlinux.conf</code> as described below.

=== With Repartitioning ===

It is possible to shrink the <tt>userdata</tt> partition, and create a new partition at the end for use with mainline Linux. This provides much more space than <tt>cache</tt>. However, because <tt>userdata</tt> is formatted with <tt>f2fs</tt>, and that filesystem cannot be shrunk, resizing the partition requires wiping <tt>userdata</tt>.

# Back up any necessary files from userdata
# Boot to a mainline kernel from <tt>mmcblk0p11</tt>, either using that partition as rootfs (see above), or using an initramfs with repartitioning tools
# Modify the partition table with your favorite tool, e.g. <tt>fdisk</tt>, <tt>gdisk</tt>, or <tt>parted</tt>
# Reboot into <tt>fastboot</tt> and wipe <tt>userdata</tt>.
# Reboot into Android, where you can now chroot in and install your favorite distribution to the new partition.

== Using rkdeveloptool ==

rkdeveloptool is a command line utility built on libusb.

=== Downloading and Building rkdeveloptool ===

PINE64 develops [https://gitlab.com/pine64-org/quartz-bsp/rkdeveloptool its own updated fork of rkdeveloptool on GitLab].

You will need to have libusb 1.0, its development headers and scdoc installed.

<pre>
git clone https://gitlab.com/pine64-org/quartz-bsp/rkdeveloptool.git
cd rkdeveloptool
mkdir build
cd build
cmake ..
</pre>

This sets up all the build files. You can then compile with <code>make</code> inside the build directory.

After you're done, you'll likely also need to install the udev rules, or else your user won't have permission to access the USB devices:

<pre>
sudo cp 99-rk-rockusb.rules /etc/udev/rules.d/
sudo udevadm control --reload
</pre>

Copying the udev rules is also performed automatically when you <code>make install</code>.

=== Building Downstream U-Boot ===

While in maskrom mode, we need to have a u-boot to download onto the device for any of the other commands to work. To build you'll also need to install device-tree-compiler.

You also need to install Python and pyelftools.

 Note that rkbin is a >5GB download! This will take some time to clone and process the deltas.

<pre>
git clone -b quartz64 https://gitlab.com/pgwipeout/u-boot-rockchip.git
git clone -b rkbin https://github.com/JeffyCN/rockchip_mirrors.git rkbin
cd u-boot-rockchip
# If using Arch Linux, export CROSS_COMPILE=aarch64-linux-gnu-
export CROSS_COMPILE=aarch64-none-linux-gnu-
make rk3566-quartz64_defconfig
./make.sh
</pre>

<blockquote>
In the version I cloned (current as of 2022-01-02), I had to make a change to one line to get a clean compilation:

<pre>
diff --git a/lib/avb/libavb/avb_slot_verify.c b/lib/avb/libavb/avb_slot_verify.c
index 123701fc3b..64a1ce6450 100644
--- a/lib/avb/libavb/avb_slot_verify.c
+++ b/lib/avb/libavb/avb_slot_verify.c
@@ -296,7 +296,7 @@ static AvbSlotVerifyResult load_and_verify_hash_partition(
bool image_preloaded = false;
uint8_t* digest;
size_t digest_len;
- const char* found;
+ const char* found = NULL;
uint64_t image_size;
size_t expected_digest_len = 0;
uint8_t expected_digest_buf[AVB_SHA512_DIGEST_SIZE];
</pre>

For systems where the global python executable points to python2, compilation fails with an error related to pyelftools not being installed (even if it is). To fix this:
<pre>
diff --git a/make.sh b/make.sh
index 2bba05b4e4..cfe5b0afd5 100755
--- a/make.sh
+++ b/make.sh
@@ -758,7 +758,7 @@ function pack_fit_image()
fi

if [ "${ARM64_TRUSTZONE}" == "y" ]; then
- if ! python -c "import elftools" ; then
+ if ! python3 -c "import elftools" ; then
echo "ERROR: No python 'pyelftools', please: pip install pyelftools"
exit 1
fi
</pre>
</blockquote>

=== Entering Maskrom/Rockusb Mode ===

There are three ways to get into Maskrom/Rockusb mode:

==== The easy way ====

# Flip the device around so that the display faces down
# Lay the pen on the right side, with its tip pointing towards the speaker grill, and its magnet pointing towards the upper right corner of the label on the back (or place the magnetic cap from the pen on the spot marked on the back).
# Turn the device on and wait for it to show up in <code>lsusb</code>. It should now be in Loader mode, according to <code>rkdeveloptool list-devices</code> (note that "Loader" here indicates U-Boot's Rockusb; separately, booting with an erased eMMC displays "Maskrom" [not "Loader"] from the RK3566).
# Unplug the device and plug it back in. It should now be in Rockusb mode.

This can be a bit fiddly to get right, and may need a few tries.

==== The u-boot way ====
# Interrupt the u-boot startup using ctrl-c (while attached using am UART dongle)
# While in u-boot use the command "rockusb 0 mmc 0" to start rockusb mode.

One benefit from this is, that if you have an UART dongle that allows to simultaneous having an UART and USB connection, there is no need to plug and unplug cables and flipping the PineNote around and placing magnets.

This is especially helpful when changing back and forth between u-boot and rockusb, for instance when trying to develop u-boot.

==== Shorting test points ====

If the bootloader is broken/corrupted, you cannot get to Maskrom without opening up the device (it can be opened using spudger and a bit of patience).

Once inside, short TP1301 and TP1302 with a small tweezers, this is how it looks on board view (credit to Caleb):

[[File:PineNote_Maskrom_TP.png|500px]]

Then plug the device to the computer and if you see the device with VID=2207/PID=350a then it should be in Maskrom mode, you can verify by typing <code>rkdeveloptool list-devices</code>.

<nowiki>Jan 07 15:04:13 melttower kernel: usb 1-14: New USB device found, idVendor=2207, idProduct=350a, bcdDevice= 1.00
Jan 07 15:04:13 melttower kernel: usb 1-14: New USB device strings: Mfr=0, Product=0, SerialNumber=0

$ rkdeveloptool list-devices
DevNo=1 Vid=0x2207,Pid=0x350a,LocationID=10e Maskrom</nowiki>

If nothing shows up, you can try to hold down the power button for 5 seconds and then try again.

=== Running rkdeveloptool ===

First, you'll want to make sure the device you've connected is in maskrom mode:

<pre>
./rkdeveloptool list
</pre>

It should output something like <code>DevNo=1 Vid=0x2207,Pid=0x350a,LocationID=202 Maskrom</code>. If it doesn't, see [[PineNote Development#Entering Maskrom Mode]].

You can now download u-boot onto it:
<pre>
./rkdeveloptool boot ../u-boot-rockchip/rk356x_spl_loader_v1.08.111.bin
</pre>

This should output <code>Downloading bootloader succeeded.</code>.

We can now verify that this worked using e.g. the "read flash info" command:

<pre>
./rkdeveloptool read-flash-info
</pre>

'''TODO:''' finish this section

=== Creating a mainline boot image ===

You can create a filesystem image that replaces the Android boot or recovery partition by doing roughly the following:

# Erase boot and dtbo with rkdeveloptool or fastboot (back them up first!!!)
# Create an ext2 partition image and mount it (fallocate, mkfs.ext2)
# Build your mainline kernel
# Copy the kernel, dtb and an initramfs to the root of the mounted image (use any old postmarketOS initramfs)
# Create a file in the root of the mounted image called <code>extlinux.conf</code> as described below
# Unmount the image and then use rkdeveloptool to flash it to the "recovery" partition on the pinenote (it's about the right size until we get around to replacing the partition layout).

== Using fastboot ==

Follow the steps for "Creating a mainline boot.img", but instead of flashing it with rkdeveloptool, use fastboot. You can enter fastboot in either of two ways:

# Use "reboot bootloader" from adb or a UART console.
# Get a U-Boot prompt and run <code>fastboot usb 0</code>.

= Mainline development =

== Status ==

Some work happening here: https://gitlab.com/calebccff/linux, the idea is to import the parts of the eink/ebc drivers which are open source and use the downstream u-boot framebuffer driver as a reference to create a basic framebuffer driver.

Currently mainline struggles to boot due to weird issues while probing fixed regulators (?). It also fails to detect eMMC.

Further work is being done here: https://github.com/smaeul/linux/commits/rk356x-ebc-dev. This has a complete device tree, with working eMMC. Pen input also works out of the box. Wi-Fi and BT work with firmware copied from the factory Android image.

== How to boot mainline ==

UART is currently REQUIRED for this to work! We depend on u-boot falling back to console. Once we have a prebuilt u-boot which will use extlinux by default, UART won't be needed anymore.

You can compile a u-boot that uses extlinux by default by following the instructions [https://github.com/JoshuaMulliken/pinenote_uboot/blob/aa9ecbd3d3e716f163f5a900824630f24e9f04ba/README.md#changing-default-boot-order here].

=== Getting to a U-Boot prompt ===

You can get to a U-Boot prompt by:

# Holding Ctrl-C while the display panel initializes.
# Wiping the "boot" partition.

=== Using sysboot ===

<code>extlinux.conf</code> should have the following contents:

<pre>
timeout 10
default MAINLINE
menu title boot prev kernel

label MAINLINE
kernel /vmlinuz
fdt /rk3566-pinenote.dtb
initrd /initramfs
append earlycon console=tty0 console=ttyS2,1500000n8 fw_devlink=off PMOS_NO_OUTPUT_REDIRECT
</pre>

At the u-boot console, run the following command to boot your mainline kernel:

<pre>
sysboot ${devtype} ${devnum}:9 any ${scriptaddr} extlinux.conf
</pre>

=== Booting with individual commands ===

Booting with individual commands can be useful when you need to temporarily add some kernel command line arguments. Use these or similar commands at the U-Boot shell:

load mmc 0:b ${kernel_addr_r} boot/Image
load mmc 0:b ${fdt_addr_r} boot/rk3566-pinenote.dtb
setenv bootargs ignore_loglevel root=/dev/mmcblk0p11 rootwait init=/bin/bash
booti ${kernel_addr_r} - ${fdt_addr_r}

== Configuration ==

=== Firmware ===

Copy WiFi/BT firmware from Android:
mkdir -p /cache/lib/firmware/brcm
cp /vendor/etc/firmware/fw_bcm43455c0_ag_cy.bin /cache/lib/firmware/brcm/brcmfmac43455-sdio.bin
cp /vendor/etc/firmware/nvram_ap6255_cy.txt /cache/lib/firmware/brcm/brcmfmac43455-sdio.txt
cp /cache/lib/firmware/BCM4345C0.hcd /cache/lib/firmware/brcm/BCM4345C0.hcd

Copy waveform partition (via previously dumped file):
adb root
adb push waveform.img /cache/lib/firmware/waveform.bin

Or via dd within Linux:
dd if=/dev/mmcblk0p3 of=/lib/firmware/waveform.bin bs=1k count=2048

=== Touchscreen and Pen In X.org ===

By default the pen config is flipped 180° (which makes it unusable) and the touchscreen doesn't work. Placing the following config in <code>/etc/X11/xorg.conf.d/50-touchscreen.conf</code> will fix both problems:

<pre>
Section "InputClass"
Identifier "evdev touchscreen"
MatchProduct "tt21000"
MatchIsTouchscreen "on"
Driver "evdev"
EndSection
Section "InputClass"
Identifier "RotateTouch"
MatchProduct "w9013"
Option "TransformationMatrix" "-1 0 1 0 -1 1 0 0 1"
EndSection
</pre>

PineNote Development

2022-12-10T13:03:09Z

Talpa: Added a third way to enter rockusb mode

This article seeks to provide general development information for the [[PineNote]]. If you are new and down to try a new installation process, the easiest way to get linux is likely to [https://wiki.pine64.org/wiki/PineNote_Development/Installing_Debian install Debian] -- NOTE THAT THIS INSTALLATION PROCESS IS VERY NEW. While many people have been using the kernel that will be installed safely at this point, the instructions for installing Debian via rootfs are very new. Take backups!

The more stable recommended approach is described below:

Start with [https://github.com/DorianRudolph/pinenotes Dorian's guide] which will guide you through getting Arch installed. For instructions on building the latest kernel, see [[PineNote Development/Building Kernel]]. For helpful configurations, see [[PineNote Development/Apps]]. For ways to pitch in, see [[PineNote Development/TODOs]]. To boot Linux by default instead of Android, see [[PineNote Development/Booting Linux]]. [https://www.youtube.com/watch?v=ZCLyJfbzbrU Here is a video] of a user running Manjaro and some apps on their PineNote on 9/10/2022.

= More Information =
== High-level developer new to embedded linux? ==
Here are some resources I have found helpful in learning to develop on embedded linux devices:
* Great youtube series introducing you to the kernel and lower-level components of Linux: https://www.youtube.com/watch?v=WiZ05pnHZqM
* https://embetronicx.com/
* https://bootlin.com/training/
* https://www.nand2tetris.org

== Notes Written by Some Developers ==

* https://github.com/m-weigand/mw_pinenote_misc (Not super legible "notes", but very helpful repo with patches, videos, etc)
** specifically see this section for helpful install/configure scripts: https://github.com/m-weigand/mw_pinenote_misc/tree/main/rockchip_ebc/patches#compiling.
* https://github.com/0cc4m/pinenote-misc
** patch for enabling gpu: https://github.com/0cc4m/pinenote-misc/blob/main/mesa-archlinux-arm/mesa/rockchip_ebc.patch
** prebuilt pkg's: https://github.com/0cc4m/pinenote-misc/releases
* https://pwarren.id.au/pinenote/build_notes.txt
* https://github.com/DorianRudolph/pinenotes
* https://github.com/tpwrules/nixos-pinenote

== Alternative to patching of mesa ==
Mesa needs to be patched to add the driver entry point. The alternative to this, is the renaming of the ebc driver to an existing mesa driver entry point. A good existing name can be "repaper". To change the driver name, edit in the kernel tree the following files: 
- replace "rockchip-ebc" with "repaper" in the two places in the file: drivers/gpu/drm/rockchip/rockchip_ebc.c 
- preventive, replace "repaper" with "repaper-disabled" in the two places in the file: drivers/gpu/drm/tiny/repaper.c 

== Building the most recent kernel ==
See [https://wiki.pine64.org/wiki/PineNote_Development/Building_Kernel here].

== Video of Factory Android OS ==

[https://www.youtube.com/watch?v=DWuTGgQHw98 PineNote Developer Edition w/Tech Demo Android OS (Video Only)]

Informal walkthrough of the factory Android installation on the PineNote Developer Edition, recorded by a community member (Apr 2022). This is useful to look back at the original OS after erasing it from your device, or to get some additional detail before your device arrives.

The video also includes a chapter at the end showing [https://www.youtube.com/watch?v=DWuTGgQHw98&t=802s how to enable Android Debug Bridge (`adb`) over USB]. Once enabled, keep the device powered and connect a USB cable directly to the PineNote (i.e. no UART breakout) to a computer running `adb`.

== Emulator for Developing/Testing Pinenote Apps ==
https://github.com/michaelshiel/picom-epaper

= Flashing Software =

Currently, the only ways to flash software are from the factory Android installation (UART shell, adb, or fastboot) or by using rkdeveloptool.

== Side-by-side setup ==

It is possible to set up a partition for mainline development without disturbing the factory Android installation. This allows updating a mainline kernel, DTB, and initramfs over Wi-Fi until WiFi or USB OTG is working in mainline Linux.

=== Without Repartitioning ===

The recommended partition for this is <tt>mmcblk0p11</tt> aka <tt>/cache</tt>. It is large and already formatted as <tt>ext4</tt>, so it is readable from U-Boot. Here are some general steps:

# From the UART or adb shell, set up your chroot in <tt>/cache</tt>. I used the Alpine Linux rootfs tarball.
# Copy in your kernel and DTB, using for example <tt>scp</tt> or <tt>wget</tt> inside the chroot.
# Finally, create and boot an <code>extlinux.conf</code> as described below.

=== With Repartitioning ===

It is possible to shrink the <tt>userdata</tt> partition, and create a new partition at the end for use with mainline Linux. This provides much more space than <tt>cache</tt>. However, because <tt>userdata</tt> is formatted with <tt>f2fs</tt>, and that filesystem cannot be shrunk, resizing the partition requires wiping <tt>userdata</tt>.

# Back up any necessary files from userdata
# Boot to a mainline kernel from <tt>mmcblk0p11</tt>, either using that partition as rootfs (see above), or using an initramfs with repartitioning tools
# Modify the partition table with your favorite tool, e.g. <tt>fdisk</tt>, <tt>gdisk</tt>, or <tt>parted</tt>
# Reboot into <tt>fastboot</tt> and wipe <tt>userdata</tt>.
# Reboot into Android, where you can now chroot in and install your favorite distribution to the new partition.

== Using rkdeveloptool ==

rkdeveloptool is a command line utility built on libusb.

=== Downloading and Building rkdeveloptool ===

PINE64 develops [https://gitlab.com/pine64-org/quartz-bsp/rkdeveloptool its own updated fork of rkdeveloptool on GitLab].

You will need to have libusb 1.0, its development headers and scdoc installed.

<pre>
git clone https://gitlab.com/pine64-org/quartz-bsp/rkdeveloptool.git
cd rkdeveloptool
mkdir build
cd build
cmake ..
</pre>

This sets up all the build files. You can then compile with <code>make</code> inside the build directory.

After you're done, you'll likely also need to install the udev rules, or else your user won't have permission to access the USB devices:

<pre>
sudo cp 99-rk-rockusb.rules /etc/udev/rules.d/
sudo udevadm control --reload
</pre>

Copying the udev rules is also performed automatically when you <code>make install</code>.

=== Building Downstream U-Boot ===

While in maskrom mode, we need to have a u-boot to download onto the device for any of the other commands to work. To build you'll also need to install device-tree-compiler.

You also need to install Python and pyelftools.

 Note that rkbin is a >5GB download! This will take some time to clone and process the deltas.

<pre>
git clone -b quartz64 https://gitlab.com/pgwipeout/u-boot-rockchip.git
git clone -b rkbin https://github.com/JeffyCN/rockchip_mirrors.git rkbin
cd u-boot-rockchip
# If using Arch Linux, export CROSS_COMPILE=aarch64-linux-gnu-
export CROSS_COMPILE=aarch64-none-linux-gnu-
make rk3566-quartz64_defconfig
./make.sh
</pre>

<blockquote>
In the version I cloned (current as of 2022-01-02), I had to make a change to one line to get a clean compilation:

<pre>
diff --git a/lib/avb/libavb/avb_slot_verify.c b/lib/avb/libavb/avb_slot_verify.c
index 123701fc3b..64a1ce6450 100644
--- a/lib/avb/libavb/avb_slot_verify.c
+++ b/lib/avb/libavb/avb_slot_verify.c
@@ -296,7 +296,7 @@ static AvbSlotVerifyResult load_and_verify_hash_partition(
bool image_preloaded = false;
uint8_t* digest;
size_t digest_len;
- const char* found;
+ const char* found = NULL;
uint64_t image_size;
size_t expected_digest_len = 0;
uint8_t expected_digest_buf[AVB_SHA512_DIGEST_SIZE];
</pre>

For systems where the global python executable points to python2, compilation fails with an error related to pyelftools not being installed (even if it is). To fix this:
<pre>
diff --git a/make.sh b/make.sh
index 2bba05b4e4..cfe5b0afd5 100755
--- a/make.sh
+++ b/make.sh
@@ -758,7 +758,7 @@ function pack_fit_image()
fi

if [ "${ARM64_TRUSTZONE}" == "y" ]; then
- if ! python -c "import elftools" ; then
+ if ! python3 -c "import elftools" ; then
echo "ERROR: No python 'pyelftools', please: pip install pyelftools"
exit 1
fi
</pre>
</blockquote>

=== Entering Maskrom/Rockusb Mode ===

There are three ways to get into Maskrom/Rockusb mode:

==== The easy way ====

# Flip the device around so that the display faces down
# Lay the pen on the right side, with its tip pointing towards the speaker grill, and its magnet pointing towards the upper right corner of the label on the back (or place the magnetic cap from the pen on the spot marked on the back).
# Turn the device on and wait for it to show up in <code>lsusb</code>. It should now be in Loader mode, according to <code>rkdeveloptool list-devices</code> (note that "Loader" here indicates U-Boot's Rockusb; separately, booting with an erased eMMC displays "Maskrom" [not "Loader"] from the RK3566).
# Unplug the device and plug it back in. It should now be in Rockusb mode.

This can be a bit fiddly to get right, and may need a few tries.

==== The u-boot way ====
# Interrupt the u-boot startup using ctrl-c (while attached using a UART dongle)
# While in u-boot use the command "rockusb 0 mmc 0" to start rockusb mode.

One benefit from this is, that if you have a UART dongle that allows to simultaneous having a UART and USB connection, there is no need to plug and unplug cables and flipping the pinenote around and placing magnets.

This is especially helpful when changing back and forth between u-boot and rockusb, for instance when trying to develop u-boot.

==== Shorting test points ====

If the bootloader is broken/corrupted, you cannot get to Maskrom without opening up the device (it can be opened using spudger and a bit of patience).

Once inside, short TP1301 and TP1302 with a small tweezers, this is how it looks on board view (credit to Caleb):

[[File:PineNote_Maskrom_TP.png|500px]]

Then plug the device to the computer and if you see the device with VID=2207/PID=350a then it should be in Maskrom mode, you can verify by typing <code>rkdeveloptool list-devices</code>.

<nowiki>Jan 07 15:04:13 melttower kernel: usb 1-14: New USB device found, idVendor=2207, idProduct=350a, bcdDevice= 1.00
Jan 07 15:04:13 melttower kernel: usb 1-14: New USB device strings: Mfr=0, Product=0, SerialNumber=0

$ rkdeveloptool list-devices
DevNo=1 Vid=0x2207,Pid=0x350a,LocationID=10e Maskrom</nowiki>

If nothing shows up, you can try to hold down the power button for 5 seconds and then try again.

=== Running rkdeveloptool ===

First, you'll want to make sure the device you've connected is in maskrom mode:

<pre>
./rkdeveloptool list
</pre>

It should output something like <code>DevNo=1 Vid=0x2207,Pid=0x350a,LocationID=202 Maskrom</code>. If it doesn't, see [[PineNote Development#Entering Maskrom Mode]].

You can now download u-boot onto it:
<pre>
./rkdeveloptool boot ../u-boot-rockchip/rk356x_spl_loader_v1.08.111.bin
</pre>

This should output <code>Downloading bootloader succeeded.</code>.

We can now verify that this worked using e.g. the "read flash info" command:

<pre>
./rkdeveloptool read-flash-info
</pre>

'''TODO:''' finish this section

=== Creating a mainline boot image ===

You can create a filesystem image that replaces the Android boot or recovery partition by doing roughly the following:

# Erase boot and dtbo with rkdeveloptool or fastboot (back them up first!!!)
# Create an ext2 partition image and mount it (fallocate, mkfs.ext2)
# Build your mainline kernel
# Copy the kernel, dtb and an initramfs to the root of the mounted image (use any old postmarketOS initramfs)
# Create a file in the root of the mounted image called <code>extlinux.conf</code> as described below
# Unmount the image and then use rkdeveloptool to flash it to the "recovery" partition on the pinenote (it's about the right size until we get around to replacing the partition layout).

== Using fastboot ==

Follow the steps for "Creating a mainline boot.img", but instead of flashing it with rkdeveloptool, use fastboot. You can enter fastboot in either of two ways:

# Use "reboot bootloader" from adb or a UART console.
# Get a U-Boot prompt and run <code>fastboot usb 0</code>.

= Mainline development =

== Status ==

Some work happening here: https://gitlab.com/calebccff/linux, the idea is to import the parts of the eink/ebc drivers which are open source and use the downstream u-boot framebuffer driver as a reference to create a basic framebuffer driver.

Currently mainline struggles to boot due to weird issues while probing fixed regulators (?). It also fails to detect eMMC.

Further work is being done here: https://github.com/smaeul/linux/commits/rk356x-ebc-dev. This has a complete device tree, with working eMMC. Pen input also works out of the box. Wi-Fi and BT work with firmware copied from the factory Android image.

== How to boot mainline ==

UART is currently REQUIRED for this to work! We depend on u-boot falling back to console. Once we have a prebuilt u-boot which will use extlinux by default, UART won't be needed anymore.

You can compile a u-boot that uses extlinux by default by following the instructions [https://github.com/JoshuaMulliken/pinenote_uboot/blob/aa9ecbd3d3e716f163f5a900824630f24e9f04ba/README.md#changing-default-boot-order here].

=== Getting to a U-Boot prompt ===

You can get to a U-Boot prompt by:

# Holding Ctrl-C while the display panel initializes.
# Wiping the "boot" partition.

=== Using sysboot ===

<code>extlinux.conf</code> should have the following contents:

<pre>
timeout 10
default MAINLINE
menu title boot prev kernel

label MAINLINE
kernel /vmlinuz
fdt /rk3566-pinenote.dtb
initrd /initramfs
append earlycon console=tty0 console=ttyS2,1500000n8 fw_devlink=off PMOS_NO_OUTPUT_REDIRECT
</pre>

At the u-boot console, run the following command to boot your mainline kernel:

<pre>
sysboot ${devtype} ${devnum}:9 any ${scriptaddr} extlinux.conf
</pre>

=== Booting with individual commands ===

Booting with individual commands can be useful when you need to temporarily add some kernel command line arguments. Use these or similar commands at the U-Boot shell:

load mmc 0:b ${kernel_addr_r} boot/Image
load mmc 0:b ${fdt_addr_r} boot/rk3566-pinenote.dtb
setenv bootargs ignore_loglevel root=/dev/mmcblk0p11 rootwait init=/bin/bash
booti ${kernel_addr_r} - ${fdt_addr_r}

== Configuration ==

=== Firmware ===

Copy WiFi/BT firmware from Android:
mkdir -p /cache/lib/firmware/brcm
cp /vendor/etc/firmware/fw_bcm43455c0_ag_cy.bin /cache/lib/firmware/brcm/brcmfmac43455-sdio.bin
cp /vendor/etc/firmware/nvram_ap6255_cy.txt /cache/lib/firmware/brcm/brcmfmac43455-sdio.txt
cp /cache/lib/firmware/BCM4345C0.hcd /cache/lib/firmware/brcm/BCM4345C0.hcd

Copy waveform partition (via previously dumped file):
adb root
adb push waveform.img /cache/lib/firmware/waveform.bin

Or via dd within Linux:
dd if=/dev/mmcblk0p3 of=/lib/firmware/waveform.bin bs=1k count=2048

=== Touchscreen and Pen In X.org ===

By default the pen config is flipped 180° (which makes it unusable) and the touchscreen doesn't work. Placing the following config in <code>/etc/X11/xorg.conf.d/50-touchscreen.conf</code> will fix both problems:

<pre>
Section "InputClass"
Identifier "evdev touchscreen"
MatchProduct "tt21000"
MatchIsTouchscreen "on"
Driver "evdev"
EndSection
Section "InputClass"
Identifier "RotateTouch"
MatchProduct "w9013"
Option "TransformationMatrix" "-1 0 1 0 -1 1 0 0 1"
EndSection
</pre>

Pinebook Pro Hardware Accessory Compatibility

2020-08-02T08:00:36Z

Talpa: Added information about Goobay 62105 (and a test result for the Moreslan 11in1)

= Pinebook Pro accessories - by type =

This page was started in the early days when not all accessories/peripherals were working.

== NVMe SSD drives ==
Note that only PCIe type M.2 drives will work. Any SATA or USB type M.2 card will NOT work.
{| class="wikitable sortable"
!Type || Make/Model || Size || Hardware IDs || Result || Notes || Power options Active only || Save power setting?
|-
| 2242 || Toshiba OCZ RC 100 || 240 GB || RC100-M22242-240G || good || || ||
|-
| 2242 || Lexar NM520 || 256 GB || LNM520-256RBNA || good ||For some data on power use and performance, see [https://forum.pine64.org/showthread.php?tid=9029 here.] || PS 0: 3.05W PS 1: 2.44W PS 2: 2.02W || No. See [https://forum.pine64.org/showthread.php?tid=8737&pid=56481#pid56481 workaround].
|-
| 2280 || XPS SX8200 || 512 GB || ASX8200PNP-512GT-C || good || Performed [https://forum.pine64.org/showthread.php?tid=8322 these] steps for physical installation. Currently rooting from drive. || ||
|-
| 2280 || Intel 660p M.2 || 512 GB || SSDPEKNW512G8X1 || good || PS 1 (2.70W) will work without issues, even under heavy load. Recommended over PS 2, as PS 2 will incur an additional 80% performance penalty. APSTE shows enabled but drive does not support it. || PS 0: 3.50W PS 1: 2.70W PS 2: 2.00W || No
|-
| 2280 || Intel 660p M.2 || 1 TB || SSDPEKNW010T8X1 || good || || PS 0: 4.00W PS 1: 3.00W PS 2: 2.20W APSTE Disabled by default || No
|-
| 2280 || Intel 660p M.2 || 2 TB || SSDPEKNW020T8 || good || [https://forum.pine64.org/showthread.php?tid=7524&pid=49300#pid49300 Performance tests results] || ||
|-
| 2280 || Intel 760p M.2 || 128 GB || SSDPEKKW128G8 || good || Firmware Revision 004C || PS 0: 9.00W PS 1: 4.60W PS 2: 3.80W PS 3: 0.045W PS 4: 0.004W APSTE: disabled by default with 4.4 kernel (mrfixit Debian), enabled by default with 5.6 kernel (Manjaro KDE) || Yes
|-
| 2280 || Intel 760p M.2 || 256 GB || SSDPEKKW256G8 || good || Firmware Revision 004C || PS 0: 9.00W PS 1: 4.60W PS 2: 3.80W PS 3: 0.045W PS 4: 0.004W Need to use lower power. ||
|-
| 2280 || integral 256GB SSD M.2 2280 NVME || 256 GB || INSSD256GM280NM1 || usable || || PS 0: 9.00W || No
|-
| 2280 || Samsung 970 EVO Plus || 250 GB || MZ-V7S250BW || fail || Tested on Manjaro-ARM as root drive. Limited to PS 2 and Volatile Write Cache off gives the most stable results, but it will still hang on a hdparm test. || ||
|-
| 2280 || Samsung 970 EVO Plus || 500 GB || MZ-V7S500 || fail || Too power hungry? || PS 0: 6.2W PS 1: 4.3W PS 2: 2.1W ||
|-
| 2280 || Samsung 970 EVO || 1 TB || MZ-V7E1T0BW || fail || Too power hungry? || ||
|-
| 2280 || Corsair MP300 || 120 GB || CSSD-F120GBMP300 || good || || PS 0: 3.00W PS 1: 2.00W PS 2: 2.00W PS 3: 0.1W PS 4: 0.005W APSTE Disabled by default ||
|-
| 2280 || Silicon Power P34A60 || 1TB || SP001TBP34A60M28 || Usable || Power eager, but doesn't seem to use all 9W all the time, only under heavy I/O || PS 0: 9W || N/A
|-
| 2280 || Silicon Power P34A60 || 256 GB || SPCC M.2 PCIe SSD || detected || ASIN B07ZH6QR8Q "Silicon Power PCIe M.2 NVMe SSD 256GB Gen3x4" / PCIe A60 || PS 0: 6.77W PS 1: 5.71W PS 2: 5.19W APSTE Enabled by default || No
|-
| 2280 || Silicon Power P34A60 || 256 GB || ??? || fail || Isn't detected || ||
|-
| 2280 || Sabrent Rocket || 256 GB || SB-ROCKET-256 || good || || || No
|-
| 2242 || Sabrent Rocket Nano || 512 GB || SB-1342-512 || good* || No touchpad issues, didn't trim NVME adapter board. (*Might be too power hungry. More testing needed.) || ||
|-
| 2280 || MyDigitalSSD SBXe || 960 GB || || good || || APST enabled Power states N/A || N/A
|-
| 2280 || HP SSD EX900 || 250GB || || good || No low-power modes available || ||
|-
| 2280 || WD BLUE SN550 || 1TB || WDC WDS100T2B0C-00PXH0 || WARNING good || WARNING mine was SATA and does NOT work! Booted successfully from NVMe (Bionic MATE) || PS 0: 3.50W PS 1: 2.70W PS 2: 1.90W APSTE Disabled by default || N/A
|-
| 2280 || WD Blue SN500 || 500GB || WDS500G1B0C || fail || Works OK on power state 2 (2.5W), but hangs the system whenever there is intense IO (peak draw) on the drive || ||
|-
| 2242 || WD PC SN520 || 256GB || - || fail || Power LED Flashes. Nothing else happens. || ||
|-
|2280 || WD BLACK SN750 || 250GB || WDS250G3X0C-00SJG0 || good || No touchpad issues, didn't trim NVME adapter board. || APSTE disabled by default PS 0: 5.00W PS 1: 3.50W PS 2: 3.00W||
|-
| 2242 || KingSpec NE-512 || 512 GB || NE512 || good || || APST enabled Power states N/A || N/A
|-
| 2230 || Kioxia BG4 256GBTB|| 256 GB || KBG40ZNS256G || good || || APST enabled by default Power states PS 0: 3.60W PS 1: 2.60W PS 2: 2.20W PS 3: 0.005W PS 4: 0.005W ||
|-
| 2280 || Patriot P300 || 256 GB || P300P256GM28US || good || Booted successfully with / on NVMe and /boot on eMMC (Armbian Buster) || APSTE disabled by default PS 0: 4.50W PS 1: 2.70W PS 2: 2.16W PS 3: 0.07W PS 4: 0.002W||
|-
| 2280 || Team Group MP33 || 128 GB || TM8FP6128G0C101 || good || || ||
|-
| 2280 || Team Group MP34 || 512 GB || TM8FP6512G0C101 || fail ||APST enabled by default and scripts do not change the power mode. Higher power consumption modes cause the PBP to crash || PS 0 5.55W PS 1 4.49W PS 2 3.97W PS 3 0.0490W PS 4 0.0018W ||No
|}

== USB hardware ==
{| class="wikitable sortable"
!Type || Make/Model || Hardware IDs || Result || Notes
|-
|USB-2 SDHC reader || Sandisk MobileMate+ || 0781:b2b3 || good ||
|-
|USB-3 SDHC/CF reader || Transcend TS-RDF8K || 8564:4000 || good ||
|-
|USB-C Hub || Totu 8-in-1 || 058f:8468, 2109:0817 USB3, 1a40:0801, 2109:2817 USB2, bda:8153 RTL8153 Gigabit Ethernet || Network, USB, Card Reader, Power Good, HDMI Not Working || Amazon Smile [https://smile.amazon.com/gp/product/B07FX2LW35/ref=ppx_yo_dt_b_search_asin_title?ie=UTF8&psc=1]
|-
|USB-C Hub || Delock 87721 || || Network Works, USB Works, Card Reader not tested, Power Good, HDMI Works but does not show as an extra output in X. It just mirrors the default display || Delock 87721 [https://www.delock.de/produkte/G_87721/merkmale.html?setLanguage=en]
|-
|USB-3 combo hub (network, card slots, usb ports) || generic || 05e3:0610 hub, 0bda:8153 gigE, 05e3:0743 card reader || Network good, usb ports good, card reader good ||
|-
|USB-C combo hub (network, card slots, usb ports) || generic || 05e3:0612 hub, 0bda:8153 realtek gigE || Network good, usb ports fail, card reader fail ||
|-
|5-1 USB-C hub || [https://www.aliexpress.com/item/32954358411.html from aliexpress] || 05e3:0626 hub || HDMI, Network, USB-3, USB-C PD [http://www.sympato.ch/~dryak/files/usbc-dock.jpg good] || Might need changing orientation or USB-C cable
|-
|Yubikey original || Yubico || 1050:0010 || good ||
|-
|4 Port USB 3 NIC || Delock 62966 || || good || 4 individually controllable Gigabit Ethernet Ports. Consider using it with own power supply
|-
|USB-2 Fast Ethernet adapter || Realtek RTL8152 || 0bda:8152 || good ||
|-
|USB-2 Ethernet adapter || ASIX AX77882 || 0b95:7720 || good ||
|-
|USB Wifi Dongle || TP-Link TL-WN725N || 0bda:8179 || good || RTL8188EUS, Driver=rtl8188eu from MrFixit stock Debian, works better than internal Broadcom, but signal still not great, https://www.amazon.com/gp/product/B008IFXQFU/ref=ppx_yo_dt_b_asin_title_o01_s00?ie=UTF8&psc=1
|-
|USB Wifi Dongle || Shenzhen Dudes Tech #8541553244 || 0bda:c811 || mixed || plug/play on stock Armbian Buster with driver rtl8821cu; could not get operating driver built on MrFixit Debian or Manjaro KDE Plasma. Works 2x+ better than internal Broadcom on Armbian. https://www.amazon.com/gp/product/B07F595V22/ref=ppx_yo_dt_b_asin_title_o02_s00?ie=UTF8&psc=1
|-
|USB 3 to Gigabit Ethernet Adapter || Pluggable USB 3.0 to Ethernet Gigabit (ASIX AX88179 chipset) || 0b95:1790 || good ||
|-
|USB-C combo hub || [https://www.amazon.com/gp/product/B07XKRGQQ2/ref=ppx_yo_dt_b_asin_title_o00_s00?ie=UTF8&psc=1 from Amazon] || 0c76:161f 0c45:6321 2109:0813 1a40:0101 || good || Everything works: AltMode DP, Ethernet, SD card, USB-A and C, and charging using the stock Debian, and Ubuntu.
|-
|USB Drawing tablet || XP Pen G430s || 28bd:0913 || good || Hardware works, with qemu usermode and some hacks it should be possible to use the official configuration software (runs but does not work on my setup for unrelated reasons) but it may also be able to be configured using more standard methods
|-
|USB-C dock || i-Tec USB-C Metal Nano Dock 4K HDMI w/ LAN || 0bda:0411 hub, 0bda:8153 ethernet || mixed || plug & play with Manjaro, HDMI tested w/ fullHD only, works but only in one polarity. Sound output works, USB hub works. HDMI output may not be recognized by Plasma if dock is connected with HDMI port disconnected. NIC recognized by kernel, but untested if link actually works. USB power delivery works only in one polarity. Unfortunately HDMI works with opposite polarity than USB PD.
|-
|USB-C dock || Planet Computers Gemini USB-C hub || 0bda:0411 hub, 0bda:8153 ethernet || good || USB works, NIC recognized by kernel, but untested if link actually works. Interestingly, dmesg shows unconnected alternate mode DP, but no connector is present. It seems as if PlanetCom actually made custom version of above i-Tec device.
|}

== USB C alternate mode DP ==
Note that only USB C alternate mode Display Port will pass video. Any HDMI, DVI or VGA port must be converted internally by the device from Display Port - or the device won't work for video.
{| class="wikitable sortable"
!Type || Make/Model || Hardware IDs || Result || Notes
|-
|USB-C to HDMI adapter 201018 || Cable Matters || || good || Tested up to 1080p30, audio works
|-
|USB-C to HDMI adapter || Choetech HUB-H06 || || good || Advertises support for 4K@60Hz, tested up to 1080p@60Hz, worked in both Debian and Manjaro 2020-04-04
|-
|USB-C to HDMI adapter || generic || || good || Tested up to 4k60
|-
|USB-C to DP Adapter || OrxnQ || 04b4:5210 || good || Advertises support for 4K@60Hz, tested up to 1080p. Only FullHD resolutions available on Debian.
|-
|USB-C HDMI adapter (DP-alt mode) || QGeeM || || good || Manjaro 2020-01-25
|-
|USB-C combo hub (HDMI, network, card slots, USB ports) || generic || || fail ||
|-
|USB-C combo hub (HDMI, VGA, Ethernet, card slots, USB 2 & 3 || Powlaken || 05e3:0610 0bda:8153 || USB, Power, Ethernet and SD good, HDMI and VGA fail ||
|-
|USB-C Dock (HDMI, VGA, Ethernet, microSD/SD card slots, 2 USB 3 Ports, 1 USB-C Port, USB-Power Passthru || Digitus DA-70865 || || USB, Ethernet and MicroSD/SD good, video crashes System (fail). || Tested on Manjaro w/ Kernel 5.5. You have to turn the USB-C connector upside down for it to work. Video seems to be a driver issue.
|-
|USB-C Dock (HDMI, VGA, Ethernet, microSD/SD card slots, 2 USB 3 Ports, 1 USB-C Port, USB-Power pass-through) || generic || || Ethernet and MicroSD/SD good, USB fail, video up to 1080p. || https://forum.pine64.org/showthread.php?tid=8728
|-
|USB-C Dock (DP, HDMI, 1Gbps Ethernet, SD card slot, 2 USB 3 Ports, USB-C power in port || goFanco || || DP, Ethernet & USB good, (HDMI & SD card untested). Video tested good to 1080p || Tested on default Debian
|-
|USB-C Dock (HDMI, USB 3.0 x 2, USB-C PD Pass Thru Power Port Up to 100W, SD/TF Card Reader || Hiearcool 7-in-1 || || HDMI, USB, Power Port good, SD/TF Reader fail || Default Debian
|-
|USB-C 3.0 Multi-Port Hub (HDMI, USB 3.0 x 1, USB-C charge only) || Linden LITCAD17 || || HDMI and USB good, Power Port fail || Default Debian & ayufan Ubuntu
|-
|USB-C to DP adapter || Nekteck || 04b4:5210 || good || Shows up as "Cypress Semiconductor Corp. Billboard Device" in lsusb and dmesg output. Works in latest Manjaro (as of January 26, 2020) with no issues. Only FullHD resolutions available on Debian.
|-
|USB-C to HDMI adapter || MHL TH002 || || good || Tested at 1080p@60
|-
|USB-C combo hub (USB-C power, HDMI, 2xUSB, 1xUSB-C(no power)) || Baseus || || good ||
|-
|USB-C Travel Dock with DP ALT-MODE || Targus DOCK411-A || 0835:2a01 (BILLBOARD DEVICE) 0bda:8153 (RTL8153 GbE Adapter) || GbE: works, HDMI: works, USB3.0 port: works, VGA: unknown || HDMI@1080p@60Hz: works OK, HDMI@4K@30Hz: works but buggy. GbE is only picked up when the USB C is plugged in with one certain side facing upwards. It is not detected the other way around. (Sounds weird, but reproduced it multiple times.)
|-
|USB-C to DP adapter || MediaGearPro AC0011 || 2109:0100 (USB 2.0 BILLBOARD) || DP: works || Only 1080p@60Hz is available, 4K resolutions not possible in contrast to what the manufacturer claims.
|-
|USB-C to DP cable || Generic on ebay || || good but with issues || Had some wonky framerates when tested on a 144hz monitor, 60hz mode was actually sent as ~48hz, 120hz mode was actually sent at ~112hz and 144hz mode was actually sent at ~120hz
|-
|UGREEN Hub USB C 9 in 1 HDMI and VGA || UGREEN || || good || VGA and HDMI works but not at the same time. HDMI audio not tested. Switching between HDMI and VGA need to replug the hub.
|-
|USB-C Dock 6-in-1 HDMI || Ugreen 50771 || || HDMI: works, Ethernet: works, 3x USB: works, USB-PD: works || Tested on Manjaro 2020/03/18 Works USB-C PD Chargers provided they can do 5V3A, works with 5V3A USB-C Raspberry Pi 4 power supply (Doesn't work with 5V2A USB-C). No HDMI Audio.
|-
|USB-C to DP cable || [https://www.amazon.es/gp/product/B01N5RFAI4/ref=ppx_yo_dt_b_asin_title_o00_s00?ie=UTF8&psc=1 CHOETECH V-XCP-0012BK] || || good
|-
| [https://www.apple.com/ca/shop/product/MQ4H2AM/A/thunderbolt-3-usb%E2%80%91c-cable-08-m Thunderbolt 3 (USB‑C) Cable (0.8 m)] || Apple || || Display Port Alternate Mode: Fails, USB-PD: works || Tested on Manjaro 2020/05/29 - Charges but no video
|-
|USB-C to HDMI cable || Planet Computers USB-C to HDMI cable || || fail || does not work regardless of orientation in USB slot
|-
|USB-C combo hub || Moreslan 11in1 (https://www.amazon.fr/gp/product/B08397B66G) || || good || GbE: OK, HDMI: OK, 4 usb ports: OK, Power via USB-C: OK, microSD: OK, TFT: OK, Jack: OK, VGA: Not tested
|-
|USB-C Multiport Adapter || [https://www.wentronic.com/en/usb-ctm-multiport-adapter-hdmi-ethernet-pd-white-62105 Goobay 62105] || || Fail || GbE: OK, UBS port: OK, Power via USB-C: OK, HDMI: Does generate an image, but it jumps X pixels right from time to time (4K@30 and FHD)
|}

== Other hardware ==
{| class="wikitable sortable"
!Type || Make/Model || Hardware IDs || Result || Notes
|-
|Bluetooth Mouse || HP Z5000 || E5C13AA || good ||
|-
|Bluetooth Mouse || Logitech MX Vertical || || good || Battery level is not detected over bluetooth, detected when using the logitech receiver
|-
|Bluetooth Mouse || Logitech Triathlon M720 || || good ||
|-
|Bluetooth Mouse || Logitech Ultra-Thin Touch Mouse || || good || Detects battery level as "keyboard"
|-
|Bluetooth Mouse || Logitech MX Anywhere 2 || || good ||
|-
|Bluetooth Mouse || Logitech M535 || 910-004432 || good ||
|-
|Bluetooth Mouse || Microsoft Bluetooth Mouse || RJN-00002 || good ||
|-
|Bluetooth Mouse || Fenifox low profile || MX106-Black || good ||
|-
|Bluetooth Mouse || Technet || MGS479 || good ||
|-
|Bluetooth Keyboard || Logitech MX Keys || || good || Battery level is not detected over bluetooth, detected when using the logitech receiver
|-
|Bluetooth Speaker || Ivation Acoustix || || good || Use audio sink profile
|-
|Headphone || Sony WH-1000XM2 || || good* || Needs pulseaudio-module-bluetooth. *Recording untested.
|-
|Bluetooth Headphone || COWIN SE7 Noise Cancelling Headphones || || good || Pairs and plays audio with stock Debian OS. More detail [https://forum.pine64.org/showthread.php?tid=8192&pid=60682#pid60682 here].
|-
|[https://www.aliexpress.com/item/32831647303.html USB charging cable] || - || - || good || Got the cable a while back so may not be identical to current product
|-
|USB Audio & Bluetooth Headset || Sony SBH90C || || good || Works well connected via USB Type-C and Bluetooth.
|-
|SD Card || Samsung Evo Select 512GB || MB-ME512GA/AM || good ||
|-
|SD Card || Samsung Evo Plus 64GB || || good || Hdparm tested 44MBps read speeds
|-
|SD Card || Sandisk Ultra 400GB || || good || Works fine as a storage extension. Mounted for pictures, etc.
|-
|Printer || HP DeskJet Ink Advantage 3775 || || good* || Using hplip-gui: via USB and WiFi. *Only print function tested.
|-
|Bluetooth Headset || BlueAnt Ribbon || 7252A-RB || good || a2dp mode works, headset mode seems to work, out of box with manjaro
|-
|}