PINE64 - User contributions [en]

PineNote Development/Flashing

2023-10-24T15:21:38Z

Ahelwer: Expanded page overview

{{Under construction}}

{{Info|These instructions are directed towards experienced developers only!}}

This page contains information on flashing software to the [[PineNote]].
The general process is as follows:
# Take a backup of all important data on the PineNote
# Modify the partition layout to make space for your desired Linux distribution
# Instantiate a root filesystem (rootfs) in the new partition space
# Install your Linux distribution to the boot partition
# Modify the boot process to boot the Linux distribution by default

There are multiple possible methods of executing these steps, and this page attempts to document all of them.
You can use:
# <code>rkdeveloptool</code>, a command line utility for modifying [https://en.wikipedia.org/wiki/Rockchip Rockchip] devices over USB
# The [[PineNote_Development/UART|UART]] shell
# [https://en.wikipedia.org/wiki/Android_Debug_Bridge Android Debug Bridge]
# [https://en.wikipedia.org/wiki/Fastboot Fastboot]

== Getting <code>rkdeveloptool</code> ==

Most flashing operations on the PineNote are done through <code>rkdeveloptool</code>, a command line utility built on libusb.
PINE64 maintains its own fork [https://gitlab.com/pine64-org/quartz-bsp/rkdeveloptool here] that you will need to get.
The repo's README contains a list of dependencies (libusb 1.0) and instructions for building the tool.

Installing (not just building) <code>rkdeveloptool</code> will configure PAM to elevate privileges where necessary on your system; you can configure this manually as follows:
<pre>
sudo cp 99-rk-rockusb.rules /etc/udev/rules.d/
sudo udevadm control --reload
</pre>

== Entering Maskrom/Rockusb mode ==

Interfacing with the PineNote over USB using <code>rkdeveloptool</code> requires first booting the PineNote into [http://opensource.rock-chips.com/wiki_Rockusb an alternative operating mode] called Maskrom or Rockusb mode.

=== Possible methods ===

There are three possible methods of entering Maskrom/Rockusb mode:

==== Hardware magnet switch ====

# Connect the PineNote to your computer via USB and boot the PineNote into Android
# Locate & identify the small circular marking on the back of the PineNote, in the top right quadrant; have the PineNote pen close at hand, or any other small magnet
# Hold the PineNote power button to bring up the reboot/shutdown menu; select reboot, then place the PineNote face down with the "eraser" end of the pen (or your magnet) resting on the small circular marking

<gallery>
Download mode.jpeg|Pen method
PineNoteMagnetOnBack.jpg|Magnet method
</gallery>

==== U-Boot terminal ====
This method requires a [[PineNote_Development/UART#USB_passthrough|UART dongle with passthrough]] allowing simultaneous UART & USB connections.
It is nice because you can easily switch back & forth between U-Boot and Rockusb without having to physically manipulate the PineNote or its connectors; this is especially helpful when trying to develop U-Boot.

# Connect to the PineNote via UART and USB simultaneously
# Interrupt the U-Boot startup using <code>ctrl+c</code> sent over UART
# In the U-Boot terminal over UART, run <code>rockusb 0 mmc 0</code>

The UART terminal should print <code>RKUSB</code> then a spinner will appear.
You can exit back to the U-Boot terminal by sending <code>ctrl+c</code> again.

==== 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]]

=== Success ===

No matter what approach you take, you can tell whether you succeeded by running the <code>lsusb</code> command on your computer:
* If you find the entry <code>2207:0018 Fuzhou Rockchip Electronics Company rk3566_eink</code> in the list, the process did not succeed; reboot and retry
* The entry <code>2207:350a Fuzhou Rockchip Electronics Company</code> will occur if you detach then reattach the USB-C cable while the PineNote is in Maskrom/Rockusb mode; <code>rkdeveloptool</code> won't work and you will have to do a hard reboot (hold down power button for 30 seconds to shutdown)
* If you find the entry <code>2207:350a Fuzhou Rockchip Electronics Company USB download gadget</code> then the process succeeded

You can also look at the output of the <code>rkdeveloptool list</code> command:
* If this prints out <code>No devices in rockusb mode found</code> the process did not succeed; reboot and retry
* If this prints out <code>DevNo=1 Vid=0x2207,Pid=0x350a,LocationID=305 Maskrom</code> then you probably detached/reattached the USB-C cable while in Maskrom/Rockusb mode and <code>rkdeveloptool</code> won't work; perform a hard reboot to fix
* If this prints out <code>DevNo=1 Vid=0x2207,Pid=0x350a,LocationID=303 Loader</code> then the process succeeded

=== Exiting ===

You can boot the PineNote back into its normal mode of operation by powercycling the PineNote with its hardware power switch, or running the <code>rkdeveloptool reboot</code> command.
If you used the magnetic switch method be sure to remove the pen/magnet before rebooting.

== Backup ==

A backup of the content of the internal eMMC before anything gets messed up is '''mandatory'''.

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

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) contain data you may also 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.

This process was developed by Dorian Rudolph, originally described [https://github.com/DorianRudolph/pinenotes here].

=== List partitions ===

First, run <code>rkdeveloptool list-partitions</code> to print out your PineNote's partitions to get an idea of what you're dealing with.
The stock PineNote has a fairly standard [https://source.android.com/docs/core/architecture/partitions Android partition setup]:

{| class="wikitable"
|-
! Number !! Name !! Size !! Purpose
|-
| 0 || uboot || 4 MB || The [https://en.wikipedia.org/wiki/Das_U-Boot U-Boot] embedded systems bootloader
|-
| 1 || trust || 4 MB || Secrets that can be encrypted with a key stored in the [https://en.wikipedia.org/wiki/Trusted_Platform_Module TPM]
|-
| 2 || waveform || 2 MB || Important files controlling the e-ink screen's state changes
|-
| 3 || misc || 4 MB || Data used by the recovery partition
|-
| 4 || dtbo || 4 MB || [https://en.wikipedia.org/wiki/Devicetree Device Tree Blob for Overlay], files describing the PineNote's hardware configuration
|-
| 5 || vbmeta || 1 MB || Data required for [https://android.googlesource.com/platform/external/avb/+/master/README.md verified boot]
|-
| 6 || boot || 42 MB || The kernel image & ramdisk to boot
|-
| 7 || security || 4 MB ||
|-
| 8 || recovery || 134 MB || The recovery image, booted during Android updates
|-
| 9 || backup || 400 MB ||
|-
| 10 || cache || 1 GB || Stores temporary data; can be used to install a minimal Linux distribution!
|-
| 11 || metadata || 17 MB || Used for disk encryption
|-
| 12 || super || 3.25 GB || Android itself is installed here
|-
| 13 || logo || 17 MB || Splash image displayed during boot
|-
| 14 || device || 67 MB ||
|-
| 15 || userdata || 119 GB || The big one; user-installed Android apps and files live here
|}

=== Patch U-Boot ===

Before we can back up our partitions, we have a problem to solve.
The version of U-Boot installed on the stock PineNote contains a bug where it can't dump partitions beyond 32 MB (above that limit all bytes in the dump are just <code>0xCC</code>), meaning the PineNote must be flashed with a fixed version of U-Boot before it is possible to take a backup of the larger partitions.
It is possible to extract and modify the U-Boot image from your PineNote if you're interested in some light reverse-engineering (following Dorian's notes), or you can simply download a patched U-Boot image directly [https://github.com/DorianRudolph/pinenotes/blob/main/static/uboot_patched.img here].

Once you've acquired a patched U-Boot image, run:
# <code>rkdeveloptool read-partition uboot uboot_backup.img</code>
# <code>rkdeveloptool write-partition uboot uboot_patched.img</code>
# <code>rkdeveloptool reboot</code>

=== Taking the backup ===

With U-Boot patched, you can back up every partition except for super and userdata; run:

<code>rkdeveloptool read-partition partition_name partition_name_backup.img</code>

Unfortunately the super and userdata partitions run into a second limitation preventing dumping partitions larger than 2 GB, this time originating in <code>rkdeveloptool</code> itself.
This means if you have a large number of documents in the Android userdata partition they might not all make it into the backup.
If you don't have many documents (or don't care about losing them) this should not be a problem.
If you do have a lot of documents, workarounds include:
* A possible patch written by Thomas exists [https://github.com/tpwrules/nixos-pinenote/blob/96d2c9158edb9da59afcb952cc864fada18382f9/nix/rkdeveloptool/0001-fix-large-dumps.patch here] but has not yet been upstreamed; consider investigating how to get the patch tested & upstreamed, or just apply it to your own local copy of <code>rkdeveloptool</code>
* Use [https://github.com/talpadk/pinenote-backup this] Python script written by Visti Andresen (talpadk) to automatically backup your entire partition by splitting reads into 2 GB chunks

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].

=== 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.

== 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 ==

=== 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 current version (current as of 2022-01-02), there might have to be made 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>

You can now download u-boot onto the PineNote:

./rkdeveloptool boot ../u-boot-rockchip/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

{{Note|'''TODO:''' Section needs to be finished}}

=== 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 [[PineNote Development/Flashing#Creating a mainline boot image|Creating a mainline boot image]], 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 or
* get a U-Boot prompt and run <code>fastboot usb 0</code>.

[[Category:PineNote]]

PineNote Development/Flashing

2023-10-23T17:42:05Z

Ahelwer: /* Taking the backup */ can backup all partitions except for super and userdata

{{Under construction}}

{{Info|These instructions are directed towards experienced developers only!}}

This page contains information on flashing software to the [[PineNote]].

Currently, software can be flashed using rkdeveloptool or from the factory Android installation (UART shell, adb, or fastboot).

== Getting <code>rkdeveloptool</code> ==

Most flashing operations on the PineNote are done through <code>rkdeveloptool</code>, a command line utility built on libusb.
PINE64 maintains its own fork [https://gitlab.com/pine64-org/quartz-bsp/rkdeveloptool here] that you will need to get.
The repo's README contains a list of dependencies (libusb 1.0) and instructions for building the tool.

Installing (not just building) <code>rkdeveloptool</code> will configure PAM to elevate privileges where necessary on your system; you can configure this manually as follows:
<pre>
sudo cp 99-rk-rockusb.rules /etc/udev/rules.d/
sudo udevadm control --reload
</pre>

== Entering Maskrom/Rockusb mode ==

Interfacing with the PineNote over USB using <code>rkdeveloptool</code> requires first booting the PineNote into [http://opensource.rock-chips.com/wiki_Rockusb an alternative operating mode] called Maskrom or Rockusb mode.

=== Possible methods ===

There are three possible methods of entering Maskrom/Rockusb mode:

==== Hardware magnet switch ====

# Connect the PineNote to your computer via USB and boot the PineNote into Android
# Locate & identify the small circular marking on the back of the PineNote, in the top right quadrant; have the PineNote pen close at hand, or any other small magnet
# Hold the PineNote power button to bring up the reboot/shutdown menu; select reboot, then place the PineNote face down with the "eraser" end of the pen (or your magnet) resting on the small circular marking

<gallery>
Download mode.jpeg|Pen method
PineNoteMagnetOnBack.jpg|Magnet method
</gallery>

==== U-Boot terminal ====
This method requires a [[PineNote_Development/UART#USB_passthrough|UART dongle with passthrough]] allowing simultaneous UART & USB connections.
It is nice because you can easily switch back & forth between U-Boot and Rockusb without having to physically manipulate the PineNote or its connectors; this is especially helpful when trying to develop U-Boot.

# Connect to the PineNote via UART and USB simultaneously
# Interrupt the U-Boot startup using <code>ctrl+c</code> sent over UART
# In the U-Boot terminal over UART, run <code>rockusb 0 mmc 0</code>

The UART terminal should print <code>RKUSB</code> then a spinner will appear.
You can exit back to the U-Boot terminal by sending <code>ctrl+c</code> again.

==== 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]]

=== Success ===

No matter what approach you take, you can tell whether you succeeded by running the <code>lsusb</code> command on your computer:
* If you find the entry <code>2207:0018 Fuzhou Rockchip Electronics Company rk3566_eink</code> in the list, the process did not succeed; reboot and retry
* The entry <code>2207:350a Fuzhou Rockchip Electronics Company</code> will occur if you detach then reattach the USB-C cable while the PineNote is in Maskrom/Rockusb mode; <code>rkdeveloptool</code> won't work and you will have to do a hard reboot (hold down power button for 30 seconds to shutdown)
* If you find the entry <code>2207:350a Fuzhou Rockchip Electronics Company USB download gadget</code> then the process succeeded

You can also look at the output of the <code>rkdeveloptool list</code> command:
* If this prints out <code>No devices in rockusb mode found</code> the process did not succeed; reboot and retry
* If this prints out <code>DevNo=1 Vid=0x2207,Pid=0x350a,LocationID=305 Maskrom</code> then you probably detached/reattached the USB-C cable while in Maskrom/Rockusb mode and <code>rkdeveloptool</code> won't work; perform a hard reboot to fix
* If this prints out <code>DevNo=1 Vid=0x2207,Pid=0x350a,LocationID=303 Loader</code> then the process succeeded

=== Exiting ===

You can boot the PineNote back into its normal mode of operation by powercycling the PineNote with its hardware power switch, or running the <code>rkdeveloptool reboot</code> command.
If you used the magnetic switch method be sure to remove the pen/magnet before rebooting.

== Backup ==

A backup of the content of the internal eMMC before anything gets messed up is '''mandatory'''.

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

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) contain data you may also 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.

This process was developed by Dorian Rudolph, originally described [https://github.com/DorianRudolph/pinenotes here].

=== List partitions ===

First, run <code>rkdeveloptool list-partitions</code> to print out your PineNote's partitions to get an idea of what you're dealing with.
The stock PineNote has a fairly standard [https://source.android.com/docs/core/architecture/partitions Android partition setup]:

{| class="wikitable"
|-
! Number !! Name !! Size !! Purpose
|-
| 0 || uboot || 4 MB || The [https://en.wikipedia.org/wiki/Das_U-Boot U-Boot] embedded systems bootloader
|-
| 1 || trust || 4 MB || Secrets that can be encrypted with a key stored in the [https://en.wikipedia.org/wiki/Trusted_Platform_Module TPM]
|-
| 2 || waveform || 2 MB || Important files controlling the e-ink screen's state changes
|-
| 3 || misc || 4 MB || Data used by the recovery partition
|-
| 4 || dtbo || 4 MB || [https://en.wikipedia.org/wiki/Devicetree Device Tree Blob for Overlay], files describing the PineNote's hardware configuration
|-
| 5 || vbmeta || 1 MB || Data required for [https://android.googlesource.com/platform/external/avb/+/master/README.md verified boot]
|-
| 6 || boot || 42 MB || The kernel image & ramdisk to boot
|-
| 7 || security || 4 MB ||
|-
| 8 || recovery || 134 MB || The recovery image, booted during Android updates
|-
| 9 || backup || 400 MB ||
|-
| 10 || cache || 1 GB || Stores temporary data; can be used to install a minimal Linux distribution!
|-
| 11 || metadata || 17 MB || Used for disk encryption
|-
| 12 || super || 3.25 GB || Android itself is installed here
|-
| 13 || logo || 17 MB || Splash image displayed during boot
|-
| 14 || device || 67 MB ||
|-
| 15 || userdata || 119 GB || The big one; user-installed Android apps and files live here
|}

=== Patch U-Boot ===

Before we can back up our partitions, we have a problem to solve.
The version of U-Boot installed on the stock PineNote contains a bug where it can't dump partitions beyond 32 MB (above that limit all bytes in the dump are just <code>0xCC</code>), meaning the PineNote must be flashed with a fixed version of U-Boot before it is possible to take a backup of the larger partitions.
It is possible to extract and modify the U-Boot image from your PineNote if you're interested in some light reverse-engineering (following Dorian's notes), or you can simply download a patched U-Boot image directly [https://github.com/DorianRudolph/pinenotes/blob/main/static/uboot_patched.img here].

Once you've acquired a patched U-Boot image, run:
# <code>rkdeveloptool read-partition uboot uboot_backup.img</code>
# <code>rkdeveloptool write-partition uboot uboot_patched.img</code>
# <code>rkdeveloptool reboot</code>

=== Taking the backup ===

With U-Boot patched, you can back up every partition except for super and userdata; run:

<code>rkdeveloptool read-partition partition_name partition_name_backup.img</code>

Unfortunately the super and userdata partitions run into a second limitation preventing dumping partitions larger than 2 GB, this time originating in <code>rkdeveloptool</code> itself.
This means if you have a large number of documents in the Android userdata partition they might not all make it into the backup.
If you don't have many documents (or don't care about losing them) this should not be a problem.
If you do have a lot of documents, workarounds include:
* A possible patch written by Thomas exists [https://github.com/tpwrules/nixos-pinenote/blob/96d2c9158edb9da59afcb952cc864fada18382f9/nix/rkdeveloptool/0001-fix-large-dumps.patch here] but has not yet been upstreamed; consider investigating how to get the patch tested & upstreamed, or just apply it to your own local copy of <code>rkdeveloptool</code>
* Use [https://github.com/talpadk/pinenote-backup this] Python script written by Visti Andresen (talpadk) to automatically backup your entire partition by splitting reads into 2 GB chunks

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].

=== 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.

== 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 ==

=== 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 current version (current as of 2022-01-02), there might have to be made 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>

You can now download u-boot onto the PineNote:

./rkdeveloptool boot ../u-boot-rockchip/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

{{Note|'''TODO:''' Section needs to be finished}}

=== 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 [[PineNote Development/Flashing#Creating a mainline boot image|Creating a mainline boot image]], 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 or
* get a U-Boot prompt and run <code>fastboot usb 0</code>.

[[Category:PineNote]]

PineNote Development/Flashing

2023-10-23T17:27:07Z

Ahelwer: /* List partitions */ Added partition descriptions

{{Under construction}}

{{Info|These instructions are directed towards experienced developers only!}}

This page contains information on flashing software to the [[PineNote]].

Currently, software can be flashed using rkdeveloptool or from the factory Android installation (UART shell, adb, or fastboot).

== Getting <code>rkdeveloptool</code> ==

Most flashing operations on the PineNote are done through <code>rkdeveloptool</code>, a command line utility built on libusb.
PINE64 maintains its own fork [https://gitlab.com/pine64-org/quartz-bsp/rkdeveloptool here] that you will need to get.
The repo's README contains a list of dependencies (libusb 1.0) and instructions for building the tool.

Installing (not just building) <code>rkdeveloptool</code> will configure PAM to elevate privileges where necessary on your system; you can configure this manually as follows:
<pre>
sudo cp 99-rk-rockusb.rules /etc/udev/rules.d/
sudo udevadm control --reload
</pre>

== Entering Maskrom/Rockusb mode ==

Interfacing with the PineNote over USB using <code>rkdeveloptool</code> requires first booting the PineNote into [http://opensource.rock-chips.com/wiki_Rockusb an alternative operating mode] called Maskrom or Rockusb mode.

=== Possible methods ===

There are three possible methods of entering Maskrom/Rockusb mode:

==== Hardware magnet switch ====

# Connect the PineNote to your computer via USB and boot the PineNote into Android
# Locate & identify the small circular marking on the back of the PineNote, in the top right quadrant; have the PineNote pen close at hand, or any other small magnet
# Hold the PineNote power button to bring up the reboot/shutdown menu; select reboot, then place the PineNote face down with the "eraser" end of the pen (or your magnet) resting on the small circular marking

<gallery>
Download mode.jpeg|Pen method
PineNoteMagnetOnBack.jpg|Magnet method
</gallery>

==== U-Boot terminal ====
This method requires a [[PineNote_Development/UART#USB_passthrough|UART dongle with passthrough]] allowing simultaneous UART & USB connections.
It is nice because you can easily switch back & forth between U-Boot and Rockusb without having to physically manipulate the PineNote or its connectors; this is especially helpful when trying to develop U-Boot.

# Connect to the PineNote via UART and USB simultaneously
# Interrupt the U-Boot startup using <code>ctrl+c</code> sent over UART
# In the U-Boot terminal over UART, run <code>rockusb 0 mmc 0</code>

The UART terminal should print <code>RKUSB</code> then a spinner will appear.
You can exit back to the U-Boot terminal by sending <code>ctrl+c</code> again.

==== 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]]

=== Success ===

No matter what approach you take, you can tell whether you succeeded by running the <code>lsusb</code> command on your computer:
* If you find the entry <code>2207:0018 Fuzhou Rockchip Electronics Company rk3566_eink</code> in the list, the process did not succeed; reboot and retry
* The entry <code>2207:350a Fuzhou Rockchip Electronics Company</code> will occur if you detach then reattach the USB-C cable while the PineNote is in Maskrom/Rockusb mode; <code>rkdeveloptool</code> won't work and you will have to do a hard reboot (hold down power button for 30 seconds to shutdown)
* If you find the entry <code>2207:350a Fuzhou Rockchip Electronics Company USB download gadget</code> then the process succeeded

You can also look at the output of the <code>rkdeveloptool list</code> command:
* If this prints out <code>No devices in rockusb mode found</code> the process did not succeed; reboot and retry
* If this prints out <code>DevNo=1 Vid=0x2207,Pid=0x350a,LocationID=305 Maskrom</code> then you probably detached/reattached the USB-C cable while in Maskrom/Rockusb mode and <code>rkdeveloptool</code> won't work; perform a hard reboot to fix
* If this prints out <code>DevNo=1 Vid=0x2207,Pid=0x350a,LocationID=303 Loader</code> then the process succeeded

=== Exiting ===

You can boot the PineNote back into its normal mode of operation by powercycling the PineNote with its hardware power switch, or running the <code>rkdeveloptool reboot</code> command.
If you used the magnetic switch method be sure to remove the pen/magnet before rebooting.

== Backup ==

A backup of the content of the internal eMMC before anything gets messed up is '''mandatory'''.

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

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) contain data you may also 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.

This process was developed by Dorian Rudolph, originally described [https://github.com/DorianRudolph/pinenotes here].

=== List partitions ===

First, run <code>rkdeveloptool list-partitions</code> to print out your PineNote's partitions to get an idea of what you're dealing with.
The stock PineNote has a fairly standard [https://source.android.com/docs/core/architecture/partitions Android partition setup]:

{| class="wikitable"
|-
! Number !! Name !! Size !! Purpose
|-
| 0 || uboot || 4 MB || The [https://en.wikipedia.org/wiki/Das_U-Boot U-Boot] embedded systems bootloader
|-
| 1 || trust || 4 MB || Secrets that can be encrypted with a key stored in the [https://en.wikipedia.org/wiki/Trusted_Platform_Module TPM]
|-
| 2 || waveform || 2 MB || Important files controlling the e-ink screen's state changes
|-
| 3 || misc || 4 MB || Data used by the recovery partition
|-
| 4 || dtbo || 4 MB || [https://en.wikipedia.org/wiki/Devicetree Device Tree Blob for Overlay], files describing the PineNote's hardware configuration
|-
| 5 || vbmeta || 1 MB || Data required for [https://android.googlesource.com/platform/external/avb/+/master/README.md verified boot]
|-
| 6 || boot || 42 MB || The kernel image & ramdisk to boot
|-
| 7 || security || 4 MB ||
|-
| 8 || recovery || 134 MB || The recovery image, booted during Android updates
|-
| 9 || backup || 400 MB ||
|-
| 10 || cache || 1 GB || Stores temporary data; can be used to install a minimal Linux distribution!
|-
| 11 || metadata || 17 MB || Used for disk encryption
|-
| 12 || super || 3.25 GB || Android itself is installed here
|-
| 13 || logo || 17 MB || Splash image displayed during boot
|-
| 14 || device || 67 MB ||
|-
| 15 || userdata || 119 GB || The big one; user-installed Android apps and files live here
|}

=== Patch U-Boot ===

Before we can back up our partitions, we have a problem to solve.
The version of U-Boot installed on the stock PineNote contains a bug where it can't dump partitions beyond 32 MB (above that limit all bytes in the dump are just <code>0xCC</code>), meaning the PineNote must be flashed with a fixed version of U-Boot before it is possible to take a backup of the larger partitions.
It is possible to extract and modify the U-Boot image from your PineNote if you're interested in some light reverse-engineering (following Dorian's notes), or you can simply download a patched U-Boot image directly [https://github.com/DorianRudolph/pinenotes/blob/main/static/uboot_patched.img here].

Once you've acquired a patched U-Boot image, run:
# <code>rkdeveloptool read-partition uboot uboot_backup.img</code>
# <code>rkdeveloptool write-partition uboot uboot_patched.img</code>
# <code>rkdeveloptool reboot</code>

=== Taking the backup ===

With U-Boot patched, run:

<code>rkdeveloptool read-partition partition_name partition_name_backup.img</code>

There is a second backup limit preventing dumping partitions larger than 2 GB, this time from <code>rkdeveloptool</code>.
This means if you have a large number of documents in the Android userdata partition they might not all make it into the backup.
If you don't have many documents (or don't care about losing them) this should not be a problem.
If you do have a lot of documents, workarounds include:
* A possible patch written by Thomas exists [https://github.com/tpwrules/nixos-pinenote/blob/96d2c9158edb9da59afcb952cc864fada18382f9/nix/rkdeveloptool/0001-fix-large-dumps.patch here] but has not yet been upstreamed; consider investigating how to get the patch tested & upstreamed, or just apply it to your own local copy of <code>rkdeveloptool</code>
* Use [https://github.com/talpadk/pinenote-backup this] Python script written by Visti Andresen (talpadk) to automatically backup your entire partition by splitting reads into 2 GB chunks

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].

=== 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.

== 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 ==

=== 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 current version (current as of 2022-01-02), there might have to be made 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>

You can now download u-boot onto the PineNote:

./rkdeveloptool boot ../u-boot-rockchip/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

{{Note|'''TODO:''' Section needs to be finished}}

=== 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 [[PineNote Development/Flashing#Creating a mainline boot image|Creating a mainline boot image]], 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 or
* get a U-Boot prompt and run <code>fastboot usb 0</code>.

[[Category:PineNote]]

PineNote Development/Flashing

2023-10-23T16:52:16Z

Ahelwer: /* Backup */ Added partition table

{{Under construction}}

{{Info|These instructions are directed towards experienced developers only!}}

This page contains information on flashing software to the [[PineNote]].

Currently, software can be flashed using rkdeveloptool or from the factory Android installation (UART shell, adb, or fastboot).

== Getting <code>rkdeveloptool</code> ==

Most flashing operations on the PineNote are done through <code>rkdeveloptool</code>, a command line utility built on libusb.
PINE64 maintains its own fork [https://gitlab.com/pine64-org/quartz-bsp/rkdeveloptool here] that you will need to get.
The repo's README contains a list of dependencies (libusb 1.0) and instructions for building the tool.

Installing (not just building) <code>rkdeveloptool</code> will configure PAM to elevate privileges where necessary on your system; you can configure this manually as follows:
<pre>
sudo cp 99-rk-rockusb.rules /etc/udev/rules.d/
sudo udevadm control --reload
</pre>

== Entering Maskrom/Rockusb mode ==

Interfacing with the PineNote over USB using <code>rkdeveloptool</code> requires first booting the PineNote into [http://opensource.rock-chips.com/wiki_Rockusb an alternative operating mode] called Maskrom or Rockusb mode.

=== Possible methods ===

There are three possible methods of entering Maskrom/Rockusb mode:

==== Hardware magnet switch ====

# Connect the PineNote to your computer via USB and boot the PineNote into Android
# Locate & identify the small circular marking on the back of the PineNote, in the top right quadrant; have the PineNote pen close at hand, or any other small magnet
# Hold the PineNote power button to bring up the reboot/shutdown menu; select reboot, then place the PineNote face down with the "eraser" end of the pen (or your magnet) resting on the small circular marking

<gallery>
Download mode.jpeg|Pen method
PineNoteMagnetOnBack.jpg|Magnet method
</gallery>

==== U-Boot terminal ====
This method requires a [[PineNote_Development/UART#USB_passthrough|UART dongle with passthrough]] allowing simultaneous UART & USB connections.
It is nice because you can easily switch back & forth between U-Boot and Rockusb without having to physically manipulate the PineNote or its connectors; this is especially helpful when trying to develop U-Boot.

# Connect to the PineNote via UART and USB simultaneously
# Interrupt the U-Boot startup using <code>ctrl+c</code> sent over UART
# In the U-Boot terminal over UART, run <code>rockusb 0 mmc 0</code>

The UART terminal should print <code>RKUSB</code> then a spinner will appear.
You can exit back to the U-Boot terminal by sending <code>ctrl+c</code> again.

==== 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]]

=== Success ===

No matter what approach you take, you can tell whether you succeeded by running the <code>lsusb</code> command on your computer:
* If you find the entry <code>2207:0018 Fuzhou Rockchip Electronics Company rk3566_eink</code> in the list, the process did not succeed; reboot and retry
* The entry <code>2207:350a Fuzhou Rockchip Electronics Company</code> will occur if you detach then reattach the USB-C cable while the PineNote is in Maskrom/Rockusb mode; <code>rkdeveloptool</code> won't work and you will have to do a hard reboot (hold down power button for 30 seconds to shutdown)
* If you find the entry <code>2207:350a Fuzhou Rockchip Electronics Company USB download gadget</code> then the process succeeded

You can also look at the output of the <code>rkdeveloptool list</code> command:
* If this prints out <code>No devices in rockusb mode found</code> the process did not succeed; reboot and retry
* If this prints out <code>DevNo=1 Vid=0x2207,Pid=0x350a,LocationID=305 Maskrom</code> then you probably detached/reattached the USB-C cable while in Maskrom/Rockusb mode and <code>rkdeveloptool</code> won't work; perform a hard reboot to fix
* If this prints out <code>DevNo=1 Vid=0x2207,Pid=0x350a,LocationID=303 Loader</code> then the process succeeded

=== Exiting ===

You can boot the PineNote back into its normal mode of operation by powercycling the PineNote with its hardware power switch, or running the <code>rkdeveloptool reboot</code> command.
If you used the magnetic switch method be sure to remove the pen/magnet before rebooting.

== Backup ==

A backup of the content of the internal eMMC before anything gets messed up is '''mandatory'''.

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

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) contain data you may also 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.

This process was developed by Dorian Rudolph, originally described [https://github.com/DorianRudolph/pinenotes here].

=== List partitions ===

First, run <code>rkdeveloptool list-partitions</code> to print out your PineNote's partitions to get an idea of what you're dealing with.
The stock PineNote has a fairly standard [https://source.android.com/docs/core/architecture/partitions Android partition setup]:

{| class="wikitable"
|-
! Number !! Name !! Size !! Purpose
|-
| 0 || uboot || 4 MB || The [https://en.wikipedia.org/wiki/Das_U-Boot U-Boot] embedded systems bootloader
|-
| 1 || trust || 4 MB || Secrets that can be encrypted with a key stored in the [https://en.wikipedia.org/wiki/Trusted_Platform_Module TPM]
|-
| 2 || waveform || 2 MB || Important files controlling the e-ink screen's state changes
|-
| 3 || misc || 4 MB || Data used by the recovery partition
|-
| 4 || dtbo || 4 MB || [https://en.wikipedia.org/wiki/Devicetree Device Tree Blob for Overlay], files describing the PineNote's hardware configuration
|-
| 5 || vbmeta || 1 MB || Data required for [https://android.googlesource.com/platform/external/avb/+/master/README.md verified boot]
|-
| 6 || boot || 42 MB || The kernel image & ramdisk to boot
|-
| 7 || security || 4 MB ||
|-
| 8 || recovery || 134 MB || The recovery image, booted during Android updates
|-
| 9 || backup || 400 MB ||
|-
| 10 || cache || 1 GB || Stores temporary data; can be used to install a minimal Linux distribution!
|-
| 11 || metadata || 17 MB ||
|-
| 12 || super || 3.25 GB ||
|-
| 13 || logo || 17 MB ||
|-
| 14 || device || 67 MB ||
|-
| 15 || userdata || 119 GB ||
|}

=== Patch U-Boot ===

Before we can back up our partitions, we have a problem to solve.
The version of U-Boot installed on the stock PineNote contains a bug where it can't dump partitions beyond 32 MB (above that limit all bytes in the dump are just <code>0xCC</code>), meaning the PineNote must be flashed with a fixed version of U-Boot before it is possible to take a backup of the larger partitions.
It is possible to extract and modify the U-Boot image from your PineNote if you're interested in some light reverse-engineering (following Dorian's notes), or you can simply download a patched U-Boot image directly [https://github.com/DorianRudolph/pinenotes/blob/main/static/uboot_patched.img here].

Once you've acquired a patched U-Boot image, run:
# <code>rkdeveloptool read-partition uboot uboot_backup.img</code>
# <code>rkdeveloptool write-partition uboot uboot_patched.img</code>
# <code>rkdeveloptool reboot</code>

=== Taking the backup ===

With U-Boot patched, run:

<code>rkdeveloptool read-partition partition_name partition_name_backup.img</code>

There is a second backup limit preventing dumping partitions larger than 2 GB, this time from <code>rkdeveloptool</code>.
This means if you have a large number of documents in the Android userdata partition they might not all make it into the backup.
If you don't have many documents (or don't care about losing them) this should not be a problem.
If you do have a lot of documents, workarounds include:
* A possible patch written by Thomas exists [https://github.com/tpwrules/nixos-pinenote/blob/96d2c9158edb9da59afcb952cc864fada18382f9/nix/rkdeveloptool/0001-fix-large-dumps.patch here] but has not yet been upstreamed; consider investigating how to get the patch tested & upstreamed, or just apply it to your own local copy of <code>rkdeveloptool</code>
* Use [https://github.com/talpadk/pinenote-backup this] Python script written by Visti Andresen (talpadk) to automatically backup your entire partition by splitting reads into 2 GB chunks

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].

=== 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.

== 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 ==

=== 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 current version (current as of 2022-01-02), there might have to be made 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>

You can now download u-boot onto the PineNote:

./rkdeveloptool boot ../u-boot-rockchip/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

{{Note|'''TODO:''' Section needs to be finished}}

=== 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 [[PineNote Development/Flashing#Creating a mainline boot image|Creating a mainline boot image]], 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 or
* get a U-Boot prompt and run <code>fastboot usb 0</code>.

[[Category:PineNote]]

PineNote Development/Flashing

2023-10-23T15:57:45Z

Ahelwer: /* Taking the backup */

{{Under construction}}

{{Info|These instructions are directed towards experienced developers only!}}

This page contains information on flashing software to the [[PineNote]].

Currently, software can be flashed using rkdeveloptool or from the factory Android installation (UART shell, adb, or fastboot).

== Getting <code>rkdeveloptool</code> ==

Most flashing operations on the PineNote are done through <code>rkdeveloptool</code>, a command line utility built on libusb.
PINE64 maintains its own fork [https://gitlab.com/pine64-org/quartz-bsp/rkdeveloptool here] that you will need to get.
The repo's README contains a list of dependencies (libusb 1.0) and instructions for building the tool.

Installing (not just building) <code>rkdeveloptool</code> will configure PAM to elevate privileges where necessary on your system; you can configure this manually as follows:
<pre>
sudo cp 99-rk-rockusb.rules /etc/udev/rules.d/
sudo udevadm control --reload
</pre>

== Entering Maskrom/Rockusb mode ==

Interfacing with the PineNote over USB using <code>rkdeveloptool</code> requires first booting the PineNote into [http://opensource.rock-chips.com/wiki_Rockusb an alternative operating mode] called Maskrom or Rockusb mode.

=== Possible methods ===

There are three possible methods of entering Maskrom/Rockusb mode:

==== Hardware magnet switch ====

# Connect the PineNote to your computer via USB and boot the PineNote into Android
# Locate & identify the small circular marking on the back of the PineNote, in the top right quadrant; have the PineNote pen close at hand, or any other small magnet
# Hold the PineNote power button to bring up the reboot/shutdown menu; select reboot, then place the PineNote face down with the "eraser" end of the pen (or your magnet) resting on the small circular marking

<gallery>
Download mode.jpeg|Pen method
PineNoteMagnetOnBack.jpg|Magnet method
</gallery>

==== U-Boot terminal ====
This method requires a [[PineNote_Development/UART#USB_passthrough|UART dongle with passthrough]] allowing simultaneous UART & USB connections.
It is nice because you can easily switch back & forth between U-Boot and Rockusb without having to physically manipulate the PineNote or its connectors; this is especially helpful when trying to develop U-Boot.

# Connect to the PineNote via UART and USB simultaneously
# Interrupt the U-Boot startup using <code>ctrl+c</code> sent over UART
# In the U-Boot terminal over UART, run <code>rockusb 0 mmc 0</code>

The UART terminal should print <code>RKUSB</code> then a spinner will appear.
You can exit back to the U-Boot terminal by sending <code>ctrl+c</code> again.

==== 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]]

=== Success ===

No matter what approach you take, you can tell whether you succeeded by running the <code>lsusb</code> command on your computer:
* If you find the entry <code>2207:0018 Fuzhou Rockchip Electronics Company rk3566_eink</code> in the list, the process did not succeed; reboot and retry
* The entry <code>2207:350a Fuzhou Rockchip Electronics Company</code> will occur if you detach then reattach the USB-C cable while the PineNote is in Maskrom/Rockusb mode; <code>rkdeveloptool</code> won't work and you will have to do a hard reboot (hold down power button for 30 seconds to shutdown)
* If you find the entry <code>2207:350a Fuzhou Rockchip Electronics Company USB download gadget</code> then the process succeeded

You can also look at the output of the <code>rkdeveloptool list</code> command:
* If this prints out <code>No devices in rockusb mode found</code> the process did not succeed; reboot and retry
* If this prints out <code>DevNo=1 Vid=0x2207,Pid=0x350a,LocationID=305 Maskrom</code> then you probably detached/reattached the USB-C cable while in Maskrom/Rockusb mode and <code>rkdeveloptool</code> won't work; perform a hard reboot to fix
* If this prints out <code>DevNo=1 Vid=0x2207,Pid=0x350a,LocationID=303 Loader</code> then the process succeeded

=== Exiting ===

You can boot the PineNote back into its normal mode of operation by powercycling the PineNote with its hardware power switch, or running the <code>rkdeveloptool reboot</code> command.
If you used the magnetic switch method be sure to remove the pen/magnet before rebooting.

== Backup ==

A backup of the content of the internal eMMC before anything gets messed up is '''mandatory'''.

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

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) contain data you may also 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.

This process was developed by Dorian Rudolph, originally described [https://github.com/DorianRudolph/pinenotes here].

=== List partitions ===

First, run <code>rkdeveloptool list-partitions</code> to print out your PineNote's partitions to get an idea of what you're dealing with.
The stock PineNote has a fairly standard Android partition setup, including:
* uboot: the [https://en.wikipedia.org/wiki/Das_U-Boot U-Boot] embedded systems bootloader
* trust: secrets that can be encrypted with a key stored in the [https://en.wikipedia.org/wiki/Trusted_Platform_Module TPM]
* waveform: important files controlling the e-ink screen's state changes
* misc: miscellaneous files needed by the firmware
* dtbo: [https://en.wikipedia.org/wiki/Devicetree Device Tree Blob for Overlay], files describing the PineNote's hardware configuration
* vbmeta: data required for verified boot
* boot, security, recovery, backup, cache, metadata, super, logo, device
* userdata: the big one; this is where all your files are stored in the stock Android install

=== Patch U-Boot ===

Before we can back up our partitions, we have a problem to solve.
The version of U-Boot installed on the stock PineNote contains a bug where it can't dump partitions beyond 32 MB (above that limit all bytes in the dump are just <code>0xCC</code>), meaning the PineNote must be flashed with a fixed version of U-Boot before it is possible to take a backup of the larger partitions.
It is possible to extract and modify the U-Boot image from your PineNote if you're interested in some light reverse-engineering (following Dorian's notes), or you can simply download a patched U-Boot image directly [https://github.com/DorianRudolph/pinenotes/blob/main/static/uboot_patched.img here].

Once you've acquired a patched U-Boot image, run:
# <code>rkdeveloptool read-partition uboot uboot_backup.img</code>
# <code>rkdeveloptool write-partition uboot uboot_patched.img</code>
# <code>rkdeveloptool reboot</code>

=== Taking the backup ===

There is a second backup limit preventing dumping partitions larger than 2 GB, this time from <code>rkdeveloptool</code>.
This means if you have a large number of documents in the Android userdata partition they might not all make it into the backup.
If you don't have many documents (or don't care about losing them) this should not be a problem.
If you do have a lot of documents, workarounds include:
* A possible patch written by Thomas exists [https://github.com/tpwrules/nixos-pinenote/blob/96d2c9158edb9da59afcb952cc864fada18382f9/nix/rkdeveloptool/0001-fix-large-dumps.patch here] but has not yet been upstreamed; consider investigating how to get the patch tested & upstreamed, or just apply it to your own local copy of <code>rkdeveloptool</code>
* Use [https://github.com/talpadk/pinenote-backup this] Python script written by Visti Andresen (talpadk) to automatically backup your entire partition by splitting reads into 2 GB chunks

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].

=== 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.

== 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 ==

=== 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 current version (current as of 2022-01-02), there might have to be made 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>

You can now download u-boot onto the PineNote:

./rkdeveloptool boot ../u-boot-rockchip/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

{{Note|'''TODO:''' Section needs to be finished}}

=== 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 [[PineNote Development/Flashing#Creating a mainline boot image|Creating a mainline boot image]], 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 or
* get a U-Boot prompt and run <code>fastboot usb 0</code>.

[[Category:PineNote]]

PineNote Development/Flashing

2023-10-23T00:19:38Z

Ahelwer:

{{Under construction}}

{{Info|These instructions are directed towards experienced developers only!}}

This page contains information on flashing software to the [[PineNote]].

Currently, software can be flashed using rkdeveloptool or from the factory Android installation (UART shell, adb, or fastboot).

== Getting <code>rkdeveloptool</code> ==

Most flashing operations on the PineNote are done through <code>rkdeveloptool</code>, a command line utility built on libusb.
PINE64 maintains its own fork [https://gitlab.com/pine64-org/quartz-bsp/rkdeveloptool here] that you will need to get.
The repo's README contains a list of dependencies (libusb 1.0) and instructions for building the tool.

Installing (not just building) <code>rkdeveloptool</code> will configure PAM to elevate privileges where necessary on your system; you can configure this manually as follows:
<pre>
sudo cp 99-rk-rockusb.rules /etc/udev/rules.d/
sudo udevadm control --reload
</pre>

== Entering Maskrom/Rockusb mode ==

Interfacing with the PineNote over USB using <code>rkdeveloptool</code> requires first booting the PineNote into [http://opensource.rock-chips.com/wiki_Rockusb an alternative operating mode] called Maskrom or Rockusb mode.

=== Possible methods ===

There are three possible methods of entering Maskrom/Rockusb mode:

==== Hardware magnet switch ====

# Connect the PineNote to your computer via USB and boot the PineNote into Android
# Locate & identify the small circular marking on the back of the PineNote, in the top right quadrant; have the PineNote pen close at hand, or any other small magnet
# Hold the PineNote power button to bring up the reboot/shutdown menu; select reboot, then place the PineNote face down with the "eraser" end of the pen (or your magnet) resting on the small circular marking

<gallery>
Download mode.jpeg|Pen method
PineNoteMagnetOnBack.jpg|Magnet method
</gallery>

==== U-Boot terminal ====
This method requires a [[PineNote_Development/UART#USB_passthrough|UART dongle with passthrough]] allowing simultaneous UART & USB connections.
It is nice because you can easily switch back & forth between U-Boot and Rockusb without having to physically manipulate the PineNote or its connectors; this is especially helpful when trying to develop U-Boot.

# Connect to the PineNote via UART and USB simultaneously
# Interrupt the U-Boot startup using <code>ctrl+c</code> sent over UART
# In the U-Boot terminal over UART, run <code>rockusb 0 mmc 0</code>

The UART terminal should print <code>RKUSB</code> then a spinner will appear.
You can exit back to the U-Boot terminal by sending <code>ctrl+c</code> again.

==== 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]]

=== Success ===

No matter what approach you take, you can tell whether you succeeded by running the <code>lsusb</code> command on your computer:
* If you find the entry <code>2207:0018 Fuzhou Rockchip Electronics Company rk3566_eink</code> in the list, the process did not succeed; reboot and retry
* The entry <code>2207:350a Fuzhou Rockchip Electronics Company</code> will occur if you detach then reattach the USB-C cable while the PineNote is in Maskrom/Rockusb mode; <code>rkdeveloptool</code> won't work and you will have to do a hard reboot (hold down power button for 30 seconds to shutdown)
* If you find the entry <code>2207:350a Fuzhou Rockchip Electronics Company USB download gadget</code> then the process succeeded

You can also look at the output of the <code>rkdeveloptool list</code> command:
* If this prints out <code>No devices in rockusb mode found</code> the process did not succeed; reboot and retry
* If this prints out <code>DevNo=1 Vid=0x2207,Pid=0x350a,LocationID=305 Maskrom</code> then you probably detached/reattached the USB-C cable while in Maskrom/Rockusb mode and <code>rkdeveloptool</code> won't work; perform a hard reboot to fix
* If this prints out <code>DevNo=1 Vid=0x2207,Pid=0x350a,LocationID=303 Loader</code> then the process succeeded

=== Exiting ===

You can boot the PineNote back into its normal mode of operation by powercycling the PineNote with its hardware power switch, or running the <code>rkdeveloptool reboot</code> command.
If you used the magnetic switch method be sure to remove the pen/magnet before rebooting.

== Backup ==

A backup of the content of the internal eMMC before anything gets messed up is '''mandatory'''.

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

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) contain data you may also 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.

This process was developed by Dorian Rudolph, originally described [https://github.com/DorianRudolph/pinenotes here].

=== List partitions ===

First, run <code>rkdeveloptool list-partitions</code> to print out your PineNote's partitions to get an idea of what you're dealing with.
The stock PineNote has a fairly standard Android partition setup, including:
* uboot: the [https://en.wikipedia.org/wiki/Das_U-Boot U-Boot] embedded systems bootloader
* trust: secrets that can be encrypted with a key stored in the [https://en.wikipedia.org/wiki/Trusted_Platform_Module TPM]
* waveform: important files controlling the e-ink screen's state changes
* misc: miscellaneous files needed by the firmware
* dtbo: [https://en.wikipedia.org/wiki/Devicetree Device Tree Blob for Overlay], files describing the PineNote's hardware configuration
* vbmeta: data required for verified boot
* boot, security, recovery, backup, cache, metadata, super, logo, device
* userdata: the big one; this is where all your files are stored in the stock Android install

=== Patch U-Boot ===

Before we can back up our partitions, we have a problem to solve.
The version of U-Boot installed on the stock PineNote contains a bug where it can't dump partitions beyond 32 MB (above that limit all bytes in the dump are just <code>0xCC</code>), meaning the PineNote must be flashed with a fixed version of U-Boot before it is possible to take a backup of the larger partitions.
It is possible to extract and modify the U-Boot image from your PineNote if you're interested in some light reverse-engineering (following Dorian's notes), or you can simply download a patched U-Boot image directly [https://github.com/DorianRudolph/pinenotes/blob/main/static/uboot_patched.img here].

Once you've acquired a patched U-Boot image, run:
# <code>rkdeveloptool read-partition uboot uboot_backup.img</code>
# <code>rkdeveloptool write-partition uboot uboot_patched.img</code>
# <code>rkdeveloptool reboot</code>

=== Taking the backup ===

There is a second backup limit preventing dumping partitions larger than 2 GB, this time from <code>rkdeveloptool</code>.
This means if you have a large number of documents in the Android userdata partition they might not all make it into the backup.
If you don't have many documents (or don't care about losing them) this should not be a problem.
If you do have a lot of documents, workarounds include:
* A possible patch written by Thomas exists [https://github.com/tpwrules/nixos-pinenote/blob/96d2c9158edb9da59afcb952cc864fada18382f9/nix/rkdeveloptool/0001-fix-large-dumps.patch here] but has not yet been upstreamed; consider investigating how to get the patch tested & upstreamed, or just apply it to your own local copy of <code>rkdeveloptool</code>
* Use [https://github.com/talpadk/pinenote-backup this] Python script written by Visti Andresen to automatically backup your entire partition by splitting reads into 2 GB chunks

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].

=== 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.

== 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 ==

=== 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 current version (current as of 2022-01-02), there might have to be made 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>

You can now download u-boot onto the PineNote:

./rkdeveloptool boot ../u-boot-rockchip/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

{{Note|'''TODO:''' Section needs to be finished}}

=== 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 [[PineNote Development/Flashing#Creating a mainline boot image|Creating a mainline boot image]], 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 or
* get a U-Boot prompt and run <code>fastboot usb 0</code>.

[[Category:PineNote]]

PineNote Development/UART

2023-10-14T21:17:02Z

Ahelwer: /* Using the dongle */ fixed link

[[File:Pinenote-uart-dongle.jpeg|thumb|Basic non-stock PineNote UART dongle]]

This page contains information on creating and using a [https://en.wikipedia.org/wiki/Universal_asynchronous_receiver-transmitter UART] dongle for the [[PineNote]].
The PineNote was shipped with a compatible UART dongle, but replacements are not available to order in case of loss or hardware fault.
Thankfully it is not difficult to make your own from easily-acquired components and a small bit of soldering.

Fear not if you've never soldered anything before!
This serves as an excellent first soldering project.
Borrow the tools from a friend, local hackerspace, or tool library.
Pine64 also makes [[Pinecil|a nice soldering iron]] themselves.

A PineNote UART dongle enables you to:
# Interact with the system boot menu
# Read system events in real time as the PineNote is used
# Fix the PineNote without opening the case if something goes wrong while [[PineNote Development/Flashing|flashing it]]

Since the PineNote is an embedded system, interfacing with it during boot is more complicated than with an ordinary computer.
The UART dongle enables you to do this.

The PineNote factory firmware runs UART at a baud rate of 1500000 bps, 8 data bits, 1 stop bit, no parity and no flow control.
The process by which the PineNote design was modified to include closed-case UART is documented [[PineNote/Hardware Changes/Closed Case UART|here]].

== Stock dongle ==

The stock UART dongle included with the PineNote was a simple device plugging directly into the PineNote's USB-C port.
The dongle exposed a female USB-C port, which the user plugged into to get UART access.
This design unfortunately ruled out passthrough USB connections, where the user connects to the PineNote via UART and USB simultaneously.
The dongle is not currently available for purchase.

<gallery>
Pinenote-stock-uart-dongle-front.jpg|Front
Pinenote-stock-uart-dongle-back.jpg|Back
</gallery>

== Creating a dongle ==

A typical self-built PineNote UART dongle design has the following components:
# A USB-C breakout board with a male connector exposing the 24 pins of the PineNote's USB-C port
# A USB-UART adapter, to plug into a USB port of the computer you'll use to interface with the PineNote
# [https://en.wikipedia.org/wiki/Jump_wire Jump wires] to connect specific breakout board pins to pins on the USB-UART adapter
# Two 1,000 Ohm through-hole resistors to splice into the jump wires
# Electrical tape or heat shrink to wrap connectors and prevent shorts

You will also need the following tools:
# Soldering iron with solder
# Wire cutters & strippers

The PineNote's internal UART system is documented in [https://files.pine64.org/doc/PineNote/PineNote_USB-C_Console_UART_breakout_board_schematic_v1.0_20210903.pdf this schematic].
The purpose of all 24 USB-C pins is documented [https://en.wikipedia.org/wiki/USB-C#Receptacles on the USB-C Wikipedia page].
We are interested in three sets of pins:
# The SBU1 (A8) and SBU2 (B8) side band use pins
# The CC1 (A5) and CC2 (B5) configuration channel pins
# The GND [https://en.wikipedia.org/wiki/Ground_(electricity) ground return] pins (A1, A12, B1, and B12)

In the PineNote UART schematic you can see (on the bottom right diagram labeled <code>USB_TYPEC_Male</code>) the side band pins are given the labels <code>UART2_TX_SUB1</code> for A8 and <code>UART2_RX_SUB2</code> for B8.
The first (TX) is used for transmitting data and the second (RX) is used for receiving data, from the perspective of the PineNote.
Also note the configuration channel pins labeled <code>TYPEC_CC1</code> for A5 and <code>TYPEC_CC2</code> for B5.
The diagram shows they must be connected to a 3.3V source in parallel, mediated by resistors.
Per the USB-C standard, when these pins are pulled high this indicates the device should enter [https://en.wikipedia.org/wiki/USB-C#Debug_Accessory_Mode Debug Accessory Mode]; connecting them to a voltage source & limiting the current with [https://www.electronics-tutorials.ws/logic/pull-up-resistor.html pull-up resistors] accomplishes this.
The schematic indicates 10,000 Ohm resistors, but community member Visti Andresen (talpadk) experimented and found 1,000 Ohm resistors work better.
Our mission is to wire up pins from a USB-UART adapter to a USB-C breakout board following these requirements.

=== Buying components ===

There are many possible USB-C breakout board designs available for purchase online.
One particularly useful design is a "passthrough" or "intercept" style, with both male and female USB-C ports.
This design is more versatile in case you want to reuse it in other projects, and also enables you to connect to the PineNote via UART and USB at the same time.
An example of this product can be found [https://pmdway.com/products/usb-3-1-type-c-male-to-female-breakout-test-board here], although you are encouraged to shop around for cheaper options.
If you're fine with a bit more soldering, there is a very cheap one [https://www.ebay.com/itm/275407037613 here].

Similarly, there are many USB-UART adapter designs available.
These devices plug into your computer and expose a number of pins themselves, connecting to specific pins on the breakout board with jump wires.
It is important to get a 3.3V model, or at least a model with the option of 3.3V, as a 5V source might fry the PineNote.
[https://pmdway.com/products/usb-to-ttl-serial-cp2104-6-pin-converter-module Here] is one example with jump wires included, although you are again encouraged to shop around for alternatives.

All other necessary components of our UART dongle are readily & cheaply available in many locations.

=== Splicing resistors ===

[[File:PineNote-UART-Y-pull-up-resistor-cable.jpg|thumb|The desired end result; wrap removed from resistors for illustration purposes.]]

This is the only difficult part of the whole process.
Your goal is to create a Y-shaped jump wire with 1,000 Ohm through-hole resistors spliced into each of the twin arms.
The solitary leg will connect to a 3.3V source on your USB-UART adapter.
The twin arms will connect to the configuration channel pins on your USB-C breakout board.
Per the USB-C standard, when these pins are pulled high this indicates the device should enter [https://en.wikipedia.org/wiki/USB-C#Debug_Accessory_Mode Debug Accessory Mode]; connecting them to a voltage source & limiting the current with [https://www.electronics-tutorials.ws/logic/pull-up-resistor.html pull-up resistors] accomplishes this.

For this project you'll need:
# A soldering iron with solder
# Wire cutters & strippers
# 2x jumper wires, male/female as compatible with your board designs
# 2x 1,000 Ohm through-hole resistors
# Electrical tape or heat shrink wrap

Consider buying extra jumper wires and resistors in case you mess up.
Also double-check that you have 1K resistors with [https://resistorcolorcodecalc.com/ this color code calculator].
Although the PineNote UART schematic says to use 10K Ohm resistors, community member Visti Andresen (talpadk) experimented and found 1K is more appropriate.
Assemble your Y-cable as follows:
# Graft one jump wire onto the other to form a Y shape using [https://www.youtube.com/watch?v=KpiEfuhPqew this] technique, ensuring solitary leg end is compatible with your USB-UART adapter
# Splice resistors into the twin arms using [https://www.youtube.com/watch?v=RMgMVqqjPZ0 this] technique
# Splice remaining jump wire onto the ends of the resistors, ensuring ends are compatible with your USB-C breakout board
# Cover all exposed wire & resistors with electrical tape or heat shrink wrap

=== Assembly ===

Once you have acquired all necessary components, assemble the UART dongle as follows:
# Connect a jump wire from the GND pin on the USB-UART adapter to any one of the four GND pins on the USB-C breakout board (A1, A12, B1, or B12)
# Connect a jump wire from the RXD pin on the USB-UART adapter to the <code>UART2_TX_SUB1</code> SBU1 pin on the USB-C breakout board (A8)
# Connect a jump wire from the TXD pin on the USB-UART adapter to the <code>UART2_RX_SUB2</code> SBU2 pin on the USB-C breakout board (B8)
# Connect your Y-shaped jump wire from the 3.3V source pin on the USB-UART adapter to the CC1 and CC2 pins on the USB-C breakout board (A5 and B5)
# Wrap all metal connectors in electrical tape or heat shrink to prevent accidental shorts

Be '''very certain''' of your connections for the 3.3V source and its cable, as there is a real risk of irreparably frying your PineNote if they're wrong!
Especially be sure you are connecting to a 3.3V source and not a 5V source.

Note that if you mix up the TX/RX pins, it will still work but the USB-C breakout board will just plug into the PineNote upside down.
You can therefore choose which orientation you want by swapping the TX/RX pin connections.
Experience shows that RX/TX-TX/RX connections will have the PineNote face down while connected, while RX/RX-TX/TX connections will put the PineNote face up.

== Using the dongle ==

First, use your UART dongle to physically connect your PineNote to your computer:
# Plug the USB-UART adapter into one of your computer's USB ports
# Plug the USB-C breakout board into the USB-C port on the bottom of your PineNote; the orientation matters, so try both and remember which one works

Once the hardware is connected, we need some program on your computer to communicate over that connection with 1500000 (1.5 million) bps, 8 data bits, 1 stop bit, no parity and no flow control.
Here's how you do that:
# Identify the USB-UART adapter in your <code>/dev</code> directory by running <code>ls /dev</code> with it plugged in, unplugging it, then again running <code>ls /dev</code> and seeing what changed; it is likely to be called <code>/dev/ttyUSB0</code>
# Check your permissions; run <code>ls -l /dev/ttyUSB0</code> to see which groups have access to the dongle (probably <code>dialout</code> or <code>uucp</code>), and add your user to that group; remember you need to log out before group changes take effect
# Install [https://salsa.debian.org/minicom-team/minicom minicom] (or [https://askubuntu.com/q/40959 some other option], but the instructions below are written for <code>minicom</code>)
# In a terminal window, run <code>minicom -D /dev/ttyUSB0 -b 1500000</code> or run <code>minicom --setup</code> to specify these settings by default

Once the software is set up, power-cycle your PineNote; as the system boots you should see text appearing in your terminal window.
You can exit the session with <code>ctrl+a x</code> then pressing <code>Enter</code> to confirm.
Run <code>man minicom</code> for more details.

=== Sending commands ===

Pressing <code>ctrl+a</code> in <code>minicom</code> enables you to send keystrokes to your PineNote.
The most important of these is <code>ctrl+c</code>, which if sent during boot will put you in the U-Boot command prompt.
You can then type <code>help</code> to list possible commands.

=== Troubleshooting ===

If you don't see any text in your terminal as the PineNote boots, or the text is garbled, try the following:
* Ensure your GND, RX/TX, and CC jump wires are connected to the correct pins on both the USB-UART adapter and the USB-C breakout board
* Connect your USB-C breakout board to your PineNote in the opposite orientation
* Run <code>minicom</code> as sudo in case your user doesn't have appropriate permissions
* Ensure you are setting the baud rate to 1500000 (1.5 million), and (less importantly because these are probably used by default) 8 data bits, 1 stop bit, no parity and no flow control

If you can see text but are having trouble sending <code>ctrl+c</code> to the PineNote during boot:
* Be sure you're typing <code>ctrl+a</code> first, or whatever escape sequence your terminal emulator uses
* Send it right as the PineNote is booting, before the loading bar appears on screen
* Double-check your Y-shaped pull-up resistor cable; if this isn't working properly you'll probably be able to read text but not send text

== USB passthrough ==

If your USB-C breakout board has a passthrough/intercept design, you can connect to your PineNote over USB and UART at the same time.
This can be useful when you're doing development work on the PineNote boot process so you don't have to continually reconnect cables.
You'll need a USB-A to USB-C cable, connecting directly from your computer's USB-A hub to your USB-C breakout board's female USB-C port.
It's important to connect directly from USB-A, without any intermediate USB-C components.
Note that connecting a live USB cable to your USB-C breakout board in this way dramatically increases the danger of frying your PineNote with a short, so you should only do this if all connectors are safely wrapped in electrical tape.

[[Category:PineNote]]

PineNote Development/UART

2023-10-14T19:48:24Z

Ahelwer: /* Creating a dongle */ added note about debug accessory mode

[[File:Pinenote-uart-dongle.jpeg|thumb|Basic non-stock PineNote UART dongle]]

This page contains information on creating and using a [https://en.wikipedia.org/wiki/Universal_asynchronous_receiver-transmitter UART] dongle for the [[PineNote]].
The PineNote was shipped with a compatible UART dongle, but replacements are not available to order in case of loss or hardware fault.
Thankfully it is not difficult to make your own from easily-acquired components and a small bit of soldering.

Fear not if you've never soldered anything before!
This serves as an excellent first soldering project.
Borrow the tools from a friend, local hackerspace, or tool library.
Pine64 also makes [[Pinecil|a nice soldering iron]] themselves.

A PineNote UART dongle enables you to:
# Interact with the system boot menu
# Read system events in real time as the PineNote is used
# Fix the PineNote without opening the case if something goes wrong while [[PineNote Development/Flashing|flashing it]]

Since the PineNote is an embedded system, interfacing with it during boot is more complicated than with an ordinary computer.
The UART dongle enables you to do this.

The PineNote factory firmware runs UART at a baud rate of 1500000 bps, 8 data bits, 1 stop bit, no parity and no flow control.
The process by which the PineNote design was modified to include closed-case UART is documented [[PineNote/Hardware Changes/Closed Case UART|here]].

== Stock dongle ==

The stock UART dongle included with the PineNote was a simple device plugging directly into the PineNote's USB-C port.
The dongle exposed a female USB-C port, which the user plugged into to get UART access.
This design unfortunately ruled out passthrough USB connections, where the user connects to the PineNote via UART and USB simultaneously.
The dongle is not currently available for purchase.

<gallery>
Pinenote-stock-uart-dongle-front.jpg|Front
Pinenote-stock-uart-dongle-back.jpg|Back
</gallery>

== Creating a dongle ==

A typical self-built PineNote UART dongle design has the following components:
# A USB-C breakout board with a male connector exposing the 24 pins of the PineNote's USB-C port
# A USB-UART adapter, to plug into a USB port of the computer you'll use to interface with the PineNote
# [https://en.wikipedia.org/wiki/Jump_wire Jump wires] to connect specific breakout board pins to pins on the USB-UART adapter
# Two 1,000 Ohm through-hole resistors to splice into the jump wires
# Electrical tape or heat shrink to wrap connectors and prevent shorts

You will also need the following tools:
# Soldering iron with solder
# Wire cutters & strippers

The PineNote's internal UART system is documented in [https://files.pine64.org/doc/PineNote/PineNote_USB-C_Console_UART_breakout_board_schematic_v1.0_20210903.pdf this schematic].
The purpose of all 24 USB-C pins is documented [https://en.wikipedia.org/wiki/USB-C#Receptacles on the USB-C Wikipedia page].
We are interested in three sets of pins:
# The SBU1 (A8) and SBU2 (B8) side band use pins
# The CC1 (A5) and CC2 (B5) configuration channel pins
# The GND [https://en.wikipedia.org/wiki/Ground_(electricity) ground return] pins (A1, A12, B1, and B12)

In the PineNote UART schematic you can see (on the bottom right diagram labeled <code>USB_TYPEC_Male</code>) the side band pins are given the labels <code>UART2_TX_SUB1</code> for A8 and <code>UART2_RX_SUB2</code> for B8.
The first (TX) is used for transmitting data and the second (RX) is used for receiving data, from the perspective of the PineNote.
Also note the configuration channel pins labeled <code>TYPEC_CC1</code> for A5 and <code>TYPEC_CC2</code> for B5.
The diagram shows they must be connected to a 3.3V source in parallel, mediated by resistors.
Per the USB-C standard, when these pins are pulled high this indicates the device should enter [https://en.wikipedia.org/wiki/USB-C#Debug_Accessory_Mode Debug Accessory Mode]; connecting them to a voltage source & limiting the current with [https://www.electronics-tutorials.ws/logic/pull-up-resistor.html pull-up resistors] accomplishes this.
The schematic indicates 10,000 Ohm resistors, but community member Visti Andresen (talpadk) experimented and found 1,000 Ohm resistors work better.
Our mission is to wire up pins from a USB-UART adapter to a USB-C breakout board following these requirements.

=== Buying components ===

There are many possible USB-C breakout board designs available for purchase online.
One particularly useful design is a "passthrough" or "intercept" style, with both male and female USB-C ports.
This design is more versatile in case you want to reuse it in other projects, and also enables you to connect to the PineNote via UART and USB at the same time.
An example of this product can be found [https://pmdway.com/products/usb-3-1-type-c-male-to-female-breakout-test-board here], although you are encouraged to shop around for cheaper options.
If you're fine with a bit more soldering, there is a very cheap one [https://www.ebay.com/itm/275407037613 here].

Similarly, there are many USB-UART adapter designs available.
These devices plug into your computer and expose a number of pins themselves, connecting to specific pins on the breakout board with jump wires.
It is important to get a 3.3V model, or at least a model with the option of 3.3V, as a 5V source might fry the PineNote.
[https://pmdway.com/products/usb-to-ttl-serial-cp2104-6-pin-converter-module Here] is one example with jump wires included, although you are again encouraged to shop around for alternatives.

All other necessary components of our UART dongle are readily & cheaply available in many locations.

=== Splicing resistors ===

[[File:PineNote-UART-Y-pull-up-resistor-cable.jpg|thumb|The desired end result; wrap removed from resistors for illustration purposes.]]

This is the only difficult part of the whole process.
Your goal is to create a Y-shaped jump wire with 1,000 Ohm through-hole resistors spliced into each of the twin arms.
The solitary leg will connect to a 3.3V source on your USB-UART adapter.
The twin arms will connect to the configuration channel pins on your USB-C breakout board.
Per the USB-C standard, when these pins are pulled high this indicates the device should enter [https://en.wikipedia.org/wiki/USB-C#Debug_Accessory_Mode Debug Accessory Mode]; connecting them to a voltage source & limiting the current with [https://www.electronics-tutorials.ws/logic/pull-up-resistor.html pull-up resistors] accomplishes this.

For this project you'll need:
# A soldering iron with solder
# Wire cutters & strippers
# 2x jumper wires, male/female as compatible with your board designs
# 2x 1,000 Ohm through-hole resistors
# Electrical tape or heat shrink wrap

Consider buying extra jumper wires and resistors in case you mess up.
Also double-check that you have 1K resistors with [https://resistorcolorcodecalc.com/ this color code calculator].
Although the PineNote UART schematic says to use 10K Ohm resistors, community member Visti Andresen (talpadk) experimented and found 1K is more appropriate.
Assemble your Y-cable as follows:
# Graft one jump wire onto the other to form a Y shape using [https://www.youtube.com/watch?v=KpiEfuhPqew this] technique, ensuring solitary leg end is compatible with your USB-UART adapter
# Splice resistors into the twin arms using [https://www.youtube.com/watch?v=RMgMVqqjPZ0 this] technique
# Splice remaining jump wire onto the ends of the resistors, ensuring ends are compatible with your USB-C breakout board
# Cover all exposed wire & resistors with electrical tape or heat shrink wrap

=== Assembly ===

Once you have acquired all necessary components, assemble the UART dongle as follows:
# Connect a jump wire from the GND pin on the USB-UART adapter to any one of the four GND pins on the USB-C breakout board (A1, A12, B1, or B12)
# Connect a jump wire from the RXD pin on the USB-UART adapter to the <code>UART2_TX_SUB1</code> SBU1 pin on the USB-C breakout board (A8)
# Connect a jump wire from the TXD pin on the USB-UART adapter to the <code>UART2_RX_SUB2</code> SBU2 pin on the USB-C breakout board (B8)
# Connect your Y-shaped jump wire from the 3.3V source pin on the USB-UART adapter to the CC1 and CC2 pins on the USB-C breakout board (A5 and B5)
# Wrap all metal connectors in electrical tape or heat shrink to prevent accidental shorts

Be '''very certain''' of your connections for the 3.3V source and its cable, as there is a real risk of irreparably frying your PineNote if they're wrong!
Especially be sure you are connecting to a 3.3V source and not a 5V source.

Note that if you mix up the TX/RX pins, it will still work but the USB-C breakout board will just plug into the PineNote upside down.
You can therefore choose which orientation you want by swapping the TX/RX pin connections.
Experience shows that RX/TX-TX/RX connections will have the PineNote face down while connected, while RX/RX-TX/TX connections will put the PineNote face up.

== Using the dongle ==

First, use your UART dongle to physically connect your PineNote to your computer:
# Plug the USB-UART adapter into one of your computer's USB ports
# Plug the USB-C breakout board into the USB-C port on the bottom of your PineNote; the orientation matters, so try both and remember which one works

Once the hardware is connected, we need some program on your computer to communicate over that connection with 1500000 (1.5 million) bps, 8 data bits, 1 stop bit, no parity and no flow control.
Here's how you do that:
# Identify the USB-UART adapter in your <code>/dev</code> directory by running <code>ls /dev</code> with it plugged in, unplugging it, then again running <code>ls /dev</code> and seeing what changed; it is likely to be called <code>/dev/ttyUSB0</code>
# Check your permissions; run <code>ls -l /dev/ttyUSB0</code> to see which groups have access to the dongle (probably <code>dialout</code> or <code>uucp</code>), and add your user to that group; remember you need to log out before group changes take effect
# Install [https://www.gnu.org/software/screen/ minicom] (or [https://askubuntu.com/q/40959 some other option], but the instructions below are written for <code>minicom</code>)
# In a terminal window, run <code>minicom -D /dev/ttyUSB0 -b 1500000</code> or run <code>minicom --setup</code> to specify these settings by default

Once the software is set up, power-cycle your PineNote; as the system boots you should see text appearing in your terminal window.
You can exit the session with <code>ctrl+a x</code> then pressing <code>Enter</code> to confirm.
Run <code>man minicom</code> for more details.

=== Sending commands ===

Pressing <code>ctrl+a</code> in <code>minicom</code> enables you to send keystrokes to your PineNote.
The most important of these is <code>ctrl+c</code>, which if sent during boot will put you in the U-Boot command prompt.
You can then type <code>help</code> to list possible commands.

=== Troubleshooting ===

If you don't see any text in your terminal as the PineNote boots, or the text is garbled, try the following:
* Ensure your GND, RX/TX, and CC jump wires are connected to the correct pins on both the USB-UART adapter and the USB-C breakout board
* Connect your USB-C breakout board to your PineNote in the opposite orientation
* Run <code>minicom</code> as sudo in case your user doesn't have appropriate permissions
* Ensure you are setting the baud rate to 1500000 (1.5 million), and (less importantly because these are probably used by default) 8 data bits, 1 stop bit, no parity and no flow control

If you can see text but are having trouble sending <code>ctrl+c</code> to the PineNote during boot:
* Be sure you're typing <code>ctrl+a</code> first, or whatever escape sequence your terminal emulator uses
* Send it right as the PineNote is booting, before the loading bar appears on screen
* Double-check your Y-shaped pull-up resistor cable; if this isn't working properly you'll probably be able to read text but not send text

== USB passthrough ==

If your USB-C breakout board has a passthrough/intercept design, you can connect to your PineNote over USB and UART at the same time.
This can be useful when you're doing development work on the PineNote boot process so you don't have to continually reconnect cables.
You'll need a USB-A to USB-C cable, connecting directly from your computer's USB-A hub to your USB-C breakout board's female USB-C port.
It's important to connect directly from USB-A, without any intermediate USB-C components.
Note that connecting a live USB cable to your USB-C breakout board in this way dramatically increases the danger of frying your PineNote with a short, so you should only do this if all connectors are safely wrapped in electrical tape.

[[Category:PineNote]]

File:PineNote-UART-Y-pull-up-resistor-cable.jpg

2023-10-14T19:34:18Z

Ahelwer: Added to PineNote category

== Summary ==
Photo of a Y-shaped cable with resistors spliced into each of the twin arms.
== Licensing ==
{{CC0}}
[[Category:PineNote]]

PineNote Development/UART

2023-10-14T19:30:31Z

Ahelwer: /* Using the dongle */

[[File:Pinenote-uart-dongle.jpeg|thumb|Basic non-stock PineNote UART dongle]]

This page contains information on creating and using a [https://en.wikipedia.org/wiki/Universal_asynchronous_receiver-transmitter UART] dongle for the [[PineNote]].
The PineNote was shipped with a compatible UART dongle, but replacements are not available to order in case of loss or hardware fault.
Thankfully it is not difficult to make your own from easily-acquired components and a small bit of soldering.

Fear not if you've never soldered anything before!
This serves as an excellent first soldering project.
Borrow the tools from a friend, local hackerspace, or tool library.
Pine64 also makes [[Pinecil|a nice soldering iron]] themselves.

A PineNote UART dongle enables you to:
# Interact with the system boot menu
# Read system events in real time as the PineNote is used
# Fix the PineNote without opening the case if something goes wrong while [[PineNote Development/Flashing|flashing it]]

Since the PineNote is an embedded system, interfacing with it during boot is more complicated than with an ordinary computer.
The UART dongle enables you to do this.

The PineNote factory firmware runs UART at a baud rate of 1500000 bps, 8 data bits, 1 stop bit, no parity and no flow control.
The process by which the PineNote design was modified to include closed-case UART is documented [[PineNote/Hardware Changes/Closed Case UART|here]].

== Stock dongle ==

The stock UART dongle included with the PineNote was a simple device plugging directly into the PineNote's USB-C port.
The dongle exposed a female USB-C port, which the user plugged into to get UART access.
This design unfortunately ruled out passthrough USB connections, where the user connects to the PineNote via UART and USB simultaneously.
The dongle is not currently available for purchase.

<gallery>
Pinenote-stock-uart-dongle-front.jpg|Front
Pinenote-stock-uart-dongle-back.jpg|Back
</gallery>

== Creating a dongle ==

A typical self-built PineNote UART dongle design has the following components:
# A USB-C breakout board with a male connector exposing the 24 pins of the PineNote's USB-C port
# A USB-UART adapter, to plug into a USB port of the computer you'll use to interface with the PineNote
# [https://en.wikipedia.org/wiki/Jump_wire Jump wires] to connect specific breakout board pins to pins on the USB-UART adapter
# Two 1,000 Ohm through-hole resistors to splice into the jump wires
# Electrical tape or heat shrink to wrap connectors and prevent shorts

You will also need the following tools:
# Soldering iron with solder
# Wire cutters & strippers

The PineNote's internal UART system is documented in [https://files.pine64.org/doc/PineNote/PineNote_USB-C_Console_UART_breakout_board_schematic_v1.0_20210903.pdf this schematic].
The purpose of all 24 USB-C pins is documented [https://en.wikipedia.org/wiki/USB-C#Receptacles on the USB-C Wikipedia page].
We are interested in three sets of pins:
# The SBU1 (A8) and SBU2 (B8) side band use pins
# The CC1 (A5) and CC2 (B5) configuration channel pins
# The GND [https://en.wikipedia.org/wiki/Ground_(electricity) ground return] pins (A1, A12, B1, and B12)

In the PineNote UART schematic you can see (on the bottom right diagram labeled <code>USB_TYPEC_Male</code>) the side band pins are given the labels <code>UART2_TX_SUB1</code> for A8 and <code>UART2_RX_SUB2</code> for B8.
The first (TX) is used for transmitting data and the second (RX) is used for receiving data, from the perspective of the PineNote.
Also note the configuration channel pins labeled <code>TYPEC_CC1</code> for A5 and <code>TYPEC_CC2</code> for B5.
These pins are used to signal to the PineNote that a UART dongle is present.
The diagram shows they must be connected to a 3.3V source in parallel, mediated by resistors.
The schematic indicates 10,000 Ohm resistors, but community member Visti Andresen (talpadk) experimented and found 1,000 Ohm resistors work better.
Our mission is to wire up pins from a USB-UART adapter to a USB-C breakout board following these requirements.

=== Buying components ===

There are many possible USB-C breakout board designs available for purchase online.
One particularly useful design is a "passthrough" or "intercept" style, with both male and female USB-C ports.
This design is more versatile in case you want to reuse it in other projects, and also enables you to connect to the PineNote via UART and USB at the same time.
An example of this product can be found [https://pmdway.com/products/usb-3-1-type-c-male-to-female-breakout-test-board here], although you are encouraged to shop around for cheaper options.
If you're fine with a bit more soldering, there is a very cheap one [https://www.ebay.com/itm/275407037613 here].

Similarly, there are many USB-UART adapter designs available.
These devices plug into your computer and expose a number of pins themselves, connecting to specific pins on the breakout board with jump wires.
It is important to get a 3.3V model, or at least a model with the option of 3.3V, as a 5V source might fry the PineNote.
[https://pmdway.com/products/usb-to-ttl-serial-cp2104-6-pin-converter-module Here] is one example with jump wires included, although you are again encouraged to shop around for alternatives.

All other necessary components of our UART dongle are readily & cheaply available in many locations.

=== Splicing resistors ===

[[File:PineNote-UART-Y-pull-up-resistor-cable.jpg|thumb|The desired end result; wrap removed from resistors for illustration purposes.]]

This is the only difficult part of the whole process.
Your goal is to create a Y-shaped jump wire with 1,000 Ohm through-hole resistors spliced into each of the twin arms.
The solitary leg will connect to a 3.3V source on your USB-UART adapter.
The twin arms will connect to the configuration channel pins on your USB-C breakout board.
This setup is called using pull-up resistors, and you can read a nice introduction to their purpose [https://www.electronics-tutorials.ws/logic/pull-up-resistor.html here].

For this project you'll need:
# A soldering iron with solder
# Wire cutters & strippers
# 2x jumper wires, male/female as compatible with your board designs
# 2x 1,000 Ohm through-hole resistors
# Electrical tape or heat shrink wrap

Consider buying extra jumper wires and resistors in case you mess up.
Also double-check that you have 1K resistors with [https://resistorcolorcodecalc.com/ this color code calculator].
Although the PineNote UART schematic says to use 10K Ohm resistors, community member Visti Andresen (talpadk) experimented and found 1K is more appropriate.
Assemble your Y-cable as follows:
# Graft one jump wire onto the other to form a Y shape using [https://www.youtube.com/watch?v=KpiEfuhPqew this] technique, ensuring solitary leg end is compatible with your USB-UART adapter
# Splice resistors into the twin arms using [https://www.youtube.com/watch?v=RMgMVqqjPZ0 this] technique
# Splice remaining jump wire onto the ends of the resistors, ensuring ends are compatible with your USB-C breakout board
# Cover all exposed wire & resistors with electrical tape or heat shrink wrap

=== Assembly ===

Once you have acquired all necessary components, assemble the UART dongle as follows:
# Connect a jump wire from the GND pin on the USB-UART adapter to any one of the four GND pins on the USB-C breakout board (A1, A12, B1, or B12)
# Connect a jump wire from the RXD pin on the USB-UART adapter to the <code>UART2_TX_SUB1</code> SBU1 pin on the USB-C breakout board (A8)
# Connect a jump wire from the TXD pin on the USB-UART adapter to the <code>UART2_RX_SUB2</code> SBU2 pin on the USB-C breakout board (B8)
# Connect your Y-shaped jump wire from the 3.3V source pin on the USB-UART adapter to the CC1 and CC2 pins on the USB-C breakout board (A5 and B5)
# Wrap all metal connectors in electrical tape or heat shrink to prevent accidental shorts

Be '''very certain''' of your connections for the 3.3V source and its cable, as there is a real risk of irreparably frying your PineNote if they're wrong!
Especially be sure you are connecting to a 3.3V source and not a 5V source.

Note that if you mix up the TX/RX pins, it will still work but the USB-C breakout board will just plug into the PineNote upside down.
You can therefore choose which orientation you want by swapping the TX/RX pin connections.
Experience shows that RX/TX-TX/RX connections will have the PineNote face down while connected, while RX/RX-TX/TX connections will put the PineNote face up.

== Using the dongle ==

First, use your UART dongle to physically connect your PineNote to your computer:
# Plug the USB-UART adapter into one of your computer's USB ports
# Plug the USB-C breakout board into the USB-C port on the bottom of your PineNote; the orientation matters, so try both and remember which one works

Once the hardware is connected, we need some program on your computer to communicate over that connection with 1500000 (1.5 million) bps, 8 data bits, 1 stop bit, no parity and no flow control.
Here's how you do that:
# Identify the USB-UART adapter in your <code>/dev</code> directory by running <code>ls /dev</code> with it plugged in, unplugging it, then again running <code>ls /dev</code> and seeing what changed; it is likely to be called <code>/dev/ttyUSB0</code>
# Check your permissions; run <code>ls -l /dev/ttyUSB0</code> to see which groups have access to the dongle (probably <code>dialout</code> or <code>uucp</code>), and add your user to that group; remember you need to log out before group changes take effect
# Install [https://www.gnu.org/software/screen/ minicom] (or [https://askubuntu.com/q/40959 some other option], but the instructions below are written for <code>minicom</code>)
# In a terminal window, run <code>minicom -D /dev/ttyUSB0 -b 1500000</code> or run <code>minicom --setup</code> to specify these settings by default

Once the software is set up, power-cycle your PineNote; as the system boots you should see text appearing in your terminal window.
You can exit the session with <code>ctrl+a x</code> then pressing <code>Enter</code> to confirm.
Run <code>man minicom</code> for more details.

=== Sending commands ===

Pressing <code>ctrl+a</code> in <code>minicom</code> enables you to send keystrokes to your PineNote.
The most important of these is <code>ctrl+c</code>, which if sent during boot will put you in the U-Boot command prompt.
You can then type <code>help</code> to list possible commands.

=== Troubleshooting ===

If you don't see any text in your terminal as the PineNote boots, or the text is garbled, try the following:
* Ensure your GND, RX/TX, and CC jump wires are connected to the correct pins on both the USB-UART adapter and the USB-C breakout board
* Connect your USB-C breakout board to your PineNote in the opposite orientation
* Run <code>minicom</code> as sudo in case your user doesn't have appropriate permissions
* Ensure you are setting the baud rate to 1500000 (1.5 million), and (less importantly because these are probably used by default) 8 data bits, 1 stop bit, no parity and no flow control

If you can see text but are having trouble sending <code>ctrl+c</code> to the PineNote during boot:
* Be sure you're typing <code>ctrl+a</code> first, or whatever escape sequence your terminal emulator uses
* Send it right as the PineNote is booting, before the loading bar appears on screen
* Double-check your Y-shaped pull-up resistor cable; if this isn't working properly you'll probably be able to read text but not send text

== USB passthrough ==

If your USB-C breakout board has a passthrough/intercept design, you can connect to your PineNote over USB and UART at the same time.
This can be useful when you're doing development work on the PineNote boot process so you don't have to continually reconnect cables.
You'll need a USB-A to USB-C cable, connecting directly from your computer's USB-A hub to your USB-C breakout board's female USB-C port.
It's important to connect directly from USB-A, without any intermediate USB-C components.
Note that connecting a live USB cable to your USB-C breakout board in this way dramatically increases the danger of frying your PineNote with a short, so you should only do this if all connectors are safely wrapped in electrical tape.

[[Category:PineNote]]

PineNote Development/UART

2023-10-14T19:29:38Z

Ahelwer: /* Using the dongle */

[[File:Pinenote-uart-dongle.jpeg|thumb|Basic non-stock PineNote UART dongle]]

This page contains information on creating and using a [https://en.wikipedia.org/wiki/Universal_asynchronous_receiver-transmitter UART] dongle for the [[PineNote]].
The PineNote was shipped with a compatible UART dongle, but replacements are not available to order in case of loss or hardware fault.
Thankfully it is not difficult to make your own from easily-acquired components and a small bit of soldering.

Fear not if you've never soldered anything before!
This serves as an excellent first soldering project.
Borrow the tools from a friend, local hackerspace, or tool library.
Pine64 also makes [[Pinecil|a nice soldering iron]] themselves.

A PineNote UART dongle enables you to:
# Interact with the system boot menu
# Read system events in real time as the PineNote is used
# Fix the PineNote without opening the case if something goes wrong while [[PineNote Development/Flashing|flashing it]]

Since the PineNote is an embedded system, interfacing with it during boot is more complicated than with an ordinary computer.
The UART dongle enables you to do this.

The PineNote factory firmware runs UART at a baud rate of 1500000 bps, 8 data bits, 1 stop bit, no parity and no flow control.
The process by which the PineNote design was modified to include closed-case UART is documented [[PineNote/Hardware Changes/Closed Case UART|here]].

== Stock dongle ==

The stock UART dongle included with the PineNote was a simple device plugging directly into the PineNote's USB-C port.
The dongle exposed a female USB-C port, which the user plugged into to get UART access.
This design unfortunately ruled out passthrough USB connections, where the user connects to the PineNote via UART and USB simultaneously.
The dongle is not currently available for purchase.

<gallery>
Pinenote-stock-uart-dongle-front.jpg|Front
Pinenote-stock-uart-dongle-back.jpg|Back
</gallery>

== Creating a dongle ==

A typical self-built PineNote UART dongle design has the following components:
# A USB-C breakout board with a male connector exposing the 24 pins of the PineNote's USB-C port
# A USB-UART adapter, to plug into a USB port of the computer you'll use to interface with the PineNote
# [https://en.wikipedia.org/wiki/Jump_wire Jump wires] to connect specific breakout board pins to pins on the USB-UART adapter
# Two 1,000 Ohm through-hole resistors to splice into the jump wires
# Electrical tape or heat shrink to wrap connectors and prevent shorts

You will also need the following tools:
# Soldering iron with solder
# Wire cutters & strippers

The PineNote's internal UART system is documented in [https://files.pine64.org/doc/PineNote/PineNote_USB-C_Console_UART_breakout_board_schematic_v1.0_20210903.pdf this schematic].
The purpose of all 24 USB-C pins is documented [https://en.wikipedia.org/wiki/USB-C#Receptacles on the USB-C Wikipedia page].
We are interested in three sets of pins:
# The SBU1 (A8) and SBU2 (B8) side band use pins
# The CC1 (A5) and CC2 (B5) configuration channel pins
# The GND [https://en.wikipedia.org/wiki/Ground_(electricity) ground return] pins (A1, A12, B1, and B12)

In the PineNote UART schematic you can see (on the bottom right diagram labeled <code>USB_TYPEC_Male</code>) the side band pins are given the labels <code>UART2_TX_SUB1</code> for A8 and <code>UART2_RX_SUB2</code> for B8.
The first (TX) is used for transmitting data and the second (RX) is used for receiving data, from the perspective of the PineNote.
Also note the configuration channel pins labeled <code>TYPEC_CC1</code> for A5 and <code>TYPEC_CC2</code> for B5.
These pins are used to signal to the PineNote that a UART dongle is present.
The diagram shows they must be connected to a 3.3V source in parallel, mediated by resistors.
The schematic indicates 10,000 Ohm resistors, but community member Visti Andresen (talpadk) experimented and found 1,000 Ohm resistors work better.
Our mission is to wire up pins from a USB-UART adapter to a USB-C breakout board following these requirements.

=== Buying components ===

There are many possible USB-C breakout board designs available for purchase online.
One particularly useful design is a "passthrough" or "intercept" style, with both male and female USB-C ports.
This design is more versatile in case you want to reuse it in other projects, and also enables you to connect to the PineNote via UART and USB at the same time.
An example of this product can be found [https://pmdway.com/products/usb-3-1-type-c-male-to-female-breakout-test-board here], although you are encouraged to shop around for cheaper options.
If you're fine with a bit more soldering, there is a very cheap one [https://www.ebay.com/itm/275407037613 here].

Similarly, there are many USB-UART adapter designs available.
These devices plug into your computer and expose a number of pins themselves, connecting to specific pins on the breakout board with jump wires.
It is important to get a 3.3V model, or at least a model with the option of 3.3V, as a 5V source might fry the PineNote.
[https://pmdway.com/products/usb-to-ttl-serial-cp2104-6-pin-converter-module Here] is one example with jump wires included, although you are again encouraged to shop around for alternatives.

All other necessary components of our UART dongle are readily & cheaply available in many locations.

=== Splicing resistors ===

[[File:PineNote-UART-Y-pull-up-resistor-cable.jpg|thumb|The desired end result; wrap removed from resistors for illustration purposes.]]

This is the only difficult part of the whole process.
Your goal is to create a Y-shaped jump wire with 1,000 Ohm through-hole resistors spliced into each of the twin arms.
The solitary leg will connect to a 3.3V source on your USB-UART adapter.
The twin arms will connect to the configuration channel pins on your USB-C breakout board.
This setup is called using pull-up resistors, and you can read a nice introduction to their purpose [https://www.electronics-tutorials.ws/logic/pull-up-resistor.html here].

For this project you'll need:
# A soldering iron with solder
# Wire cutters & strippers
# 2x jumper wires, male/female as compatible with your board designs
# 2x 1,000 Ohm through-hole resistors
# Electrical tape or heat shrink wrap

Consider buying extra jumper wires and resistors in case you mess up.
Also double-check that you have 1K resistors with [https://resistorcolorcodecalc.com/ this color code calculator].
Although the PineNote UART schematic says to use 10K Ohm resistors, community member Visti Andresen (talpadk) experimented and found 1K is more appropriate.
Assemble your Y-cable as follows:
# Graft one jump wire onto the other to form a Y shape using [https://www.youtube.com/watch?v=KpiEfuhPqew this] technique, ensuring solitary leg end is compatible with your USB-UART adapter
# Splice resistors into the twin arms using [https://www.youtube.com/watch?v=RMgMVqqjPZ0 this] technique
# Splice remaining jump wire onto the ends of the resistors, ensuring ends are compatible with your USB-C breakout board
# Cover all exposed wire & resistors with electrical tape or heat shrink wrap

=== Assembly ===

Once you have acquired all necessary components, assemble the UART dongle as follows:
# Connect a jump wire from the GND pin on the USB-UART adapter to any one of the four GND pins on the USB-C breakout board (A1, A12, B1, or B12)
# Connect a jump wire from the RXD pin on the USB-UART adapter to the <code>UART2_TX_SUB1</code> SBU1 pin on the USB-C breakout board (A8)
# Connect a jump wire from the TXD pin on the USB-UART adapter to the <code>UART2_RX_SUB2</code> SBU2 pin on the USB-C breakout board (B8)
# Connect your Y-shaped jump wire from the 3.3V source pin on the USB-UART adapter to the CC1 and CC2 pins on the USB-C breakout board (A5 and B5)
# Wrap all metal connectors in electrical tape or heat shrink to prevent accidental shorts

Be '''very certain''' of your connections for the 3.3V source and its cable, as there is a real risk of irreparably frying your PineNote if they're wrong!
Especially be sure you are connecting to a 3.3V source and not a 5V source.

Note that if you mix up the TX/RX pins, it will still work but the USB-C breakout board will just plug into the PineNote upside down.
You can therefore choose which orientation you want by swapping the TX/RX pin connections.
Experience shows that RX/TX-TX/RX connections will have the PineNote face down while connected, while RX/RX-TX/TX connections will put the PineNote face up.

== Using the dongle ==

First, use your UART dongle to physically connect your PineNote to your computer:
# Plug the USB-UART adapter into one of your computer's USB ports
# Plug the USB-C breakout board into the USB-C port on the bottom of your PineNote; the orientation matters, so try both and remember which one works

Once the hardware is connected, we need to get some program on your computer to communicate over that connection with 1500000 (1.5 million) bps, 8 data bits, 1 stop bit, no parity and no flow control.
Here's how you do that:
# Identify the USB-UART adapter in your <code>/dev</code> directory by running <code>ls /dev</code> with it plugged in, unplugging it, then again running <code>ls /dev</code> and seeing what changed; it is likely to be called <code>/dev/ttyUSB0</code>
# Check your permissions; run <code>ls -l /dev/ttyUSB0</code> to see which groups have access to the dongle (probably <code>dialout</code> or <code>uucp</code>), and add your user to that group; remember you need to log out before group changes take effect
# Install [https://www.gnu.org/software/screen/ minicom] (or [https://askubuntu.com/q/40959 some other option], but the instructions below are written for <code>minicom</code>)
# In a terminal window, run <code>minicom -D /dev/ttyUSB0 -b 1500000</code> or run <code>minicom --setup</code> to specify these settings by default

Once the software is set up, power-cycle your PineNote; as the system boots you should see text appearing in your terminal window.
You can exit the session with <code>ctrl+a x</code> then pressing <code>Enter</code> to confirm.
Run <code>man minicom</code> for more details.

=== Sending commands ===

Pressing <code>ctrl+a</code> in <code>minicom</code> enables you to send keystrokes to your PineNote.
The most important of these is <code>ctrl+c</code>, which if sent during boot will put you in the U-Boot command prompt.
You can then type <code>help</code> to list possible commands.

=== Troubleshooting ===

If you don't see any text in your terminal as the PineNote boots, or the text is garbled, try the following:
* Ensure your GND, RX/TX, and CC jump wires are connected to the correct pins on both the USB-UART adapter and the USB-C breakout board
* Connect your USB-C breakout board to your PineNote in the opposite orientation
* Run <code>minicom</code> as sudo in case your user doesn't have appropriate permissions
* Ensure you are setting the baud rate to 1500000 (1.5 million), and (less importantly because these are probably used by default) 8 data bits, 1 stop bit, no parity and no flow control

If you can see text but are having trouble sending <code>ctrl+c</code> to the PineNote during boot:
* Be sure you're typing <code>ctrl+a</code> first, or whatever escape sequence your terminal emulator uses
* Send it right as the PineNote is booting, before the loading bar appears on screen
* Double-check your Y-shaped pull-up resistor cable; if this isn't working properly you'll probably be able to read text but not send text

== USB passthrough ==

If your USB-C breakout board has a passthrough/intercept design, you can connect to your PineNote over USB and UART at the same time.
This can be useful when you're doing development work on the PineNote boot process so you don't have to continually reconnect cables.
You'll need a USB-A to USB-C cable, connecting directly from your computer's USB-A hub to your USB-C breakout board's female USB-C port.
It's important to connect directly from USB-A, without any intermediate USB-C components.
Note that connecting a live USB cable to your USB-C breakout board in this way dramatically increases the danger of frying your PineNote with a short, so you should only do this if all connectors are safely wrapped in electrical tape.

[[Category:PineNote]]

PineNote Development/UART

2023-10-14T19:29:07Z

Ahelwer: /* Using the dongle */

[[File:Pinenote-uart-dongle.jpeg|thumb|Basic non-stock PineNote UART dongle]]

This page contains information on creating and using a [https://en.wikipedia.org/wiki/Universal_asynchronous_receiver-transmitter UART] dongle for the [[PineNote]].
The PineNote was shipped with a compatible UART dongle, but replacements are not available to order in case of loss or hardware fault.
Thankfully it is not difficult to make your own from easily-acquired components and a small bit of soldering.

Fear not if you've never soldered anything before!
This serves as an excellent first soldering project.
Borrow the tools from a friend, local hackerspace, or tool library.
Pine64 also makes [[Pinecil|a nice soldering iron]] themselves.

A PineNote UART dongle enables you to:
# Interact with the system boot menu
# Read system events in real time as the PineNote is used
# Fix the PineNote without opening the case if something goes wrong while [[PineNote Development/Flashing|flashing it]]

Since the PineNote is an embedded system, interfacing with it during boot is more complicated than with an ordinary computer.
The UART dongle enables you to do this.

The PineNote factory firmware runs UART at a baud rate of 1500000 bps, 8 data bits, 1 stop bit, no parity and no flow control.
The process by which the PineNote design was modified to include closed-case UART is documented [[PineNote/Hardware Changes/Closed Case UART|here]].

== Stock dongle ==

The stock UART dongle included with the PineNote was a simple device plugging directly into the PineNote's USB-C port.
The dongle exposed a female USB-C port, which the user plugged into to get UART access.
This design unfortunately ruled out passthrough USB connections, where the user connects to the PineNote via UART and USB simultaneously.
The dongle is not currently available for purchase.

<gallery>
Pinenote-stock-uart-dongle-front.jpg|Front
Pinenote-stock-uart-dongle-back.jpg|Back
</gallery>

== Creating a dongle ==

A typical self-built PineNote UART dongle design has the following components:
# A USB-C breakout board with a male connector exposing the 24 pins of the PineNote's USB-C port
# A USB-UART adapter, to plug into a USB port of the computer you'll use to interface with the PineNote
# [https://en.wikipedia.org/wiki/Jump_wire Jump wires] to connect specific breakout board pins to pins on the USB-UART adapter
# Two 1,000 Ohm through-hole resistors to splice into the jump wires
# Electrical tape or heat shrink to wrap connectors and prevent shorts

You will also need the following tools:
# Soldering iron with solder
# Wire cutters & strippers

The PineNote's internal UART system is documented in [https://files.pine64.org/doc/PineNote/PineNote_USB-C_Console_UART_breakout_board_schematic_v1.0_20210903.pdf this schematic].
The purpose of all 24 USB-C pins is documented [https://en.wikipedia.org/wiki/USB-C#Receptacles on the USB-C Wikipedia page].
We are interested in three sets of pins:
# The SBU1 (A8) and SBU2 (B8) side band use pins
# The CC1 (A5) and CC2 (B5) configuration channel pins
# The GND [https://en.wikipedia.org/wiki/Ground_(electricity) ground return] pins (A1, A12, B1, and B12)

In the PineNote UART schematic you can see (on the bottom right diagram labeled <code>USB_TYPEC_Male</code>) the side band pins are given the labels <code>UART2_TX_SUB1</code> for A8 and <code>UART2_RX_SUB2</code> for B8.
The first (TX) is used for transmitting data and the second (RX) is used for receiving data, from the perspective of the PineNote.
Also note the configuration channel pins labeled <code>TYPEC_CC1</code> for A5 and <code>TYPEC_CC2</code> for B5.
These pins are used to signal to the PineNote that a UART dongle is present.
The diagram shows they must be connected to a 3.3V source in parallel, mediated by resistors.
The schematic indicates 10,000 Ohm resistors, but community member Visti Andresen (talpadk) experimented and found 1,000 Ohm resistors work better.
Our mission is to wire up pins from a USB-UART adapter to a USB-C breakout board following these requirements.

=== Buying components ===

There are many possible USB-C breakout board designs available for purchase online.
One particularly useful design is a "passthrough" or "intercept" style, with both male and female USB-C ports.
This design is more versatile in case you want to reuse it in other projects, and also enables you to connect to the PineNote via UART and USB at the same time.
An example of this product can be found [https://pmdway.com/products/usb-3-1-type-c-male-to-female-breakout-test-board here], although you are encouraged to shop around for cheaper options.
If you're fine with a bit more soldering, there is a very cheap one [https://www.ebay.com/itm/275407037613 here].

Similarly, there are many USB-UART adapter designs available.
These devices plug into your computer and expose a number of pins themselves, connecting to specific pins on the breakout board with jump wires.
It is important to get a 3.3V model, or at least a model with the option of 3.3V, as a 5V source might fry the PineNote.
[https://pmdway.com/products/usb-to-ttl-serial-cp2104-6-pin-converter-module Here] is one example with jump wires included, although you are again encouraged to shop around for alternatives.

All other necessary components of our UART dongle are readily & cheaply available in many locations.

=== Splicing resistors ===

[[File:PineNote-UART-Y-pull-up-resistor-cable.jpg|thumb|The desired end result; wrap removed from resistors for illustration purposes.]]

This is the only difficult part of the whole process.
Your goal is to create a Y-shaped jump wire with 1,000 Ohm through-hole resistors spliced into each of the twin arms.
The solitary leg will connect to a 3.3V source on your USB-UART adapter.
The twin arms will connect to the configuration channel pins on your USB-C breakout board.
This setup is called using pull-up resistors, and you can read a nice introduction to their purpose [https://www.electronics-tutorials.ws/logic/pull-up-resistor.html here].

For this project you'll need:
# A soldering iron with solder
# Wire cutters & strippers
# 2x jumper wires, male/female as compatible with your board designs
# 2x 1,000 Ohm through-hole resistors
# Electrical tape or heat shrink wrap

Consider buying extra jumper wires and resistors in case you mess up.
Also double-check that you have 1K resistors with [https://resistorcolorcodecalc.com/ this color code calculator].
Although the PineNote UART schematic says to use 10K Ohm resistors, community member Visti Andresen (talpadk) experimented and found 1K is more appropriate.
Assemble your Y-cable as follows:
# Graft one jump wire onto the other to form a Y shape using [https://www.youtube.com/watch?v=KpiEfuhPqew this] technique, ensuring solitary leg end is compatible with your USB-UART adapter
# Splice resistors into the twin arms using [https://www.youtube.com/watch?v=RMgMVqqjPZ0 this] technique
# Splice remaining jump wire onto the ends of the resistors, ensuring ends are compatible with your USB-C breakout board
# Cover all exposed wire & resistors with electrical tape or heat shrink wrap

=== Assembly ===

Once you have acquired all necessary components, assemble the UART dongle as follows:
# Connect a jump wire from the GND pin on the USB-UART adapter to any one of the four GND pins on the USB-C breakout board (A1, A12, B1, or B12)
# Connect a jump wire from the RXD pin on the USB-UART adapter to the <code>UART2_TX_SUB1</code> SBU1 pin on the USB-C breakout board (A8)
# Connect a jump wire from the TXD pin on the USB-UART adapter to the <code>UART2_RX_SUB2</code> SBU2 pin on the USB-C breakout board (B8)
# Connect your Y-shaped jump wire from the 3.3V source pin on the USB-UART adapter to the CC1 and CC2 pins on the USB-C breakout board (A5 and B5)
# Wrap all metal connectors in electrical tape or heat shrink to prevent accidental shorts

Be '''very certain''' of your connections for the 3.3V source and its cable, as there is a real risk of irreparably frying your PineNote if they're wrong!
Especially be sure you are connecting to a 3.3V source and not a 5V source.

Note that if you mix up the TX/RX pins, it will still work but the USB-C breakout board will just plug into the PineNote upside down.
You can therefore choose which orientation you want by swapping the TX/RX pin connections.
Experience shows that RX/TX-TX/RX connections will have the PineNote face down while connected, while RX/RX-TX/TX connections will put the PineNote face up.

== Using the dongle ==

First, use your UART dongle to physically connect your PineNote to your computer:
# Plug the USB-UART adapter into one of your computer's USB ports
# Plug the USB-C breakout board into the USB-C port on the bottom of your PineNote; the orientation matters, so try both and remember which one works

Once the hardware is connected, we need to get some program to communicate over UART with 1500000 (1.5 million) bps, 8 data bits, 1 stop bit, no parity and no flow control.
Here's how you do that:
# Identify the USB-UART adapter in your <code>/dev</code> directory by running <code>ls /dev</code> with it plugged in, unplugging it, then again running <code>ls /dev</code> and seeing what changed; it is likely to be called <code>/dev/ttyUSB0</code>
# Check your permissions; run <code>ls -l /dev/ttyUSB0</code> to see which groups have access to the dongle (probably <code>dialout</code> or <code>uucp</code>), and add your user to that group; remember you need to log out before group changes take effect
# Install [https://www.gnu.org/software/screen/ minicom] (or [https://askubuntu.com/q/40959 some other option], but the instructions below are written for <code>minicom</code>)
# In a terminal window, run <code>minicom -D /dev/ttyUSB0 -b 1500000</code> or run <code>minicom --setup</code> to specify these settings by default

Once the software is set up, power-cycle your PineNote; as the system boots you should see text appearing in your terminal window.
You can exit the session with <code>ctrl+a x</code> then pressing <code>Enter</code> to confirm.
Run <code>man minicom</code> for more details.

=== Sending commands ===

Pressing <code>ctrl+a</code> in <code>minicom</code> enables you to send keystrokes to your PineNote.
The most important of these is <code>ctrl+c</code>, which if sent during boot will put you in the U-Boot command prompt.
You can then type <code>help</code> to list possible commands.

=== Troubleshooting ===

If you don't see any text in your terminal as the PineNote boots, or the text is garbled, try the following:
* Ensure your GND, RX/TX, and CC jump wires are connected to the correct pins on both the USB-UART adapter and the USB-C breakout board
* Connect your USB-C breakout board to your PineNote in the opposite orientation
* Run <code>minicom</code> as sudo in case your user doesn't have appropriate permissions
* Ensure you are setting the baud rate to 1500000 (1.5 million), and (less importantly because these are probably used by default) 8 data bits, 1 stop bit, no parity and no flow control

If you can see text but are having trouble sending <code>ctrl+c</code> to the PineNote during boot:
* Be sure you're typing <code>ctrl+a</code> first, or whatever escape sequence your terminal emulator uses
* Send it right as the PineNote is booting, before the loading bar appears on screen
* Double-check your Y-shaped pull-up resistor cable; if this isn't working properly you'll probably be able to read text but not send text

== USB passthrough ==

If your USB-C breakout board has a passthrough/intercept design, you can connect to your PineNote over USB and UART at the same time.
This can be useful when you're doing development work on the PineNote boot process so you don't have to continually reconnect cables.
You'll need a USB-A to USB-C cable, connecting directly from your computer's USB-A hub to your USB-C breakout board's female USB-C port.
It's important to connect directly from USB-A, without any intermediate USB-C components.
Note that connecting a live USB cable to your USB-C breakout board in this way dramatically increases the danger of frying your PineNote with a short, so you should only do this if all connectors are safely wrapped in electrical tape.

[[Category:PineNote]]

PineNote Development/UART

2023-10-14T14:07:53Z

Ahelwer: /* Troubleshooting */ added note about data settings in UART

[[File:Pinenote-uart-dongle.jpeg|thumb|Basic non-stock PineNote UART dongle]]

This page contains information on creating and using a [https://en.wikipedia.org/wiki/Universal_asynchronous_receiver-transmitter UART] dongle for the [[PineNote]].
The PineNote was shipped with a compatible UART dongle, but replacements are not available to order in case of loss or hardware fault.
Thankfully it is not difficult to make your own from easily-acquired components and a small bit of soldering.

Fear not if you've never soldered anything before!
This serves as an excellent first soldering project.
Borrow the tools from a friend, local hackerspace, or tool library.
Pine64 also makes [[Pinecil|a nice soldering iron]] themselves.

A PineNote UART dongle enables you to:
# Interact with the system boot menu
# Read system events in real time as the PineNote is used
# Fix the PineNote without opening the case if something goes wrong while [[PineNote Development/Flashing|flashing it]]

Since the PineNote is an embedded system, interfacing with it during boot is more complicated than with an ordinary computer.
The UART dongle enables you to do this.

The PineNote factory firmware runs UART at a baud rate of 1500000 bps, 8 data bits, 1 stop bit, no parity and no flow control.
The process by which the PineNote design was modified to include closed-case UART is documented [[PineNote/Hardware Changes/Closed Case UART|here]].

== Stock dongle ==

The stock UART dongle included with the PineNote was a simple device plugging directly into the PineNote's USB-C port.
The dongle exposed a female USB-C port, which the user plugged into to get UART access.
This design unfortunately ruled out passthrough USB connections, where the user connects to the PineNote via UART and USB simultaneously.
The dongle is not currently available for purchase.

<gallery>
Pinenote-stock-uart-dongle-front.jpg|Front
Pinenote-stock-uart-dongle-back.jpg|Back
</gallery>

== Creating a dongle ==

A typical self-built PineNote UART dongle design has the following components:
# A USB-C breakout board with a male connector exposing the 24 pins of the PineNote's USB-C port
# A USB-UART adapter, to plug into a USB port of the computer you'll use to interface with the PineNote
# [https://en.wikipedia.org/wiki/Jump_wire Jump wires] to connect specific breakout board pins to pins on the USB-UART adapter
# Two 1,000 Ohm through-hole resistors to splice into the jump wires
# Electrical tape or heat shrink to wrap connectors and prevent shorts

You will also need the following tools:
# Soldering iron with solder
# Wire cutters & strippers

The PineNote's internal UART system is documented in [https://files.pine64.org/doc/PineNote/PineNote_USB-C_Console_UART_breakout_board_schematic_v1.0_20210903.pdf this schematic].
The purpose of all 24 USB-C pins is documented [https://en.wikipedia.org/wiki/USB-C#Receptacles on the USB-C Wikipedia page].
We are interested in three sets of pins:
# The SBU1 (A8) and SBU2 (B8) side band use pins
# The CC1 (A5) and CC2 (B5) configuration channel pins
# The GND [https://en.wikipedia.org/wiki/Ground_(electricity) ground return] pins (A1, A12, B1, and B12)

In the PineNote UART schematic you can see (on the bottom right diagram labeled <code>USB_TYPEC_Male</code>) the side band pins are given the labels <code>UART2_TX_SUB1</code> for A8 and <code>UART2_RX_SUB2</code> for B8.
The first (TX) is used for transmitting data and the second (RX) is used for receiving data, from the perspective of the PineNote.
Also note the configuration channel pins labeled <code>TYPEC_CC1</code> for A5 and <code>TYPEC_CC2</code> for B5.
These pins are used to signal to the PineNote that a UART dongle is present.
The diagram shows they must be connected to a 3.3V source in parallel, mediated by resistors.
The schematic indicates 10,000 Ohm resistors, but community member Visti Andresen (talpadk) experimented and found 1,000 Ohm resistors work better.
Our mission is to wire up pins from a USB-UART adapter to a USB-C breakout board following these requirements.

=== Buying components ===

There are many possible USB-C breakout board designs available for purchase online.
One particularly useful design is a "passthrough" or "intercept" style, with both male and female USB-C ports.
This design is more versatile in case you want to reuse it in other projects, and also enables you to connect to the PineNote via UART and USB at the same time.
An example of this product can be found [https://pmdway.com/products/usb-3-1-type-c-male-to-female-breakout-test-board here], although you are encouraged to shop around for cheaper options.
If you're fine with a bit more soldering, there is a very cheap one [https://www.ebay.com/itm/275407037613 here].

Similarly, there are many USB-UART adapter designs available.
These devices plug into your computer and expose a number of pins themselves, connecting to specific pins on the breakout board with jump wires.
It is important to get a 3.3V model, or at least a model with the option of 3.3V, as a 5V source might fry the PineNote.
[https://pmdway.com/products/usb-to-ttl-serial-cp2104-6-pin-converter-module Here] is one example with jump wires included, although you are again encouraged to shop around for alternatives.

All other necessary components of our UART dongle are readily & cheaply available in many locations.

=== Splicing resistors ===

[[File:PineNote-UART-Y-pull-up-resistor-cable.jpg|thumb|The desired end result; wrap removed from resistors for illustration purposes.]]

This is the only difficult part of the whole process.
Your goal is to create a Y-shaped jump wire with 1,000 Ohm through-hole resistors spliced into each of the twin arms.
The solitary leg will connect to a 3.3V source on your USB-UART adapter.
The twin arms will connect to the configuration channel pins on your USB-C breakout board.
This setup is called using pull-up resistors, and you can read a nice introduction to their purpose [https://www.electronics-tutorials.ws/logic/pull-up-resistor.html here].

For this project you'll need:
# A soldering iron with solder
# Wire cutters & strippers
# 2x jumper wires, male/female as compatible with your board designs
# 2x 1,000 Ohm through-hole resistors
# Electrical tape or heat shrink wrap

Consider buying extra jumper wires and resistors in case you mess up.
Also double-check that you have 1K resistors with [https://resistorcolorcodecalc.com/ this color code calculator].
Although the PineNote UART schematic says to use 10K Ohm resistors, community member Visti Andresen (talpadk) experimented and found 1K is more appropriate.
Assemble your Y-cable as follows:
# Graft one jump wire onto the other to form a Y shape using [https://www.youtube.com/watch?v=KpiEfuhPqew this] technique, ensuring solitary leg end is compatible with your USB-UART adapter
# Splice resistors into the twin arms using [https://www.youtube.com/watch?v=RMgMVqqjPZ0 this] technique
# Splice remaining jump wire onto the ends of the resistors, ensuring ends are compatible with your USB-C breakout board
# Cover all exposed wire & resistors with electrical tape or heat shrink wrap

=== Assembly ===

Once you have acquired all necessary components, assemble the UART dongle as follows:
# Connect a jump wire from the GND pin on the USB-UART adapter to any one of the four GND pins on the USB-C breakout board (A1, A12, B1, or B12)
# Connect a jump wire from the RXD pin on the USB-UART adapter to the <code>UART2_TX_SUB1</code> SBU1 pin on the USB-C breakout board (A8)
# Connect a jump wire from the TXD pin on the USB-UART adapter to the <code>UART2_RX_SUB2</code> SBU2 pin on the USB-C breakout board (B8)
# Connect your Y-shaped jump wire from the 3.3V source pin on the USB-UART adapter to the CC1 and CC2 pins on the USB-C breakout board (A5 and B5)
# Wrap all metal connectors in electrical tape or heat shrink to prevent accidental shorts

Be '''very certain''' of your connections for the 3.3V source and its cable, as there is a real risk of irreparably frying your PineNote if they're wrong!
Especially be sure you are connecting to a 3.3V source and not a 5V source.

Note that if you mix up the TX/RX pins, it will still work but the USB-C breakout board will just plug into the PineNote upside down.
You can therefore choose which orientation you want by swapping the TX/RX pin connections.
Experience shows that RX/TX-TX/RX connections will have the PineNote face down while connected, while RX/RX-TX/TX connections will put the PineNote face up.

== Using the dongle ==

First, use your UART dongle to physically connect your PineNote to your computer:
# Plug the USB-UART adapter into one of your computer's USB ports
# Plug the USB-C breakout board into the USB-C port on the bottom of your PineNote; the orientation matters, so try both and remember which one works

Once the hardware is connected, set up your computer's software as follows:
# Identify the USB-UART adapter in your <code>/dev</code> directory by running <code>ls /dev</code> with it plugged in, unplugging it, then again running <code>ls /dev</code> and seeing what changed; it is likely to be called <code>/dev/ttyUSB0</code>
# Check your permissions; run <code>ls -l /dev/ttyUSB0</code> to see which groups have access to the dongle (probably <code>dialout</code> or <code>uucp</code>), and add your user to that group; remember you need to log out before group changes take effect
# Install [https://www.gnu.org/software/screen/ minicom] (or [https://askubuntu.com/q/40959 some other option], but the instructions below are written for <code>minicom</code>)
# In a terminal window, run <code>minicom -D /dev/ttyUSB0 -b 1500000</code> or run <code>minicom --setup</code> to specify these settings by default

Once the software is set up, power-cycle your PineNote; as the system boots you should see text appearing in your terminal window.
You can exit the session with <code>ctrl+a x</code> then pressing <code>Enter</code> to confirm.
Run <code>man minicom</code> for more details.

=== Sending commands ===

Pressing <code>ctrl+a</code> in <code>minicom</code> enables you to send keystrokes to your PineNote.
The most important of these is <code>ctrl+c</code>, which if sent during boot will put you in the U-Boot command prompt.
You can then type <code>help</code> to list possible commands.

=== Troubleshooting ===

If you don't see any text in your terminal as the PineNote boots, or the text is garbled, try the following:
* Ensure your GND, RX/TX, and CC jump wires are connected to the correct pins on both the USB-UART adapter and the USB-C breakout board
* Connect your USB-C breakout board to your PineNote in the opposite orientation
* Run <code>minicom</code> as sudo in case your user doesn't have appropriate permissions
* Ensure you are setting the baud rate to 1500000 (1.5 million), and (less importantly because these are probably used by default) 8 data bits, 1 stop bit, no parity and no flow control

If you can see text but are having trouble sending <code>ctrl+c</code> to the PineNote during boot:
* Be sure you're typing <code>ctrl+a</code> first, or whatever escape sequence your terminal emulator uses
* Send it right as the PineNote is booting, before the loading bar appears on screen
* Double-check your Y-shaped pull-up resistor cable; if this isn't working properly you'll probably be able to read text but not send text

== USB passthrough ==

If your USB-C breakout board has a passthrough/intercept design, you can connect to your PineNote over USB and UART at the same time.
This can be useful when you're doing development work on the PineNote boot process so you don't have to continually reconnect cables.
You'll need a USB-A to USB-C cable, connecting directly from your computer's USB-A hub to your USB-C breakout board's female USB-C port.
It's important to connect directly from USB-A, without any intermediate USB-C components.
Note that connecting a live USB cable to your USB-C breakout board in this way dramatically increases the danger of frying your PineNote with a short, so you should only do this if all connectors are safely wrapped in electrical tape.

[[Category:PineNote]]

PineNote Development/UART

2023-10-14T14:04:39Z

Ahelwer: /* Using UART */ Added section on sending commands over UART

[[File:Pinenote-uart-dongle.jpeg|thumb|Basic non-stock PineNote UART dongle]]

This page contains information on creating and using a [https://en.wikipedia.org/wiki/Universal_asynchronous_receiver-transmitter UART] dongle for the [[PineNote]].
The PineNote was shipped with a compatible UART dongle, but replacements are not available to order in case of loss or hardware fault.
Thankfully it is not difficult to make your own from easily-acquired components and a small bit of soldering.

Fear not if you've never soldered anything before!
This serves as an excellent first soldering project.
Borrow the tools from a friend, local hackerspace, or tool library.
Pine64 also makes [[Pinecil|a nice soldering iron]] themselves.

A PineNote UART dongle enables you to:
# Interact with the system boot menu
# Read system events in real time as the PineNote is used
# Fix the PineNote without opening the case if something goes wrong while [[PineNote Development/Flashing|flashing it]]

Since the PineNote is an embedded system, interfacing with it during boot is more complicated than with an ordinary computer.
The UART dongle enables you to do this.

The PineNote factory firmware runs UART at a baud rate of 1500000 bps, 8 data bits, 1 stop bit, no parity and no flow control.
The process by which the PineNote design was modified to include closed-case UART is documented [[PineNote/Hardware Changes/Closed Case UART|here]].

== Stock dongle ==

The stock UART dongle included with the PineNote was a simple device plugging directly into the PineNote's USB-C port.
The dongle exposed a female USB-C port, which the user plugged into to get UART access.
This design unfortunately ruled out passthrough USB connections, where the user connects to the PineNote via UART and USB simultaneously.
The dongle is not currently available for purchase.

<gallery>
Pinenote-stock-uart-dongle-front.jpg|Front
Pinenote-stock-uart-dongle-back.jpg|Back
</gallery>

== Creating a dongle ==

A typical self-built PineNote UART dongle design has the following components:
# A USB-C breakout board with a male connector exposing the 24 pins of the PineNote's USB-C port
# A USB-UART adapter, to plug into a USB port of the computer you'll use to interface with the PineNote
# [https://en.wikipedia.org/wiki/Jump_wire Jump wires] to connect specific breakout board pins to pins on the USB-UART adapter
# Two 1,000 Ohm through-hole resistors to splice into the jump wires
# Electrical tape or heat shrink to wrap connectors and prevent shorts

You will also need the following tools:
# Soldering iron with solder
# Wire cutters & strippers

The PineNote's internal UART system is documented in [https://files.pine64.org/doc/PineNote/PineNote_USB-C_Console_UART_breakout_board_schematic_v1.0_20210903.pdf this schematic].
The purpose of all 24 USB-C pins is documented [https://en.wikipedia.org/wiki/USB-C#Receptacles on the USB-C Wikipedia page].
We are interested in three sets of pins:
# The SBU1 (A8) and SBU2 (B8) side band use pins
# The CC1 (A5) and CC2 (B5) configuration channel pins
# The GND [https://en.wikipedia.org/wiki/Ground_(electricity) ground return] pins (A1, A12, B1, and B12)

In the PineNote UART schematic you can see (on the bottom right diagram labeled <code>USB_TYPEC_Male</code>) the side band pins are given the labels <code>UART2_TX_SUB1</code> for A8 and <code>UART2_RX_SUB2</code> for B8.
The first (TX) is used for transmitting data and the second (RX) is used for receiving data, from the perspective of the PineNote.
Also note the configuration channel pins labeled <code>TYPEC_CC1</code> for A5 and <code>TYPEC_CC2</code> for B5.
These pins are used to signal to the PineNote that a UART dongle is present.
The diagram shows they must be connected to a 3.3V source in parallel, mediated by resistors.
The schematic indicates 10,000 Ohm resistors, but community member Visti Andresen (talpadk) experimented and found 1,000 Ohm resistors work better.
Our mission is to wire up pins from a USB-UART adapter to a USB-C breakout board following these requirements.

=== Buying components ===

There are many possible USB-C breakout board designs available for purchase online.
One particularly useful design is a "passthrough" or "intercept" style, with both male and female USB-C ports.
This design is more versatile in case you want to reuse it in other projects, and also enables you to connect to the PineNote via UART and USB at the same time.
An example of this product can be found [https://pmdway.com/products/usb-3-1-type-c-male-to-female-breakout-test-board here], although you are encouraged to shop around for cheaper options.
If you're fine with a bit more soldering, there is a very cheap one [https://www.ebay.com/itm/275407037613 here].

Similarly, there are many USB-UART adapter designs available.
These devices plug into your computer and expose a number of pins themselves, connecting to specific pins on the breakout board with jump wires.
It is important to get a 3.3V model, or at least a model with the option of 3.3V, as a 5V source might fry the PineNote.
[https://pmdway.com/products/usb-to-ttl-serial-cp2104-6-pin-converter-module Here] is one example with jump wires included, although you are again encouraged to shop around for alternatives.

All other necessary components of our UART dongle are readily & cheaply available in many locations.

=== Splicing resistors ===

[[File:PineNote-UART-Y-pull-up-resistor-cable.jpg|thumb|The desired end result; wrap removed from resistors for illustration purposes.]]

This is the only difficult part of the whole process.
Your goal is to create a Y-shaped jump wire with 1,000 Ohm through-hole resistors spliced into each of the twin arms.
The solitary leg will connect to a 3.3V source on your USB-UART adapter.
The twin arms will connect to the configuration channel pins on your USB-C breakout board.
This setup is called using pull-up resistors, and you can read a nice introduction to their purpose [https://www.electronics-tutorials.ws/logic/pull-up-resistor.html here].

For this project you'll need:
# A soldering iron with solder
# Wire cutters & strippers
# 2x jumper wires, male/female as compatible with your board designs
# 2x 1,000 Ohm through-hole resistors
# Electrical tape or heat shrink wrap

Consider buying extra jumper wires and resistors in case you mess up.
Also double-check that you have 1K resistors with [https://resistorcolorcodecalc.com/ this color code calculator].
Although the PineNote UART schematic says to use 10K Ohm resistors, community member Visti Andresen (talpadk) experimented and found 1K is more appropriate.
Assemble your Y-cable as follows:
# Graft one jump wire onto the other to form a Y shape using [https://www.youtube.com/watch?v=KpiEfuhPqew this] technique, ensuring solitary leg end is compatible with your USB-UART adapter
# Splice resistors into the twin arms using [https://www.youtube.com/watch?v=RMgMVqqjPZ0 this] technique
# Splice remaining jump wire onto the ends of the resistors, ensuring ends are compatible with your USB-C breakout board
# Cover all exposed wire & resistors with electrical tape or heat shrink wrap

=== Assembly ===

Once you have acquired all necessary components, assemble the UART dongle as follows:
# Connect a jump wire from the GND pin on the USB-UART adapter to any one of the four GND pins on the USB-C breakout board (A1, A12, B1, or B12)
# Connect a jump wire from the RXD pin on the USB-UART adapter to the <code>UART2_TX_SUB1</code> SBU1 pin on the USB-C breakout board (A8)
# Connect a jump wire from the TXD pin on the USB-UART adapter to the <code>UART2_RX_SUB2</code> SBU2 pin on the USB-C breakout board (B8)
# Connect your Y-shaped jump wire from the 3.3V source pin on the USB-UART adapter to the CC1 and CC2 pins on the USB-C breakout board (A5 and B5)
# Wrap all metal connectors in electrical tape or heat shrink to prevent accidental shorts

Be '''very certain''' of your connections for the 3.3V source and its cable, as there is a real risk of irreparably frying your PineNote if they're wrong!
Especially be sure you are connecting to a 3.3V source and not a 5V source.

Note that if you mix up the TX/RX pins, it will still work but the USB-C breakout board will just plug into the PineNote upside down.
You can therefore choose which orientation you want by swapping the TX/RX pin connections.
Experience shows that RX/TX-TX/RX connections will have the PineNote face down while connected, while RX/RX-TX/TX connections will put the PineNote face up.

== Using the dongle ==

First, use your UART dongle to physically connect your PineNote to your computer:
# Plug the USB-UART adapter into one of your computer's USB ports
# Plug the USB-C breakout board into the USB-C port on the bottom of your PineNote; the orientation matters, so try both and remember which one works

Once the hardware is connected, set up your computer's software as follows:
# Identify the USB-UART adapter in your <code>/dev</code> directory by running <code>ls /dev</code> with it plugged in, unplugging it, then again running <code>ls /dev</code> and seeing what changed; it is likely to be called <code>/dev/ttyUSB0</code>
# Check your permissions; run <code>ls -l /dev/ttyUSB0</code> to see which groups have access to the dongle (probably <code>dialout</code> or <code>uucp</code>), and add your user to that group; remember you need to log out before group changes take effect
# Install [https://www.gnu.org/software/screen/ minicom] (or [https://askubuntu.com/q/40959 some other option], but the instructions below are written for <code>minicom</code>)
# In a terminal window, run <code>minicom -D /dev/ttyUSB0 -b 1500000</code> or run <code>minicom --setup</code> to specify these settings by default

Once the software is set up, power-cycle your PineNote; as the system boots you should see text appearing in your terminal window.
You can exit the session with <code>ctrl+a x</code> then pressing <code>Enter</code> to confirm.
Run <code>man minicom</code> for more details.

=== Sending commands ===

Pressing <code>ctrl+a</code> in <code>minicom</code> enables you to send keystrokes to your PineNote.
The most important of these is <code>ctrl+c</code>, which if sent during boot will put you in the U-Boot command prompt.
You can then type <code>help</code> to list possible commands.

=== Troubleshooting ===

If you don't see any text in your terminal as the PineNote boots, or the text is garbled, try the following:
* Ensure your GND, RX/TX, and CC jump wires are connected to the correct pins on both the USB-UART adapter and the USB-C breakout board
* Connect your USB-C breakout board to your PineNote in the opposite orientation
* Run <code>minicom</code> as sudo in case your user doesn't have appropriate permissions
* Ensure you are setting the baud rate in the <code>screen</code> command to 1500000 (1.5 million)

If you can see text but are having trouble sending <code>ctrl+c</code> to the PineNote during boot:
* Be sure you're typing <code>ctrl+a</code> first, or whatever escape sequence your terminal emulator uses
* Send it right as the PineNote is booting, before the loading bar appears on screen
* Double-check your Y-shaped pull-up resistor cable; if this isn't working properly you'll probably be able to read text but not send text

== USB passthrough ==

If your USB-C breakout board has a passthrough/intercept design, you can connect to your PineNote over USB and UART at the same time.
This can be useful when you're doing development work on the PineNote boot process so you don't have to continually reconnect cables.
You'll need a USB-A to USB-C cable, connecting directly from your computer's USB-A hub to your USB-C breakout board's female USB-C port.
It's important to connect directly from USB-A, without any intermediate USB-C components.
Note that connecting a live USB cable to your USB-C breakout board in this way dramatically increases the danger of frying your PineNote with a short, so you should only do this if all connectors are safely wrapped in electrical tape.

[[Category:PineNote]]

PineNote Development/UART

2023-10-14T13:18:32Z

Ahelwer: /* Assembly */ added note about orientation

[[File:Pinenote-uart-dongle.jpeg|thumb|Basic non-stock PineNote UART dongle]]

This page contains information on creating and using a [https://en.wikipedia.org/wiki/Universal_asynchronous_receiver-transmitter UART] dongle for the [[PineNote]].
The PineNote was shipped with a compatible UART dongle, but replacements are not available to order in case of loss or hardware fault.
Thankfully it is not difficult to make your own from easily-acquired components and a small bit of soldering.

Fear not if you've never soldered anything before!
This serves as an excellent first soldering project.
Borrow the tools from a friend, local hackerspace, or tool library.
Pine64 also makes [[Pinecil|a nice soldering iron]] themselves.

A PineNote UART dongle enables you to:
# Interact with the system boot menu
# Read system events in real time as the PineNote is used
# Fix the PineNote without opening the case if something goes wrong while [[PineNote Development/Flashing|flashing it]]

Since the PineNote is an embedded system, interfacing with it during boot is more complicated than with an ordinary computer.
The UART dongle enables you to do this.

The PineNote factory firmware runs UART at a baud rate of 1500000 bps, 8 data bits, 1 stop bit, no parity and no flow control.
The process by which the PineNote design was modified to include closed-case UART is documented [[PineNote/Hardware Changes/Closed Case UART|here]].

== Stock dongle ==

The stock UART dongle included with the PineNote was a simple device plugging directly into the PineNote's USB-C port.
The dongle exposed a female USB-C port, which the user plugged into to get UART access.
This design unfortunately ruled out passthrough USB connections, where the user connects to the PineNote via UART and USB simultaneously.
The dongle is not currently available for purchase.

<gallery>
Pinenote-stock-uart-dongle-front.jpg|Front
Pinenote-stock-uart-dongle-back.jpg|Back
</gallery>

== Creating a dongle ==

A typical self-built PineNote UART dongle design has the following components:
# A USB-C breakout board with a male connector exposing the 24 pins of the PineNote's USB-C port
# A USB-UART adapter, to plug into a USB port of the computer you'll use to interface with the PineNote
# [https://en.wikipedia.org/wiki/Jump_wire Jump wires] to connect specific breakout board pins to pins on the USB-UART adapter
# Two 1,000 Ohm through-hole resistors to splice into the jump wires
# Electrical tape or heat shrink to wrap connectors and prevent shorts

You will also need the following tools:
# Soldering iron with solder
# Wire cutters & strippers

The PineNote's internal UART system is documented in [https://files.pine64.org/doc/PineNote/PineNote_USB-C_Console_UART_breakout_board_schematic_v1.0_20210903.pdf this schematic].
The purpose of all 24 USB-C pins is documented [https://en.wikipedia.org/wiki/USB-C#Receptacles on the USB-C Wikipedia page].
We are interested in three sets of pins:
# The SBU1 (A8) and SBU2 (B8) side band use pins
# The CC1 (A5) and CC2 (B5) configuration channel pins
# The GND [https://en.wikipedia.org/wiki/Ground_(electricity) ground return] pins (A1, A12, B1, and B12)

In the PineNote UART schematic you can see (on the bottom right diagram labeled <code>USB_TYPEC_Male</code>) the side band pins are given the labels <code>UART2_TX_SUB1</code> for A8 and <code>UART2_RX_SUB2</code> for B8.
The first (TX) is used for transmitting data and the second (RX) is used for receiving data, from the perspective of the PineNote.
Also note the configuration channel pins labeled <code>TYPEC_CC1</code> for A5 and <code>TYPEC_CC2</code> for B5.
These pins are used to signal to the PineNote that a UART dongle is present.
The diagram shows they must be connected to a 3.3V source in parallel, mediated by resistors.
The schematic indicates 10,000 Ohm resistors, but community member Visti Andresen (talpadk) experimented and found 1,000 Ohm resistors work better.
Our mission is to wire up pins from a USB-UART adapter to a USB-C breakout board following these requirements.

=== Buying components ===

There are many possible USB-C breakout board designs available for purchase online.
One particularly useful design is a "passthrough" or "intercept" style, with both male and female USB-C ports.
This design is more versatile in case you want to reuse it in other projects, and also enables you to connect to the PineNote via UART and USB at the same time.
An example of this product can be found [https://pmdway.com/products/usb-3-1-type-c-male-to-female-breakout-test-board here], although you are encouraged to shop around for cheaper options.
If you're fine with a bit more soldering, there is a very cheap one [https://www.ebay.com/itm/275407037613 here].

Similarly, there are many USB-UART adapter designs available.
These devices plug into your computer and expose a number of pins themselves, connecting to specific pins on the breakout board with jump wires.
It is important to get a 3.3V model, or at least a model with the option of 3.3V, as a 5V source might fry the PineNote.
[https://pmdway.com/products/usb-to-ttl-serial-cp2104-6-pin-converter-module Here] is one example with jump wires included, although you are again encouraged to shop around for alternatives.

All other necessary components of our UART dongle are readily & cheaply available in many locations.

=== Splicing resistors ===

[[File:PineNote-UART-Y-pull-up-resistor-cable.jpg|thumb|The desired end result; wrap removed from resistors for illustration purposes.]]

This is the only difficult part of the whole process.
Your goal is to create a Y-shaped jump wire with 1,000 Ohm through-hole resistors spliced into each of the twin arms.
The solitary leg will connect to a 3.3V source on your USB-UART adapter.
The twin arms will connect to the configuration channel pins on your USB-C breakout board.
This setup is called using pull-up resistors, and you can read a nice introduction to their purpose [https://www.electronics-tutorials.ws/logic/pull-up-resistor.html here].

For this project you'll need:
# A soldering iron with solder
# Wire cutters & strippers
# 2x jumper wires, male/female as compatible with your board designs
# 2x 1,000 Ohm through-hole resistors
# Electrical tape or heat shrink wrap

Consider buying extra jumper wires and resistors in case you mess up.
Also double-check that you have 1K resistors with [https://resistorcolorcodecalc.com/ this color code calculator].
Although the PineNote UART schematic says to use 10K Ohm resistors, community member Visti Andresen (talpadk) experimented and found 1K is more appropriate.
Assemble your Y-cable as follows:
# Graft one jump wire onto the other to form a Y shape using [https://www.youtube.com/watch?v=KpiEfuhPqew this] technique, ensuring solitary leg end is compatible with your USB-UART adapter
# Splice resistors into the twin arms using [https://www.youtube.com/watch?v=RMgMVqqjPZ0 this] technique
# Splice remaining jump wire onto the ends of the resistors, ensuring ends are compatible with your USB-C breakout board
# Cover all exposed wire & resistors with electrical tape or heat shrink wrap

=== Assembly ===

Once you have acquired all necessary components, assemble the UART dongle as follows:
# Connect a jump wire from the GND pin on the USB-UART adapter to any one of the four GND pins on the USB-C breakout board (A1, A12, B1, or B12)
# Connect a jump wire from the RXD pin on the USB-UART adapter to the <code>UART2_TX_SUB1</code> SBU1 pin on the USB-C breakout board (A8)
# Connect a jump wire from the TXD pin on the USB-UART adapter to the <code>UART2_RX_SUB2</code> SBU2 pin on the USB-C breakout board (B8)
# Connect your Y-shaped jump wire from the 3.3V source pin on the USB-UART adapter to the CC1 and CC2 pins on the USB-C breakout board (A5 and B5)
# Wrap all metal connectors in electrical tape or heat shrink to prevent accidental shorts

Be '''very certain''' of your connections for the 3.3V source and its cable, as there is a real risk of irreparably frying your PineNote if they're wrong!
Especially be sure you are connecting to a 3.3V source and not a 5V source.

Note that if you mix up the TX/RX pins, it will still work but the USB-C breakout board will just plug into the PineNote upside down.
You can therefore choose which orientation you want by swapping the TX/RX pin connections.
Experience shows that RX/TX-TX/RX connections will have the PineNote face down while connected, while RX/RX-TX/TX connections will put the PineNote face up.

== Using UART ==

First, use your UART dongle to physically connect your PineNote to your computer:
# Plug the USB-UART adapter into one of your computer's USB ports
# Plug the USB-C breakout board into the USB-C port on the bottom of your PineNote; the orientation matters, so try both and remember which one works

Once the hardware is connected, set up your computer's software as follows:
# Install [https://www.gnu.org/software/screen/ GNU Screen] (or [https://askubuntu.com/q/40959 some other option], but the instructions below are written for <code>screen</code>)
# Identify the USB-UART adapter in your <code>/dev</code> directory by running <code>ls /dev</code> with it plugged in, unplugging it, then again running <code>ls /dev</code> and seeing what changes; it is likely to be called <code>/dev/ttyUSB0</code>
# In a terminal window, run <code>screen -L /dev/ttyUSB0 1500000</code> (you may need to run this as sudo depending on your user's permissions; on most Linux distributions you need to be in the <code>dialout</code> usergroup)

Once the software is set up, power-cycle your PineNote; as the system boots you should see text appearing in your terminal window.
You can exit the screen session with <code>ctrl+a k</code> then pressing <code>y</code> to confirm.
The <code>screen -L</code> flag outputs a text log of the session to the current working directory, probably called <code>screenlog.0</code>.

==== Troubleshooting ====

If you don't see any text in your terminal as the PineNote boots, or the text is garbled, try the following:
* Ensure your GND, RX/TX, and CC jump wires are connected to the correct pins on both the USB-UART adapter and the USB-C breakout board
* Connect your USB-C breakout board to your PineNote in the opposite orientation
* Run the screen command as sudo in case your user doesn't have appropriate permissions
* Ensure you are setting the baud rate in the <code>screen</code> command to 1500000 (1.5 million)

== USB passthrough ==

If your USB-C breakout board has a passthrough/intercept design, you can connect to your PineNote over USB and UART at the same time.
This can be useful when you're doing development work on the PineNote boot process so you don't have to continually reconnect cables.
You'll need a USB-A to USB-C cable, connecting directly from your computer's USB-A hub to your USB-C breakout board's female USB-C port.
It's important to connect directly from USB-A, without any intermediate USB-C components.
Note that connecting a live USB cable to your USB-C breakout board in this way dramatically increases the danger of frying your PineNote with a short, so you should only do this if all connectors are safely wrapped in electrical tape.

[[Category:PineNote]]

PineNote Development/UART

2023-10-14T13:16:05Z

Ahelwer: Added credit to talpadk

[[File:Pinenote-uart-dongle.jpeg|thumb|Basic non-stock PineNote UART dongle]]

This page contains information on creating and using a [https://en.wikipedia.org/wiki/Universal_asynchronous_receiver-transmitter UART] dongle for the [[PineNote]].
The PineNote was shipped with a compatible UART dongle, but replacements are not available to order in case of loss or hardware fault.
Thankfully it is not difficult to make your own from easily-acquired components and a small bit of soldering.

Fear not if you've never soldered anything before!
This serves as an excellent first soldering project.
Borrow the tools from a friend, local hackerspace, or tool library.
Pine64 also makes [[Pinecil|a nice soldering iron]] themselves.

A PineNote UART dongle enables you to:
# Interact with the system boot menu
# Read system events in real time as the PineNote is used
# Fix the PineNote without opening the case if something goes wrong while [[PineNote Development/Flashing|flashing it]]

Since the PineNote is an embedded system, interfacing with it during boot is more complicated than with an ordinary computer.
The UART dongle enables you to do this.

The PineNote factory firmware runs UART at a baud rate of 1500000 bps, 8 data bits, 1 stop bit, no parity and no flow control.
The process by which the PineNote design was modified to include closed-case UART is documented [[PineNote/Hardware Changes/Closed Case UART|here]].

== Stock dongle ==

The stock UART dongle included with the PineNote was a simple device plugging directly into the PineNote's USB-C port.
The dongle exposed a female USB-C port, which the user plugged into to get UART access.
This design unfortunately ruled out passthrough USB connections, where the user connects to the PineNote via UART and USB simultaneously.
The dongle is not currently available for purchase.

<gallery>
Pinenote-stock-uart-dongle-front.jpg|Front
Pinenote-stock-uart-dongle-back.jpg|Back
</gallery>

== Creating a dongle ==

A typical self-built PineNote UART dongle design has the following components:
# A USB-C breakout board with a male connector exposing the 24 pins of the PineNote's USB-C port
# A USB-UART adapter, to plug into a USB port of the computer you'll use to interface with the PineNote
# [https://en.wikipedia.org/wiki/Jump_wire Jump wires] to connect specific breakout board pins to pins on the USB-UART adapter
# Two 1,000 Ohm through-hole resistors to splice into the jump wires
# Electrical tape or heat shrink to wrap connectors and prevent shorts

You will also need the following tools:
# Soldering iron with solder
# Wire cutters & strippers

The PineNote's internal UART system is documented in [https://files.pine64.org/doc/PineNote/PineNote_USB-C_Console_UART_breakout_board_schematic_v1.0_20210903.pdf this schematic].
The purpose of all 24 USB-C pins is documented [https://en.wikipedia.org/wiki/USB-C#Receptacles on the USB-C Wikipedia page].
We are interested in three sets of pins:
# The SBU1 (A8) and SBU2 (B8) side band use pins
# The CC1 (A5) and CC2 (B5) configuration channel pins
# The GND [https://en.wikipedia.org/wiki/Ground_(electricity) ground return] pins (A1, A12, B1, and B12)

In the PineNote UART schematic you can see (on the bottom right diagram labeled <code>USB_TYPEC_Male</code>) the side band pins are given the labels <code>UART2_TX_SUB1</code> for A8 and <code>UART2_RX_SUB2</code> for B8.
The first (TX) is used for transmitting data and the second (RX) is used for receiving data, from the perspective of the PineNote.
Also note the configuration channel pins labeled <code>TYPEC_CC1</code> for A5 and <code>TYPEC_CC2</code> for B5.
These pins are used to signal to the PineNote that a UART dongle is present.
The diagram shows they must be connected to a 3.3V source in parallel, mediated by resistors.
The schematic indicates 10,000 Ohm resistors, but community member Visti Andresen (talpadk) experimented and found 1,000 Ohm resistors work better.
Our mission is to wire up pins from a USB-UART adapter to a USB-C breakout board following these requirements.

=== Buying components ===

There are many possible USB-C breakout board designs available for purchase online.
One particularly useful design is a "passthrough" or "intercept" style, with both male and female USB-C ports.
This design is more versatile in case you want to reuse it in other projects, and also enables you to connect to the PineNote via UART and USB at the same time.
An example of this product can be found [https://pmdway.com/products/usb-3-1-type-c-male-to-female-breakout-test-board here], although you are encouraged to shop around for cheaper options.
If you're fine with a bit more soldering, there is a very cheap one [https://www.ebay.com/itm/275407037613 here].

Similarly, there are many USB-UART adapter designs available.
These devices plug into your computer and expose a number of pins themselves, connecting to specific pins on the breakout board with jump wires.
It is important to get a 3.3V model, or at least a model with the option of 3.3V, as a 5V source might fry the PineNote.
[https://pmdway.com/products/usb-to-ttl-serial-cp2104-6-pin-converter-module Here] is one example with jump wires included, although you are again encouraged to shop around for alternatives.

All other necessary components of our UART dongle are readily & cheaply available in many locations.

=== Splicing resistors ===

[[File:PineNote-UART-Y-pull-up-resistor-cable.jpg|thumb|The desired end result; wrap removed from resistors for illustration purposes.]]

This is the only difficult part of the whole process.
Your goal is to create a Y-shaped jump wire with 1,000 Ohm through-hole resistors spliced into each of the twin arms.
The solitary leg will connect to a 3.3V source on your USB-UART adapter.
The twin arms will connect to the configuration channel pins on your USB-C breakout board.
This setup is called using pull-up resistors, and you can read a nice introduction to their purpose [https://www.electronics-tutorials.ws/logic/pull-up-resistor.html here].

For this project you'll need:
# A soldering iron with solder
# Wire cutters & strippers
# 2x jumper wires, male/female as compatible with your board designs
# 2x 1,000 Ohm through-hole resistors
# Electrical tape or heat shrink wrap

Consider buying extra jumper wires and resistors in case you mess up.
Also double-check that you have 1K resistors with [https://resistorcolorcodecalc.com/ this color code calculator].
Although the PineNote UART schematic says to use 10K Ohm resistors, community member Visti Andresen (talpadk) experimented and found 1K is more appropriate.
Assemble your Y-cable as follows:
# Graft one jump wire onto the other to form a Y shape using [https://www.youtube.com/watch?v=KpiEfuhPqew this] technique, ensuring solitary leg end is compatible with your USB-UART adapter
# Splice resistors into the twin arms using [https://www.youtube.com/watch?v=RMgMVqqjPZ0 this] technique
# Splice remaining jump wire onto the ends of the resistors, ensuring ends are compatible with your USB-C breakout board
# Cover all exposed wire & resistors with electrical tape or heat shrink wrap

=== Assembly ===

Once you have acquired all necessary components, assemble the UART dongle as follows:
# Connect a jump wire from the GND pin on the USB-UART adapter to any one of the four GND pins on the USB-C breakout board (A1, A12, B1, or B12)
# Connect a jump wire from the RXD pin on the USB-UART adapter to the <code>UART2_TX_SUB1</code> SBU1 pin on the USB-C breakout board (A8)
# Connect a jump wire from the TXD pin on the USB-UART adapter to the <code>UART2_RX_SUB2</code> SBU2 pin on the USB-C breakout board (B8)
# Connect your Y-shaped jump wire from the 3.3V source pin on the USB-UART adapter to the CC1 and CC2 pins on the USB-C breakout board (A5 and B5)
# Wrap all metal connectors in electrical tape or heat shrink to prevent accidental shorts

Be '''very certain''' of your connections for the 3.3V source and its cable, as there is a real risk of irreparably frying your PineNote if they're wrong!
Especially be sure you are connecting to a 3.3V source and not a 5V source.

Note that if you mix up the TX/RX pins, it will still work but the USB-C breakout board will just plug into the PineNote upside down.
You can therefore choose which orientation you want by swapping the TX/RX pin connections.

== Using UART ==

First, use your UART dongle to physically connect your PineNote to your computer:
# Plug the USB-UART adapter into one of your computer's USB ports
# Plug the USB-C breakout board into the USB-C port on the bottom of your PineNote; the orientation matters, so try both and remember which one works

Once the hardware is connected, set up your computer's software as follows:
# Install [https://www.gnu.org/software/screen/ GNU Screen] (or [https://askubuntu.com/q/40959 some other option], but the instructions below are written for <code>screen</code>)
# Identify the USB-UART adapter in your <code>/dev</code> directory by running <code>ls /dev</code> with it plugged in, unplugging it, then again running <code>ls /dev</code> and seeing what changes; it is likely to be called <code>/dev/ttyUSB0</code>
# In a terminal window, run <code>screen -L /dev/ttyUSB0 1500000</code> (you may need to run this as sudo depending on your user's permissions; on most Linux distributions you need to be in the <code>dialout</code> usergroup)

Once the software is set up, power-cycle your PineNote; as the system boots you should see text appearing in your terminal window.
You can exit the screen session with <code>ctrl+a k</code> then pressing <code>y</code> to confirm.
The <code>screen -L</code> flag outputs a text log of the session to the current working directory, probably called <code>screenlog.0</code>.

==== Troubleshooting ====

If you don't see any text in your terminal as the PineNote boots, or the text is garbled, try the following:
* Ensure your GND, RX/TX, and CC jump wires are connected to the correct pins on both the USB-UART adapter and the USB-C breakout board
* Connect your USB-C breakout board to your PineNote in the opposite orientation
* Run the screen command as sudo in case your user doesn't have appropriate permissions
* Ensure you are setting the baud rate in the <code>screen</code> command to 1500000 (1.5 million)

== USB passthrough ==

If your USB-C breakout board has a passthrough/intercept design, you can connect to your PineNote over USB and UART at the same time.
This can be useful when you're doing development work on the PineNote boot process so you don't have to continually reconnect cables.
You'll need a USB-A to USB-C cable, connecting directly from your computer's USB-A hub to your USB-C breakout board's female USB-C port.
It's important to connect directly from USB-A, without any intermediate USB-C components.
Note that connecting a live USB cable to your USB-C breakout board in this way dramatically increases the danger of frying your PineNote with a short, so you should only do this if all connectors are safely wrapped in electrical tape.

[[Category:PineNote]]

PineNote Development/UART

2023-10-14T13:14:26Z

Ahelwer: Added link to pinecil

[[File:Pinenote-uart-dongle.jpeg|thumb|Basic non-stock PineNote UART dongle]]

This page contains information on creating and using a [https://en.wikipedia.org/wiki/Universal_asynchronous_receiver-transmitter UART] dongle for the [[PineNote]].
The PineNote was shipped with a compatible UART dongle, but replacements are not available to order in case of loss or hardware fault.
Thankfully it is not difficult to make your own from easily-acquired components and a small bit of soldering.

Fear not if you've never soldered anything before!
This serves as an excellent first soldering project.
Borrow the tools from a friend, local hackerspace, or tool library.
Pine64 also makes [[Pinecil|a nice soldering iron]] themselves.

A PineNote UART dongle enables you to:
# Interact with the system boot menu
# Read system events in real time as the PineNote is used
# Fix the PineNote without opening the case if something goes wrong while [[PineNote Development/Flashing|flashing it]]

Since the PineNote is an embedded system, interfacing with it during boot is more complicated than with an ordinary computer.
The UART dongle enables you to do this.

The PineNote factory firmware runs UART at a baud rate of 1500000 bps, 8 data bits, 1 stop bit, no parity and no flow control.
The process by which the PineNote design was modified to include closed-case UART is documented [[PineNote/Hardware Changes/Closed Case UART|here]].

== Stock dongle ==

The stock UART dongle included with the PineNote was a simple device plugging directly into the PineNote's USB-C port.
The dongle exposed a female USB-C port, which the user plugged into to get UART access.
This design unfortunately ruled out passthrough USB connections, where the user connects to the PineNote via UART and USB simultaneously.
The dongle is not currently available for purchase.

<gallery>
Pinenote-stock-uart-dongle-front.jpg|Front
Pinenote-stock-uart-dongle-back.jpg|Back
</gallery>

== Creating a dongle ==

A typical self-built PineNote UART dongle design has the following components:
# A USB-C breakout board with a male connector exposing the 24 pins of the PineNote's USB-C port
# A USB-UART adapter, to plug into a USB port of the computer you'll use to interface with the PineNote
# [https://en.wikipedia.org/wiki/Jump_wire Jump wires] to connect specific breakout board pins to pins on the USB-UART adapter
# Two 1,000 Ohm through-hole resistors to splice into the jump wires
# Electrical tape or heat shrink to wrap connectors and prevent shorts

You will also need the following tools:
# Soldering iron with solder
# Wire cutters & strippers

The PineNote's internal UART system is documented in [https://files.pine64.org/doc/PineNote/PineNote_USB-C_Console_UART_breakout_board_schematic_v1.0_20210903.pdf this schematic].
The purpose of all 24 USB-C pins is documented [https://en.wikipedia.org/wiki/USB-C#Receptacles on the USB-C Wikipedia page].
We are interested in three sets of pins:
# The SBU1 (A8) and SBU2 (B8) side band use pins
# The CC1 (A5) and CC2 (B5) configuration channel pins
# The GND [https://en.wikipedia.org/wiki/Ground_(electricity) ground return] pins (A1, A12, B1, and B12)

In the PineNote UART schematic you can see (on the bottom right diagram labeled <code>USB_TYPEC_Male</code>) the side band pins are given the labels <code>UART2_TX_SUB1</code> for A8 and <code>UART2_RX_SUB2</code> for B8.
The first (TX) is used for transmitting data and the second (RX) is used for receiving data, from the perspective of the PineNote.
Also note the configuration channel pins labeled <code>TYPEC_CC1</code> for A5 and <code>TYPEC_CC2</code> for B5.
These pins are used to signal to the PineNote that a UART dongle is present.
The diagram shows they must be connected to a 3.3V source in parallel, mediated by resistors.
The schematic indicates 10,000 Ohm resistors, but community member talpadk experimented and found 1,000 Ohm resistors work better.
Our mission is to wire up pins from a USB-UART adapter to a USB-C breakout board following these requirements.

=== Buying components ===

There are many possible USB-C breakout board designs available for purchase online.
One particularly useful design is a "passthrough" or "intercept" style, with both male and female USB-C ports.
This design is more versatile in case you want to reuse it in other projects, and also enables you to connect to the PineNote via UART and USB at the same time.
An example of this product can be found [https://pmdway.com/products/usb-3-1-type-c-male-to-female-breakout-test-board here], although you are encouraged to shop around for cheaper options.
If you're fine with a bit more soldering, there is a very cheap one [https://www.ebay.com/itm/275407037613 here].

Similarly, there are many USB-UART adapter designs available.
These devices plug into your computer and expose a number of pins themselves, connecting to specific pins on the breakout board with jump wires.
It is important to get a 3.3V model, or at least a model with the option of 3.3V, as a 5V source might fry the PineNote.
[https://pmdway.com/products/usb-to-ttl-serial-cp2104-6-pin-converter-module Here] is one example with jump wires included, although you are again encouraged to shop around for alternatives.

All other necessary components of our UART dongle are readily & cheaply available in many locations.

=== Splicing resistors ===

[[File:PineNote-UART-Y-pull-up-resistor-cable.jpg|thumb|The desired end result; wrap removed from resistors for illustration purposes.]]

This is the only difficult part of the whole process.
Your goal is to create a Y-shaped jump wire with 1,000 Ohm through-hole resistors spliced into each of the twin arms.
The solitary leg will connect to a 3.3V source on your USB-UART adapter.
The twin arms will connect to the configuration channel pins on your USB-C breakout board.
This setup is called using pull-up resistors, and you can read a nice introduction to their purpose [https://www.electronics-tutorials.ws/logic/pull-up-resistor.html here].

For this project you'll need:
# A soldering iron with solder
# Wire cutters & strippers
# 2x jumper wires, male/female as compatible with your board designs
# 2x 1,000 Ohm through-hole resistors
# Electrical tape or heat shrink wrap

Consider buying extra jumper wires and resistors in case you mess up.
Also double-check that you have 1K resistors with [https://resistorcolorcodecalc.com/ this color code calculator].
Although the PineNote UART schematic says to use 10K Ohm resistors, community member talpadk experimented and found 1K is more appropriate.
Assemble your Y-cable as follows:
# Graft one jump wire onto the other to form a Y shape using [https://www.youtube.com/watch?v=KpiEfuhPqew this] technique, ensuring solitary leg end is compatible with your USB-UART adapter
# Splice resistors into the twin arms using [https://www.youtube.com/watch?v=RMgMVqqjPZ0 this] technique
# Splice remaining jump wire onto the ends of the resistors, ensuring ends are compatible with your USB-C breakout board
# Cover all exposed wire & resistors with electrical tape or heat shrink wrap

=== Assembly ===

Once you have acquired all necessary components, assemble the UART dongle as follows:
# Connect a jump wire from the GND pin on the USB-UART adapter to any one of the four GND pins on the USB-C breakout board (A1, A12, B1, or B12)
# Connect a jump wire from the RXD pin on the USB-UART adapter to the <code>UART2_TX_SUB1</code> SBU1 pin on the USB-C breakout board (A8)
# Connect a jump wire from the TXD pin on the USB-UART adapter to the <code>UART2_RX_SUB2</code> SBU2 pin on the USB-C breakout board (B8)
# Connect your Y-shaped jump wire from the 3.3V source pin on the USB-UART adapter to the CC1 and CC2 pins on the USB-C breakout board (A5 and B5)
# Wrap all metal connectors in electrical tape or heat shrink to prevent accidental shorts

Be '''very certain''' of your connections for the 3.3V source and its cable, as there is a real risk of irreparably frying your PineNote if they're wrong!
Especially be sure you are connecting to a 3.3V source and not a 5V source.

Note that if you mix up the TX/RX pins, it will still work but the USB-C breakout board will just plug into the PineNote upside down.
You can therefore choose which orientation you want by swapping the TX/RX pin connections.

== Using UART ==

First, use your UART dongle to physically connect your PineNote to your computer:
# Plug the USB-UART adapter into one of your computer's USB ports
# Plug the USB-C breakout board into the USB-C port on the bottom of your PineNote; the orientation matters, so try both and remember which one works

Once the hardware is connected, set up your computer's software as follows:
# Install [https://www.gnu.org/software/screen/ GNU Screen] (or [https://askubuntu.com/q/40959 some other option], but the instructions below are written for <code>screen</code>)
# Identify the USB-UART adapter in your <code>/dev</code> directory by running <code>ls /dev</code> with it plugged in, unplugging it, then again running <code>ls /dev</code> and seeing what changes; it is likely to be called <code>/dev/ttyUSB0</code>
# In a terminal window, run <code>screen -L /dev/ttyUSB0 1500000</code> (you may need to run this as sudo depending on your user's permissions; on most Linux distributions you need to be in the <code>dialout</code> usergroup)

Once the software is set up, power-cycle your PineNote; as the system boots you should see text appearing in your terminal window.
You can exit the screen session with <code>ctrl+a k</code> then pressing <code>y</code> to confirm.
The <code>screen -L</code> flag outputs a text log of the session to the current working directory, probably called <code>screenlog.0</code>.

==== Troubleshooting ====

If you don't see any text in your terminal as the PineNote boots, or the text is garbled, try the following:
* Ensure your GND, RX/TX, and CC jump wires are connected to the correct pins on both the USB-UART adapter and the USB-C breakout board
* Connect your USB-C breakout board to your PineNote in the opposite orientation
* Run the screen command as sudo in case your user doesn't have appropriate permissions
* Ensure you are setting the baud rate in the <code>screen</code> command to 1500000 (1.5 million)

== USB passthrough ==

If your USB-C breakout board has a passthrough/intercept design, you can connect to your PineNote over USB and UART at the same time.
This can be useful when you're doing development work on the PineNote boot process so you don't have to continually reconnect cables.
You'll need a USB-A to USB-C cable, connecting directly from your computer's USB-A hub to your USB-C breakout board's female USB-C port.
It's important to connect directly from USB-A, without any intermediate USB-C components.
Note that connecting a live USB cable to your USB-C breakout board in this way dramatically increases the danger of frying your PineNote with a short, so you should only do this if all connectors are safely wrapped in electrical tape.

[[Category:PineNote]]

PineNote Development/UART

2023-10-14T02:22:37Z

Ahelwer: /* Troubleshooting */

[[File:Pinenote-uart-dongle.jpeg|thumb|Basic non-stock PineNote UART dongle]]

This page contains information on creating and using a [https://en.wikipedia.org/wiki/Universal_asynchronous_receiver-transmitter UART] dongle for the [[PineNote]].
The PineNote was shipped with a compatible UART dongle, but replacements are not available to order in case of loss or hardware fault.
Thankfully it is not difficult to make your own from easily-acquired components and a small bit of soldering.
Fear not if you've never soldered anything before!
This serves as an excellent first soldering project.
Borrow the tools from a friend, local hackerspace, or tool library.

A PineNote UART dongle enables you to:
# Interact with the system boot menu
# Read system events in real time as the PineNote is used
# Fix the PineNote without opening the case if something goes wrong while [[PineNote Development/Flashing|flashing it]]

Since the PineNote is an embedded system, interfacing with it during boot is more complicated than with an ordinary computer.
The UART dongle enables you to do this.

The PineNote factory firmware runs UART at a baud rate of 1500000 bps, 8 data bits, 1 stop bit, no parity and no flow control.
The process by which the PineNote design was modified to include closed-case UART is documented [[PineNote/Hardware Changes/Closed Case UART|here]].

== Stock dongle ==

The stock UART dongle included with the PineNote was a simple device plugging directly into the PineNote's USB-C port.
The dongle exposed a female USB-C port, which the user plugged into to get UART access.
This design unfortunately ruled out passthrough USB connections, where the user connects to the PineNote via UART and USB simultaneously.
The dongle is not currently available for purchase.

<gallery>
Pinenote-stock-uart-dongle-front.jpg|Front
Pinenote-stock-uart-dongle-back.jpg|Back
</gallery>

== Creating a dongle ==

A typical self-built PineNote UART dongle design has the following components:
# A USB-C breakout board with a male connector exposing the 24 pins of the PineNote's USB-C port
# A USB-UART adapter, to plug into a USB port of the computer you'll use to interface with the PineNote
# [https://en.wikipedia.org/wiki/Jump_wire Jump wires] to connect specific breakout board pins to pins on the USB-UART adapter
# Two 1,000 Ohm through-hole resistors to splice into the jump wires
# Electrical tape or heat shrink to wrap connectors and prevent shorts

You will also need the following tools:
# Soldering iron with solder
# Wire cutters & strippers

The PineNote's internal UART system is documented in [https://files.pine64.org/doc/PineNote/PineNote_USB-C_Console_UART_breakout_board_schematic_v1.0_20210903.pdf this schematic].
The purpose of all 24 USB-C pins is documented [https://en.wikipedia.org/wiki/USB-C#Receptacles on the USB-C Wikipedia page].
We are interested in three sets of pins:
# The SBU1 (A8) and SBU2 (B8) side band use pins
# The CC1 (A5) and CC2 (B5) configuration channel pins
# The GND [https://en.wikipedia.org/wiki/Ground_(electricity) ground return] pins (A1, A12, B1, and B12)

In the PineNote UART schematic you can see (on the bottom right diagram labeled <code>USB_TYPEC_Male</code>) the side band pins are given the labels <code>UART2_TX_SUB1</code> for A8 and <code>UART2_RX_SUB2</code> for B8.
The first (TX) is used for transmitting data and the second (RX) is used for receiving data, from the perspective of the PineNote.
Also note the configuration channel pins labeled <code>TYPEC_CC1</code> for A5 and <code>TYPEC_CC2</code> for B5.
These pins are used to signal to the PineNote that a UART dongle is present.
The diagram shows they must be connected to a 3.3V source in parallel, mediated by resistors.
The schematic indicates 10,000 Ohm resistors, but community member talpadk experimented and found 1,000 Ohm resistors work better.
Our mission is to wire up pins from a USB-UART adapter to a USB-C breakout board following these requirements.

=== Buying components ===

There are many possible USB-C breakout board designs available for purchase online.
One particularly useful design is a "passthrough" or "intercept" style, with both male and female USB-C ports.
This design is more versatile in case you want to reuse it in other projects, and also enables you to connect to the PineNote via UART and USB at the same time.
An example of this product can be found [https://pmdway.com/products/usb-3-1-type-c-male-to-female-breakout-test-board here], although you are encouraged to shop around for cheaper options.
If you're fine with a bit more soldering, there is a very cheap one [https://www.ebay.com/itm/275407037613 here].

Similarly, there are many USB-UART adapter designs available.
These devices plug into your computer and expose a number of pins themselves, connecting to specific pins on the breakout board with jump wires.
It is important to get a 3.3V model, or at least a model with the option of 3.3V, as a 5V source might fry the PineNote.
[https://pmdway.com/products/usb-to-ttl-serial-cp2104-6-pin-converter-module Here] is one example with jump wires included, although you are again encouraged to shop around for alternatives.

All other necessary components of our UART dongle are readily & cheaply available in many locations.

=== Splicing resistors ===

[[File:PineNote-UART-Y-pull-up-resistor-cable.jpg|thumb|The desired end result; wrap removed from resistors for illustration purposes.]]

This is the only difficult part of the whole process.
Your goal is to create a Y-shaped jump wire with 1,000 Ohm through-hole resistors spliced into each of the twin arms.
The solitary leg will connect to a 3.3V source on your USB-UART adapter.
The twin arms will connect to the configuration channel pins on your USB-C breakout board.
This setup is called using pull-up resistors, and you can read a nice introduction to their purpose [https://www.electronics-tutorials.ws/logic/pull-up-resistor.html here].

For this project you'll need:
# A soldering iron with solder
# Wire cutters & strippers
# 2x jumper wires, male/female as compatible with your board designs
# 2x 1,000 Ohm through-hole resistors
# Electrical tape or heat shrink wrap

Consider buying extra jumper wires and resistors in case you mess up.
Also double-check that you have 1K resistors with [https://resistorcolorcodecalc.com/ this color code calculator].
Although the PineNote UART schematic says to use 10K Ohm resistors, community member talpadk experimented and found 1K is more appropriate.
Assemble your Y-cable as follows:
# Graft one jump wire onto the other to form a Y shape using [https://www.youtube.com/watch?v=KpiEfuhPqew this] technique, ensuring solitary leg end is compatible with your USB-UART adapter
# Splice resistors into the twin arms using [https://www.youtube.com/watch?v=RMgMVqqjPZ0 this] technique
# Splice remaining jump wire onto the ends of the resistors, ensuring ends are compatible with your USB-C breakout board
# Cover all exposed wire & resistors with electrical tape or heat shrink wrap

=== Assembly ===

Once you have acquired all necessary components, assemble the UART dongle as follows:
# Connect a jump wire from the GND pin on the USB-UART adapter to any one of the four GND pins on the USB-C breakout board (A1, A12, B1, or B12)
# Connect a jump wire from the RXD pin on the USB-UART adapter to the <code>UART2_TX_SUB1</code> SBU1 pin on the USB-C breakout board (A8)
# Connect a jump wire from the TXD pin on the USB-UART adapter to the <code>UART2_RX_SUB2</code> SBU2 pin on the USB-C breakout board (B8)
# Connect your Y-shaped jump wire from the 3.3V source pin on the USB-UART adapter to the CC1 and CC2 pins on the USB-C breakout board (A5 and B5)
# Wrap all metal connectors in electrical tape or heat shrink to prevent accidental shorts

Be '''very certain''' of your connections for the 3.3V source and its cable, as there is a real risk of irreparably frying your PineNote if they're wrong!
Especially be sure you are connecting to a 3.3V source and not a 5V source.

Note that if you mix up the TX/RX pins, it will still work but the USB-C breakout board will just plug into the PineNote upside down.
You can therefore choose which orientation you want by swapping the TX/RX pin connections.

== Using UART ==

First, use your UART dongle to physically connect your PineNote to your computer:
# Plug the USB-UART adapter into one of your computer's USB ports
# Plug the USB-C breakout board into the USB-C port on the bottom of your PineNote; the orientation matters, so try both and remember which one works

Once the hardware is connected, set up your computer's software as follows:
# Install [https://www.gnu.org/software/screen/ GNU Screen] (or [https://askubuntu.com/q/40959 some other option], but the instructions below are written for <code>screen</code>)
# Identify the USB-UART adapter in your <code>/dev</code> directory by running <code>ls /dev</code> with it plugged in, unplugging it, then again running <code>ls /dev</code> and seeing what changes; it is likely to be called <code>/dev/ttyUSB0</code>
# In a terminal window, run <code>screen -L /dev/ttyUSB0 1500000</code> (you may need to run this as sudo depending on your user's permissions; on most Linux distributions you need to be in the <code>dialout</code> usergroup)

Once the software is set up, power-cycle your PineNote; as the system boots you should see text appearing in your terminal window.
You can exit the screen session with <code>ctrl+a k</code> then pressing <code>y</code> to confirm.
The <code>screen -L</code> flag outputs a text log of the session to the current working directory, probably called <code>screenlog.0</code>.

==== Troubleshooting ====

If you don't see any text in your terminal as the PineNote boots, or the text is garbled, try the following:
* Ensure your GND, RX/TX, and CC jump wires are connected to the correct pins on both the USB-UART adapter and the USB-C breakout board
* Connect your USB-C breakout board to your PineNote in the opposite orientation
* Run the screen command as sudo in case your user doesn't have appropriate permissions
* Ensure you are setting the baud rate in the <code>screen</code> command to 1500000 (1.5 million)

== USB passthrough ==

If your USB-C breakout board has a passthrough/intercept design, you can connect to your PineNote over USB and UART at the same time.
This can be useful when you're doing development work on the PineNote boot process so you don't have to continually reconnect cables.
You'll need a USB-A to USB-C cable, connecting directly from your computer's USB-A hub to your USB-C breakout board's female USB-C port.
It's important to connect directly from USB-A, without any intermediate USB-C components.
Note that connecting a live USB cable to your USB-C breakout board in this way dramatically increases the danger of frying your PineNote with a short, so you should only do this if all connectors are safely wrapped in electrical tape.

[[Category:PineNote]]

PineNote

2023-10-14T02:20:25Z

Ahelwer: /* UART Dongle */

[[File:PineNote-1.jpg|400px|thumb|right|The PineNote]]

The '''PineNote''' is the first hybrid notepad computer device combination of notebook, tablet and e-reader using an e-ink panel. It is derived from the Quartz64 model A SBC and powered by a Rockchip RK3566 quad-core ARM Cortex A55 64-bit processor with a MALI G-52 GPU.

== Introduction ==

=== State of the software ===

The PineNote is based on the in 2021 released Rockchip RK3566 SoC. The upstreaming status of the SoC functionality can be found on the [[Quartz64 Development#Upstreaming Status|Quartz64 development]] wiki page of the Quartz64 single-board computer using the same SoC. In the [[PineNote_Development#Kernel_modules_/_mainlining_status|PineNote development]] wiki page you'll find the items specific for the PineNote.

The early adopter's batch of the PineNote is aimed solely at early adopters - more specifically, the units are solely intended to find their way into the hands of users with extensive Linux experience. If you’re looking to buy a PineNote in the first batch, you must expect to write software for it, not to write notes on it. The software shipping from the factory for the first batch will not be suitable for taking notes, reading e-books, or writing your dissertation. It may not even boot to a graphical environment.

An early version of a GNOME-based Debian image is available for [[PineNote_Software_Releases|testing]], but should not be expected to meet general-user readiness.

=== Help and support ===

Still have any questions regarding software, shipping, or ordering after reading this wiki? Please don't hesitate to contact the community in the bridged community channels for detailed answers or simply to chat with friendly people in the community! See [[Main Page#Community and Support]].

Please keep in mind that PINE64 is not like a regular company (see the [https://www.pine64.org/philosophy/ PINE64 philosophy]) and that support resources are limited - the best way to get support quickly is to ask in the community chat! Please only contact the PINE64 support directly if questions couldn't be solved via the community chat or this wiki.

== Software releases ==
While there are no robust and tested operating system releases for the PineNote available at this time, various linux distributions can be installed on the PineNote, with various degrees of working functionality.
Operating system software releases, or efforts to create them, can be found in the [[PineNote Software Releases]] section. Please join the development effort and help creating one.

== Development efforts ==

The following page discusses the development efforts for the PineNote:

* [[PineNote Development]] for general information regarding how to flash the device and other development information.

=== Software ===

* [[PineNote Development/Flashing]] for general flashing instructions of data to the PineNote
* [[PineNote Development/TODOs]]

==== Linux Kernel ====

* [[RK3566 EBC Reverse-Engineering]] for the EBC (eInk Panel) driver.
* [[PineNote Development/Building Kernel]]
* BSP Linux SDK version 4.19 for the PineNote and [[Quartz64|Quartz64 Model A]]:
** [http://files.pine64.org/SDK/Quartz64/QUARTZ64-model-A_BSP%20Linux.tar.gz Direct download] from ''pine64.org'' (32.67GB, MD5 of the TAR-GZip file ''24554419aec29700add97167a3a4c9ed'')
** [https://tmp.mwfc.info/pinenote/QUARTZ64-model-A_BSP%20Linux.tar.gz Mirror by mwfc]
** An unofficial torrent download provided by a community member of the BSP Linux and Android SDKs can be found [https://cdn.discordapp.com/attachments/870707390998282292/907726420204208148/pinenote.torrent here] (100GB).

==== User Space ====

* [[PineNote Development/Booting Linux]]

For tweaks and tricks see:
* [[PineNote Development/Software Tweaks]]

For app development see:
* [[PineNote Development/Apps]]

==== Android ====

Android 11 e-ink SDK for the PineNote and [[Quartz64|Quartz64 Model A]. This is the Android SDK build for 10.3" eink panels on Quartz64 Model A.

Download:
* [http://files.pine64.org/SDK/Quartz64/QUARTZ64-model-A_eink.android11_SDK.tar.gz Direct download] from ''pine64.org'' (72.88GB, MD5 of the TAR-GZip file ''293a550584298de4fb95ceae18103672'')
* [https://tmp.mwfc.info/pinenote/QUARTZ64-model-A_eink.android11_SDK.tar.gz Mirror by mwfc]
* An unofficial torrent download provided by a community member of the BSP Linux and Android SDKs can be found [https://cdn.discordapp.com/attachments/870707390998282292/907726420204208148/pinenote.torrent here] (100GB).
* Just the boot blobs (<1MB): [[File:Rk35-blobs.tar.gz]]

Notes:
* View [[Android SDK for RK3566]] for more information how to compile an image for the PineNote using this SDK

==== Related ====
* [[Quartz64 Development]] for the mainlining status of various functions on the Rockchip RK3566 SoC.

=== Hardware ===

This section includes discussions and their results regarding hardware changes and debugging of the PineNote.

==== Resolved issues ====

The following topics have resolved:

* [[PineNote/Hardware Changes/Closed Case UART]]
* '''Could the USB-C port support USB 3.1 5Gbps?''' Yes and no. The RK3566 only has a host-mode 5Gbps controller, meaning it can only negotiate such a high data rate with a device such as a flash drive. When the RK3566 is acting as a device, it only supports 480Mbps transfer rates. The hardware required to switch between these modes would raise the PineNote's price unreasonably. Therefore, the USB-C port will remain at USB 2.0 speeds for Host and Device mode.
* '''Could the USB-C port output DisplayPort?''' Yes and no. The hardware required to support such a feature would raise the PineNote's price unreasonably. Therefore, DisplayPort output will not be possible through the USB-C port.
* '''Where is the microSD card slot?''' The case design of the PineNote is fixed, making physical changes like adding a microSD card slot would raise the cost unreasonably.
* '''How will I install software to the PineNote?''' This is a hardware and software question. If the software on your PineNote is completely broken and cannot boot to a recoverable state, a Hall (magnet) sensor was fitted to the PineTab motherboard as U9009. This sensor is attached to SARADC_VIN0_KEY/RECOVERY on the RK3566. With the device powered off, and screen face down, holding a magnet over U9009 and plugging in a USB-C cable causes the device to boot into [http://opensource.rock-chips.com/wiki_Rockusb "rockusb"] flash mode. With proper flashing software and drivers, it should be possible to load a new operating system using rockusb if the system is soft-bricked. Of course, software vendors will need to be more careful with flashing firmware and providing useful "recovery" options on this device due to this process's relative difficulty to other PINE64 devices.
* [[PineNote/Battery Replacement]]

==== Unresolved issues ====

The following concerns have been brought up as open, unanswered topics:

* Does [https://en.wikipedia.org/wiki/USB-C#Audio_Adapter_Accessory_Mode_2|USB-C Audio Adapter Accessory Mode] work? It appears that the Headphone output of the audio codec was routed to the USB-C audio+USB switch, but it's unclear whether CC lines are hooked up correctly for detection of such a device. The PineNote hardware team will be testing this functionality soon (as of August 19, 2021). Note that Audio Accessory mode is detectable by reading the I2C registers of the WUSB3801Q. So connecting ASEL to a GPIO would be enough to get this working if it is not working already.
* Why is the Headphone output of the audio codec routed to the speakers? HPL_OUT is routed from the RK817 PMIC and audio codec to U9010 (the USB-C switch) and U6 (the audio amplifier). SPK_OUT is unused. It seems like SPK_OUT should be routed to U6 and HPL_OUT to U9010.
* Nitpick: The cold white charging LED bleeds through the gap between the rear case and the device's face. It does not bleed onto the screen, but it is jarring in low-light conditions or when the screen is amber. Could be resolved in software by turning off the charge LED when the screen is on.
* Is there any way to indicate when the device is in rockusb mode, such as connecting a certain magic pin to the power LED?
* The modem/4G connector (J6010) has its I2C and UART pins unconnected. Could those be connected to the SoC?

==== UART Dongle ====
{{Note|See main article: [[PineNote Development/UART]]}}

The USB UART dongle delivered with the PineNote allows you to have access to a serial port via USB-C Debug Accessory Mode (''DAM'') without having to open up the device.
The factory firmware runs at a baud rate of 1500000bps, 8 data bits 1 stop bit, no parity and no flow control. The USB-C male end should go into the PineNote and the female end can be connected with a standard USB-C cable to your computer.

It is relatively easy to build your own UART interface with a USB-C breakout board (for example https://www.ebay.com/itm/275407037613), two resistors and a 3.3V USB serial adapter. It is basically just two 1K pull up resistors (R3, R4), the data sheet values of 10K isn't whats on the real hardware, see the [https://files.pine64.org/doc/PineNote/PineNote_USB-C_Console_UART_breakout_board_schematic_v1.0_20210903.pdf schematic]. The pull ups enable the serial output on SBU1 and SBU2 you can use with any 3.3V USB serial adapter.

The UART dongle is not necessary to flash the PineNote, but is essential if something goes wrong to fix it without having to open the case.

You can flash premade images with the following links:
* https://github.com/m-weigand/pinenote_uboot_patching_dorians_backup (Note: this creates a U-Boot image to flash, do not worry about idblock.bin on the instructions for the next link)
* https://github.com/m-weigand/pinenote-debian-recipes/releases/

== Specification ==
[[File:PineNote_Pen_function.jpg|300px|right]]
[[File:PineNote_Cover-1.jpg|300px|right]]

=== General Information ===
* Dimensions: 191.1x232.5x7.4mm
* Weight: 438g

=== Core ===
* CPU: RK3566 1.8GHz 64-bit quad-core A55
* GPU: MALI G52 2EE
* System memory: 4GB LPDDR4
* Flash: 128GB eMMC

=== E-ink Display ===
* Size: 10.3"
* Resolution: 1404x1872
* DPI: 227
* Grayscale: 16
* Front Light: 36 level cold and warm
* Capacitive multi-touch panel
* EMR pen digitizer

=== Network ===
* WiFi: 2.4/5GHz 802.11a/b/g/n/ac
* Bluetooth: 5.0

=== Audio ===
* Built in stereo speakers
* 4 x DMIC microphone

=== Sensor ===
* G-Sensor for portrait and landscape sensing

=== Power ===
* 4000mAH LiPo battery
* DC 5V @ 3A USB-C connector

=== Accessories ===
* Optional EMR pen with magnetic attachment (included in the first production batch)
* Optional Cover (included in the first production batch)

== SoC and Memory Specifications ==
* Based on [https://www.rock-chips.com/a/en/products/RK35_Series/2021/0113/1274.html Rockchip RK3566]
[[File:RK3566_icon.png|right]]

=== CPU Architecture ===
* [https://developer.arm.com/ip-products/processors/cortex-a/cortex-a55 Quad-core ARM Cortex-A55@1.8GHz]
* AArch32 for full backwards compatibility with ARMv7
* ARM Neon Advanced SIMD (single instruction, multiple data) support for accelerated media and signal processing computation
* Includes VFP hardware to support single and double-precision operations
* ARMv8 Cryptography Extensions
* Integrated 32KB L1 instruction cache and 32KB L1 data cache per core
* 512KB unified system L3 cache
* [https://developer.arm.com/ip-products/security-ip/trustzone TrustZone] technology support
* [https://www.cnx-software.com/2020/12/01/rockchip-rk3568-processor-to-power-edge-computing-and-nvr-applications 22nm process, believed to be FD-SOI]

=== GPU (Graphics Processing Unit) Capabilities ===
* [https://developer.arm.com/ip-products/graphics-and-multimedia/mali-gpus/mali-g52-gpu Mali-G52 2EE Bifrost GPU@800MHz]
* 4x Multi-Sampling Anti-Aliasing (MSAA) with minimal performance drop
* 128KB L2 Cache configurations
* Supports OpenGL ES 1.1, 2.0, and 3.2
* Supports Vulkan 1.0 and 1.1
* Supports OpenCL 2.0 Full Profile
* Supports 1600 Mpix/s fill rate when at 800MHz clock frequency
* Supports 38.4 GLOP/s when at 800MHz clock frequency

=== NPU (Neural Processing Unit) Capabilities ===
* Neural network acceleration engine with processing performance of up to 0.8 TOPS
* Supports integer 8 and integer 16 convolution operations
* Supports the following deep learning frameworks: TensorFlow, TF-lite, Pytorch, Caffe, ONNX, MXNet, Keras, Darknet

=== System Memory ===
* RAM Memory : 4GB LPDDR4.
* Flash Memory: 128GB eMMC

== Information, Schematics, and Certifications ==

=== PineNote Developer kit version ===
Version v1.2 is the PineNote production version that was sold through the Pines64 store
* [https://files.pine64.org/doc/PineNote/PINENOTE_MAIN-V1R2%20-%20Schematic-20210824.pdf PineNote Mainboard Schematic ver 1.2 20210824 PDF file]
* [https://files.pine64.org/doc/PineNote/PINENOTE_USB-C-Board-V1.0-sch.pdf PineNote USB-C Daughter Board Schematic ver 1.0 PDF file]
* [https://files.pine64.org/doc/PineNote/PineNote_USB-C_Console_UART_breakout_board_schematic_v1.0_20210903.pdf PineNote USB-C Console UART Breakout Board Schematic ver 1.0 PDF file] Note: When building USB-C console breakout board, please be aware 10k CC pin pull-up is too weak to pull CC to logically high level. Replacing it to lower resistance, such as 1k is recommended.

The v1.1 is early release schematic just for reference only and used by developers who received the prototype.
* [https://files.pine64.org/doc/PineNote/PINENOTE_MAIN-V1R1%20-%20Schematic-20210726.pdf PineNote early released Schematic ver 1.1 20210726 PDF file]
* [https://files.pine64.org/doc/PineNote/PINENOTE_MAIN-V1R1-REF-TOP-20210726.pdf PineNote early released ver 1.1 20210726 PCB Connector placement PDF file]

Certifications:
* [https://files.pine64.org/doc/cert/PineNote%20FCC15C%20Certificate%20DTS-TC561262.pdf PineNote FCC-15C Certificate]
* [https://files.pine64.org/doc/cert/PineNote%20FCC15E%20Certificate%20NII-TC973072.pdf PineNote FCC-15E Certificate]
* [https://files.pine64.org/doc/cert/PineNote%20CE%20RED%20Certicate%20ET-21090682EC.pdf PineNote CE RED Certificate]
* [https://files.pine64.org/doc/cert/PineNote%20RoHS%20Certificate%20ET-210900082C.pdf PineNote ROHS Certificate]

== Datasheets for Components and Peripherals ==

Rockchip RK3566 SoC information:
* [https://files.pine64.org/doc/quartz64/Rockchip%20RK3566%20Datasheet%20V1.0-20201210.pdf Rockchip RK3566 ver 1.0 datasheet, release permission from Rockchip]

Rockchip RK817 PMU (Power Management Unit) Information:
* [https://www.rockchip.fr/RK817%20datasheet%20V1.01.pdf Rockchip RK817 version 1.01 datasheet]

LPDDR4 (200 Balls) SDRAM:
* ---

eMMC information:
* [https://en.biwin.com.cn/product/detail/6 Biwin 128GB eMMC model: BWCTASC41P128G]

E-ink Panel information:
* [https://files.pine64.org/doc/quartz64/Eink%20P-511-828-V1_ED103TC2%20Formal%20Spec%20V1.0_20190514.pdf E-Ink 10.3" 1872x1404 ED103TC2 Glass Panel Specification]
* [https://files.pine64.org/doc/datasheet/PineNote/TI%20PMU-TPS651851.pdf TPS65185x PMIC for E-Ink Enabled Electronic Paper Display Datasheet]

Touch Screen information:
* [https://files.pine64.org/doc/datasheet/PineNote/CYTMA448_Summary_RevC_5-26-16.pdf Cypress CYTMA448 multi-Point Capacitive Touch Controller Datasheet]
* Wacom Pen Digitizer Unit Model: SUDE-10S15MI-01X for 10.3" Display Module

WiFi/BT module information:
* [https://files.pine64.org/doc/datasheet/rockpro64/AW-CM256SM_DS_DF_V1.9_STD.pdf Azurewave CM256SM 11AC WiFi + Bluetooth5.0 Datasheet]]

G Sensor information:
* [http://www.silan.com.cn/en/product/details/47.html#app01 Silan SC7A20 3-Axis MEMS Accelerometer]

Audio Amplifier information:
* [https://files.pine64.org/doc/datasheet/PineNote/Awinic%20AW87318%20Class-K%20Audio%20Amp%20Datasheet.pdf Awinic AW87318 Class-K Audio Amp Datasheet]

== Resources ==
* [[PineNote Press]]

[[Category:PineNote]] [[Category:Rockchip RK3566]]

PineNote Development/UART

2023-10-14T02:17:48Z

Ahelwer:

[[File:Pinenote-uart-dongle.jpeg|thumb|Basic non-stock PineNote UART dongle]]

This page contains information on creating and using a [https://en.wikipedia.org/wiki/Universal_asynchronous_receiver-transmitter UART] dongle for the [[PineNote]].
The PineNote was shipped with a compatible UART dongle, but replacements are not available to order in case of loss or hardware fault.
Thankfully it is not difficult to make your own from easily-acquired components and a small bit of soldering.
Fear not if you've never soldered anything before!
This serves as an excellent first soldering project.
Borrow the tools from a friend, local hackerspace, or tool library.

A PineNote UART dongle enables you to:
# Interact with the system boot menu
# Read system events in real time as the PineNote is used
# Fix the PineNote without opening the case if something goes wrong while [[PineNote Development/Flashing|flashing it]]

Since the PineNote is an embedded system, interfacing with it during boot is more complicated than with an ordinary computer.
The UART dongle enables you to do this.

The PineNote factory firmware runs UART at a baud rate of 1500000 bps, 8 data bits, 1 stop bit, no parity and no flow control.
The process by which the PineNote design was modified to include closed-case UART is documented [[PineNote/Hardware Changes/Closed Case UART|here]].

== Stock dongle ==

The stock UART dongle included with the PineNote was a simple device plugging directly into the PineNote's USB-C port.
The dongle exposed a female USB-C port, which the user plugged into to get UART access.
This design unfortunately ruled out passthrough USB connections, where the user connects to the PineNote via UART and USB simultaneously.
The dongle is not currently available for purchase.

<gallery>
Pinenote-stock-uart-dongle-front.jpg|Front
Pinenote-stock-uart-dongle-back.jpg|Back
</gallery>

== Creating a dongle ==

A typical self-built PineNote UART dongle design has the following components:
# A USB-C breakout board with a male connector exposing the 24 pins of the PineNote's USB-C port
# A USB-UART adapter, to plug into a USB port of the computer you'll use to interface with the PineNote
# [https://en.wikipedia.org/wiki/Jump_wire Jump wires] to connect specific breakout board pins to pins on the USB-UART adapter
# Two 1,000 Ohm through-hole resistors to splice into the jump wires
# Electrical tape or heat shrink to wrap connectors and prevent shorts

You will also need the following tools:
# Soldering iron with solder
# Wire cutters & strippers

The PineNote's internal UART system is documented in [https://files.pine64.org/doc/PineNote/PineNote_USB-C_Console_UART_breakout_board_schematic_v1.0_20210903.pdf this schematic].
The purpose of all 24 USB-C pins is documented [https://en.wikipedia.org/wiki/USB-C#Receptacles on the USB-C Wikipedia page].
We are interested in three sets of pins:
# The SBU1 (A8) and SBU2 (B8) side band use pins
# The CC1 (A5) and CC2 (B5) configuration channel pins
# The GND [https://en.wikipedia.org/wiki/Ground_(electricity) ground return] pins (A1, A12, B1, and B12)

In the PineNote UART schematic you can see (on the bottom right diagram labeled <code>USB_TYPEC_Male</code>) the side band pins are given the labels <code>UART2_TX_SUB1</code> for A8 and <code>UART2_RX_SUB2</code> for B8.
The first (TX) is used for transmitting data and the second (RX) is used for receiving data, from the perspective of the PineNote.
Also note the configuration channel pins labeled <code>TYPEC_CC1</code> for A5 and <code>TYPEC_CC2</code> for B5.
These pins are used to signal to the PineNote that a UART dongle is present.
The diagram shows they must be connected to a 3.3V source in parallel, mediated by resistors.
The schematic indicates 10,000 Ohm resistors, but community member talpadk experimented and found 1,000 Ohm resistors work better.
Our mission is to wire up pins from a USB-UART adapter to a USB-C breakout board following these requirements.

=== Buying components ===

There are many possible USB-C breakout board designs available for purchase online.
One particularly useful design is a "passthrough" or "intercept" style, with both male and female USB-C ports.
This design is more versatile in case you want to reuse it in other projects, and also enables you to connect to the PineNote via UART and USB at the same time.
An example of this product can be found [https://pmdway.com/products/usb-3-1-type-c-male-to-female-breakout-test-board here], although you are encouraged to shop around for cheaper options.
If you're fine with a bit more soldering, there is a very cheap one [https://www.ebay.com/itm/275407037613 here].

Similarly, there are many USB-UART adapter designs available.
These devices plug into your computer and expose a number of pins themselves, connecting to specific pins on the breakout board with jump wires.
It is important to get a 3.3V model, or at least a model with the option of 3.3V, as a 5V source might fry the PineNote.
[https://pmdway.com/products/usb-to-ttl-serial-cp2104-6-pin-converter-module Here] is one example with jump wires included, although you are again encouraged to shop around for alternatives.

All other necessary components of our UART dongle are readily & cheaply available in many locations.

=== Splicing resistors ===

[[File:PineNote-UART-Y-pull-up-resistor-cable.jpg|thumb|The desired end result; wrap removed from resistors for illustration purposes.]]

This is the only difficult part of the whole process.
Your goal is to create a Y-shaped jump wire with 1,000 Ohm through-hole resistors spliced into each of the twin arms.
The solitary leg will connect to a 3.3V source on your USB-UART adapter.
The twin arms will connect to the configuration channel pins on your USB-C breakout board.
This setup is called using pull-up resistors, and you can read a nice introduction to their purpose [https://www.electronics-tutorials.ws/logic/pull-up-resistor.html here].

For this project you'll need:
# A soldering iron with solder
# Wire cutters & strippers
# 2x jumper wires, male/female as compatible with your board designs
# 2x 1,000 Ohm through-hole resistors
# Electrical tape or heat shrink wrap

Consider buying extra jumper wires and resistors in case you mess up.
Also double-check that you have 1K resistors with [https://resistorcolorcodecalc.com/ this color code calculator].
Although the PineNote UART schematic says to use 10K Ohm resistors, community member talpadk experimented and found 1K is more appropriate.
Assemble your Y-cable as follows:
# Graft one jump wire onto the other to form a Y shape using [https://www.youtube.com/watch?v=KpiEfuhPqew this] technique, ensuring solitary leg end is compatible with your USB-UART adapter
# Splice resistors into the twin arms using [https://www.youtube.com/watch?v=RMgMVqqjPZ0 this] technique
# Splice remaining jump wire onto the ends of the resistors, ensuring ends are compatible with your USB-C breakout board
# Cover all exposed wire & resistors with electrical tape or heat shrink wrap

=== Assembly ===

Once you have acquired all necessary components, assemble the UART dongle as follows:
# Connect a jump wire from the GND pin on the USB-UART adapter to any one of the four GND pins on the USB-C breakout board (A1, A12, B1, or B12)
# Connect a jump wire from the RXD pin on the USB-UART adapter to the <code>UART2_TX_SUB1</code> SBU1 pin on the USB-C breakout board (A8)
# Connect a jump wire from the TXD pin on the USB-UART adapter to the <code>UART2_RX_SUB2</code> SBU2 pin on the USB-C breakout board (B8)
# Connect your Y-shaped jump wire from the 3.3V source pin on the USB-UART adapter to the CC1 and CC2 pins on the USB-C breakout board (A5 and B5)
# Wrap all metal connectors in electrical tape or heat shrink to prevent accidental shorts

Be '''very certain''' of your connections for the 3.3V source and its cable, as there is a real risk of irreparably frying your PineNote if they're wrong!
Especially be sure you are connecting to a 3.3V source and not a 5V source.

Note that if you mix up the TX/RX pins, it will still work but the USB-C breakout board will just plug into the PineNote upside down.
You can therefore choose which orientation you want by swapping the TX/RX pin connections.

== Using UART ==

First, use your UART dongle to physically connect your PineNote to your computer:
# Plug the USB-UART adapter into one of your computer's USB ports
# Plug the USB-C breakout board into the USB-C port on the bottom of your PineNote; the orientation matters, so try both and remember which one works

Once the hardware is connected, set up your computer's software as follows:
# Install [https://www.gnu.org/software/screen/ GNU Screen] (or [https://askubuntu.com/q/40959 some other option], but the instructions below are written for <code>screen</code>)
# Identify the USB-UART adapter in your <code>/dev</code> directory by running <code>ls /dev</code> with it plugged in, unplugging it, then again running <code>ls /dev</code> and seeing what changes; it is likely to be called <code>/dev/ttyUSB0</code>
# In a terminal window, run <code>screen -L /dev/ttyUSB0 1500000</code> (you may need to run this as sudo depending on your user's permissions; on most Linux distributions you need to be in the <code>dialout</code> usergroup)

Once the software is set up, power-cycle your PineNote; as the system boots you should see text appearing in your terminal window.
You can exit the screen session with <code>ctrl+a k</code> then pressing <code>y</code> to confirm.
The <code>screen -L</code> flag outputs a text log of the session to the current working directory, probably called <code>screenlog.0</code>.

==== Troubleshooting ====

If you don't see any text in your terminal as the PineNote boots, or the text is garbled, try the following:
* Ensure your GND, RX and TX jump wires are connected to the correct pins on both the USB-UART adapter and the USB-C breakout board
* Connect your USB-C breakout board to your PineNote in the opposite orientation
* Run the screen command as sudo in case your user doesn't have appropriate permissions
* Ensure you are setting the baud rate in the <code>screen</code> command to 1500000 (1.5 million)

== USB passthrough ==

If your USB-C breakout board has a passthrough/intercept design, you can connect to your PineNote over USB and UART at the same time.
This can be useful when you're doing development work on the PineNote boot process so you don't have to continually reconnect cables.
You'll need a USB-A to USB-C cable, connecting directly from your computer's USB-A hub to your USB-C breakout board's female USB-C port.
It's important to connect directly from USB-A, without any intermediate USB-C components.
Note that connecting a live USB cable to your USB-C breakout board in this way dramatically increases the danger of frying your PineNote with a short, so you should only do this if all connectors are safely wrapped in electrical tape.

[[Category:PineNote]]

PineNote Development/Flashing

2023-10-14T02:14:19Z

Ahelwer: /* Exit */

{{Under construction}}

{{Info|These instructions are directed towards experienced developers only!}}

This page contains information on flashing software to the [https://wiki.pine64.org/wiki/PineNote PineNote].

Currently, software can be flashed using rkdeveloptool or from the factory Android installation (UART shell, adb, or fastboot).

== Getting <code>rkdeveloptool</code> ==

Most flashing operations on the PineNote are done through <code>rkdeveloptool</code>, a command line utility built on libusb.
PINE64 maintains its own fork [https://gitlab.com/pine64-org/quartz-bsp/rkdeveloptool here] that you will need to get.
The repo's README contains a list of dependencies (libusb 1.0) and instructions for building the tool.

Installing (not just building) <code>rkdeveloptool</code> will configure PAM to elevate privileges where necessary on your system; you can configure this manually as follows:
<pre>
sudo cp 99-rk-rockusb.rules /etc/udev/rules.d/
sudo udevadm control --reload
</pre>

== Entering Maskrom/Rockusb mode ==

Interfacing with the PineNote over USB using <code>rkdeveloptool</code> requires first booting the PineNote into [http://opensource.rock-chips.com/wiki_Rockusb an alternative operating mode] called Maskrom or Rockusb mode.

=== Possible methods ===

There are three possible methods of entering Maskrom/Rockusb mode:

==== Hardware magnet switch ====

# Connect the PineNote to your computer via USB and boot the PineNote into Android
# Locate & identify the small circular marking on the back of the PineNote, in the top right quadrant; have the PineNote pen close at hand, or any other small magnet
# Hold the PineNote power button to bring up the reboot/shutdown menu; select reboot, then place the PineNote face down with the "eraser" end of the pen (or your magnet) resting on the small circular marking

<gallery>
Download mode.jpeg|Pen method
PineNoteMagnetOnBack.jpg|Magnet method
</gallery>

==== U-Boot terminal ====
This method requires a [[PineNote_Development/UART#USB_passthrough|UART dongle with passthrough]] allowing simultaneous UART & USB connections.
It is nice because you can easily switch back & forth between U-Boot and Rockusb without having to physically manipulate the PineNote or its connectors; this is especially helpful when trying to develop U-Boot.

# Connect to the PineNote via UART and USB simultaneously
# Interrupt the U-Boot startup using <code>ctrl+c</code> sent over UART
# In the U-Boot terminal over UART, run <code>rockusb 0 mmc 0</code>

The UART terminal should print <code>RKUSB</code> then a spinner will appear.
You can exit back to the U-Boot terminal by sending <code>ctrl+c</code> again.

==== 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]]

=== Success ===

No matter what approach you take, you can tell whether you succeeded by running the <code>lsusb</code> command on your computer:
* If you find the entry <code>2207:0018 Fuzhou Rockchip Electronics Company rk3566_eink</code> in the list, the process did not succeed; reboot and retry
* The entry <code>2207:350a Fuzhou Rockchip Electronics Company</code> will occur if you detach then reattach the USB-C cable while the PineNote is in Maskrom/Rockusb mode; <code>rkdeveloptool</code> won't work and you will have to do a hard reboot (hold down power button for 30 seconds to shutdown)
* If you find the entry <code>2207:350a Fuzhou Rockchip Electronics Company USB download gadget</code> then the process succeeded

You can also look at the output of the <code>rkdeveloptool list</code> command:
* If this prints out <code>No devices in rockusb mode found</code> the process did not succeed; reboot and retry
* If this prints out <code>DevNo=1 Vid=0x2207,Pid=0x350a,LocationID=305 Maskrom</code> then you probably detached/reattached the USB-C cable while in Maskrom/Rockusb mode and <code>rkdeveloptool</code> won't work; perform a hard reboot to fix
* If this prints out <code>DevNo=1 Vid=0x2207,Pid=0x350a,LocationID=303 Loader</code> then the process succeeded

=== Exiting ===

You can boot the PineNote back into its normal mode of operation by powercycling the PineNote with its hardware power switch, or running the <code>rkdeveloptool reboot</code> command.
If you used the magnetic switch method be sure to remove the pen/magnet before rebooting.

== Backup ==

A backup of the content of the internal eMMC before anything gets messed up is '''mandatory'''.

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

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) contain data you may also 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.

This process was developed by Dorian Rudolph, originally described [https://github.com/DorianRudolph/pinenotes here].

=== List partitions ===

First, run <code>rkdeveloptool list-partitions</code> to print out your PineNote's partitions to get an idea of what you're dealing with.
The stock PineNote has a fairly standard Android partition setup, including:
* uboot: the [https://en.wikipedia.org/wiki/Das_U-Boot U-Boot] embedded systems bootloader
* trust: secrets that can be encrypted with a key stored in the [https://en.wikipedia.org/wiki/Trusted_Platform_Module TPM]
* waveform: important files controlling the e-ink screen's state changes
* misc: miscellaneous files needed by the firmware
* dtbo: [https://en.wikipedia.org/wiki/Devicetree Device Tree Blob for Overlay], files describing the PineNote's hardware configuration
* vbmeta: data required for verified boot
* boot, security, recovery, backup, cache, metadata, super, logo, device
* userdata: the big one; this is where all your files are stored in the stock Android install

=== Patch U-Boot ===

Before we can back up our partitions, we have a problem to solve.
The version of U-Boot installed on the stock PineNote contains a bug where it can't dump partitions beyond 32 MB (above that limit all bytes in the dump are just <code>0xCC</code>), meaning the PineNote must be flashed with a fixed version of U-Boot before it is possible to take a backup of the larger partitions.
It is possible to extract and modify the U-Boot image from your PineNote if you're interested in some light reverse-engineering (following Dorian's notes), or you can simply download a patched U-Boot image directly [https://github.com/DorianRudolph/pinenotes/blob/main/static/uboot_patched.img here].

Once you've acquired a patched U-Boot image, run:
# <code>rkdeveloptool read-partition uboot uboot_backup.img</code>
# <code>rkdeveloptool write-partition uboot uboot_patched.img</code>
# <code>rkdeveloptool reboot</code>

=== Taking the backup ===

There is a second backup limit preventing dumping partitions larger than 2 GB, this time from <code>rkdeveloptool</code>.
This means if you have a large number of documents in the Android userdata partition they might not all make it into the backup.
If you don't have many documents (or don't care about losing them) this should not be a problem.
If you do have a lot of documents, workarounds include:
* A possible patch written by Thomas exists [https://github.com/tpwrules/nixos-pinenote/blob/96d2c9158edb9da59afcb952cc864fada18382f9/nix/rkdeveloptool/0001-fix-large-dumps.patch here] but has not yet been upstreamed; consider investigating how to get the patch tested & upstreamed, or just apply it to your own local copy of <code>rkdeveloptool</code>
* Use [https://github.com/talpadk/pinenote-backup this] Python script written by Visti Andresen to automatically backup your entire partition by splitting reads into 2 GB chunks

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].

=== 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.

== 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 ==

=== 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 current version (current as of 2022-01-02), there might have to be made 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>

You can now download u-boot onto the PineNote:

./rkdeveloptool boot ../u-boot-rockchip/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

{{Note|'''TODO:''' Section needs to be finished}}

=== 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 [[PineNote Development/Flashing#Creating a mainline boot image|Creating a mainline boot image]], 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 or
* get a U-Boot prompt and run <code>fastboot usb 0</code>.

[[Category:PineNote]]

PineNote Development/Flashing

2023-10-14T02:13:59Z

Ahelwer: /* Entering Maskrom/Rockusb mode */

{{Under construction}}

{{Info|These instructions are directed towards experienced developers only!}}

This page contains information on flashing software to the [https://wiki.pine64.org/wiki/PineNote PineNote].

Currently, software can be flashed using rkdeveloptool or from the factory Android installation (UART shell, adb, or fastboot).

== Getting <code>rkdeveloptool</code> ==

Most flashing operations on the PineNote are done through <code>rkdeveloptool</code>, a command line utility built on libusb.
PINE64 maintains its own fork [https://gitlab.com/pine64-org/quartz-bsp/rkdeveloptool here] that you will need to get.
The repo's README contains a list of dependencies (libusb 1.0) and instructions for building the tool.

Installing (not just building) <code>rkdeveloptool</code> will configure PAM to elevate privileges where necessary on your system; you can configure this manually as follows:
<pre>
sudo cp 99-rk-rockusb.rules /etc/udev/rules.d/
sudo udevadm control --reload
</pre>

== Entering Maskrom/Rockusb mode ==

Interfacing with the PineNote over USB using <code>rkdeveloptool</code> requires first booting the PineNote into [http://opensource.rock-chips.com/wiki_Rockusb an alternative operating mode] called Maskrom or Rockusb mode.

=== Possible methods ===

There are three possible methods of entering Maskrom/Rockusb mode:

==== Hardware magnet switch ====

# Connect the PineNote to your computer via USB and boot the PineNote into Android
# Locate & identify the small circular marking on the back of the PineNote, in the top right quadrant; have the PineNote pen close at hand, or any other small magnet
# Hold the PineNote power button to bring up the reboot/shutdown menu; select reboot, then place the PineNote face down with the "eraser" end of the pen (or your magnet) resting on the small circular marking

<gallery>
Download mode.jpeg|Pen method
PineNoteMagnetOnBack.jpg|Magnet method
</gallery>

==== U-Boot terminal ====
This method requires a [[PineNote_Development/UART#USB_passthrough|UART dongle with passthrough]] allowing simultaneous UART & USB connections.
It is nice because you can easily switch back & forth between U-Boot and Rockusb without having to physically manipulate the PineNote or its connectors; this is especially helpful when trying to develop U-Boot.

# Connect to the PineNote via UART and USB simultaneously
# Interrupt the U-Boot startup using <code>ctrl+c</code> sent over UART
# In the U-Boot terminal over UART, run <code>rockusb 0 mmc 0</code>

The UART terminal should print <code>RKUSB</code> then a spinner will appear.
You can exit back to the U-Boot terminal by sending <code>ctrl+c</code> again.

==== 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]]

=== Success ===

No matter what approach you take, you can tell whether you succeeded by running the <code>lsusb</code> command on your computer:
* If you find the entry <code>2207:0018 Fuzhou Rockchip Electronics Company rk3566_eink</code> in the list, the process did not succeed; reboot and retry
* The entry <code>2207:350a Fuzhou Rockchip Electronics Company</code> will occur if you detach then reattach the USB-C cable while the PineNote is in Maskrom/Rockusb mode; <code>rkdeveloptool</code> won't work and you will have to do a hard reboot (hold down power button for 30 seconds to shutdown)
* If you find the entry <code>2207:350a Fuzhou Rockchip Electronics Company USB download gadget</code> then the process succeeded

You can also look at the output of the <code>rkdeveloptool list</code> command:
* If this prints out <code>No devices in rockusb mode found</code> the process did not succeed; reboot and retry
* If this prints out <code>DevNo=1 Vid=0x2207,Pid=0x350a,LocationID=305 Maskrom</code> then you probably detached/reattached the USB-C cable while in Maskrom/Rockusb mode and <code>rkdeveloptool</code> won't work; perform a hard reboot to fix
* If this prints out <code>DevNo=1 Vid=0x2207,Pid=0x350a,LocationID=303 Loader</code> then the process succeeded

=== Exit ===

You can boot the PineNote back into its normal mode of operation by powercycling the PineNote with its hardware power switch, or running the <code>rkdeveloptool reboot</code> command.
If you used the magnetic switch method be sure to remove the pen/magnet before rebooting.

== Backup ==

A backup of the content of the internal eMMC before anything gets messed up is '''mandatory'''.

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

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) contain data you may also 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.

This process was developed by Dorian Rudolph, originally described [https://github.com/DorianRudolph/pinenotes here].

=== List partitions ===

First, run <code>rkdeveloptool list-partitions</code> to print out your PineNote's partitions to get an idea of what you're dealing with.
The stock PineNote has a fairly standard Android partition setup, including:
* uboot: the [https://en.wikipedia.org/wiki/Das_U-Boot U-Boot] embedded systems bootloader
* trust: secrets that can be encrypted with a key stored in the [https://en.wikipedia.org/wiki/Trusted_Platform_Module TPM]
* waveform: important files controlling the e-ink screen's state changes
* misc: miscellaneous files needed by the firmware
* dtbo: [https://en.wikipedia.org/wiki/Devicetree Device Tree Blob for Overlay], files describing the PineNote's hardware configuration
* vbmeta: data required for verified boot
* boot, security, recovery, backup, cache, metadata, super, logo, device
* userdata: the big one; this is where all your files are stored in the stock Android install

=== Patch U-Boot ===

Before we can back up our partitions, we have a problem to solve.
The version of U-Boot installed on the stock PineNote contains a bug where it can't dump partitions beyond 32 MB (above that limit all bytes in the dump are just <code>0xCC</code>), meaning the PineNote must be flashed with a fixed version of U-Boot before it is possible to take a backup of the larger partitions.
It is possible to extract and modify the U-Boot image from your PineNote if you're interested in some light reverse-engineering (following Dorian's notes), or you can simply download a patched U-Boot image directly [https://github.com/DorianRudolph/pinenotes/blob/main/static/uboot_patched.img here].

Once you've acquired a patched U-Boot image, run:
# <code>rkdeveloptool read-partition uboot uboot_backup.img</code>
# <code>rkdeveloptool write-partition uboot uboot_patched.img</code>
# <code>rkdeveloptool reboot</code>

=== Taking the backup ===

There is a second backup limit preventing dumping partitions larger than 2 GB, this time from <code>rkdeveloptool</code>.
This means if you have a large number of documents in the Android userdata partition they might not all make it into the backup.
If you don't have many documents (or don't care about losing them) this should not be a problem.
If you do have a lot of documents, workarounds include:
* A possible patch written by Thomas exists [https://github.com/tpwrules/nixos-pinenote/blob/96d2c9158edb9da59afcb952cc864fada18382f9/nix/rkdeveloptool/0001-fix-large-dumps.patch here] but has not yet been upstreamed; consider investigating how to get the patch tested & upstreamed, or just apply it to your own local copy of <code>rkdeveloptool</code>
* Use [https://github.com/talpadk/pinenote-backup this] Python script written by Visti Andresen to automatically backup your entire partition by splitting reads into 2 GB chunks

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].

=== 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.

== 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 ==

=== 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 current version (current as of 2022-01-02), there might have to be made 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>

You can now download u-boot onto the PineNote:

./rkdeveloptool boot ../u-boot-rockchip/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

{{Note|'''TODO:''' Section needs to be finished}}

=== 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 [[PineNote Development/Flashing#Creating a mainline boot image|Creating a mainline boot image]], 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 or
* get a U-Boot prompt and run <code>fastboot usb 0</code>.

[[Category:PineNote]]

PineNote Development/Flashing

2023-10-14T02:12:42Z

Ahelwer: /* U-Boot */

{{Under construction}}

{{Info|These instructions are directed towards experienced developers only!}}

This page contains information on flashing software to the [https://wiki.pine64.org/wiki/PineNote PineNote].

Currently, software can be flashed using rkdeveloptool or from the factory Android installation (UART shell, adb, or fastboot).

== Getting <code>rkdeveloptool</code> ==

Most flashing operations on the PineNote are done through <code>rkdeveloptool</code>, a command line utility built on libusb.
PINE64 maintains its own fork [https://gitlab.com/pine64-org/quartz-bsp/rkdeveloptool here] that you will need to get.
The repo's README contains a list of dependencies (libusb 1.0) and instructions for building the tool.

Installing (not just building) <code>rkdeveloptool</code> will configure PAM to elevate privileges where necessary on your system; you can configure this manually as follows:
<pre>
sudo cp 99-rk-rockusb.rules /etc/udev/rules.d/
sudo udevadm control --reload
</pre>

== Entering Maskrom/Rockusb mode ==

Interfacing with the PineNote over USB using <code>rkdeveloptool</code> requires first booting the PineNote into [http://opensource.rock-chips.com/wiki_Rockusb an alternative operating mode] called Maskrom or Rockusb mode.

=== Possible Methods ===

There are three possible methods of entering Maskrom/Rockusb mode:

==== Hardware Magnet Switch ====

# Connect the PineNote to your computer via USB and boot the PineNote into Android
# Locate & identify the small circular marking on the back of the PineNote, in the top right quadrant; have the PineNote pen close at hand, or any other small magnet
# Hold the PineNote power button to bring up the reboot/shutdown menu; select reboot, then place the PineNote face down with the "eraser" end of the pen (or your magnet) resting on the small circular marking

<gallery>
Download mode.jpeg|Pen method
PineNoteMagnetOnBack.jpg|Magnet method
</gallery>

==== U-Boot ====
This method requires a [[PineNote_Development/UART#USB_passthrough|UART dongle with passthrough]] allowing simultaneous UART & USB connections.
It is nice because you can easily switch back & forth between U-Boot and Rockusb without having to physically manipulate the PineNote or its connectors; this is especially helpful when trying to develop U-Boot.

# Connect to the PineNote via UART and USB simultaneously
# Interrupt the U-Boot startup using <code>ctrl+c</code> sent over UART
# In the U-Boot terminal over UART, run <code>rockusb 0 mmc 0</code>

The UART terminal should print <code>RKUSB</code> then a spinner will appear.
You can exit back to the U-Boot terminal by sending <code>ctrl+c</code> again.

==== 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]]

=== Success ===

No matter what approach you take, you can tell whether you succeeded by running the <code>lsusb</code> command on your computer:
* If you find the entry <code>2207:0018 Fuzhou Rockchip Electronics Company rk3566_eink</code> in the list, the process did not succeed; reboot and retry
* The entry <code>2207:350a Fuzhou Rockchip Electronics Company</code> will occur if you detach then reattach the USB-C cable while the PineNote is in Maskrom/Rockusb mode; <code>rkdeveloptool</code> won't work and you will have to do a hard reboot (hold down power button for 30 seconds to shutdown)
* If you find the entry <code>2207:350a Fuzhou Rockchip Electronics Company USB download gadget</code> then the process succeeded

You can also look at the output of the <code>rkdeveloptool list</code> command:
* If this prints out <code>No devices in rockusb mode found</code> the process did not succeed; reboot and retry
* If this prints out <code>DevNo=1 Vid=0x2207,Pid=0x350a,LocationID=305 Maskrom</code> then you probably detached/reattached the USB-C cable while in Maskrom/Rockusb mode and <code>rkdeveloptool</code> won't work; perform a hard reboot to fix
* If this prints out <code>DevNo=1 Vid=0x2207,Pid=0x350a,LocationID=303 Loader</code> then the process succeeded

=== Exiting mode ===

You can boot the PineNote back into its normal mode of operation by powercycling the PineNote with its hardware power switch, or running the <code>rkdeveloptool reboot</code> command.
If you used the magnetic switch method be sure to remove the pen/magnet before rebooting.

== Backup ==

A backup of the content of the internal eMMC before anything gets messed up is '''mandatory'''.

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

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) contain data you may also 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.

This process was developed by Dorian Rudolph, originally described [https://github.com/DorianRudolph/pinenotes here].

=== List partitions ===

First, run <code>rkdeveloptool list-partitions</code> to print out your PineNote's partitions to get an idea of what you're dealing with.
The stock PineNote has a fairly standard Android partition setup, including:
* uboot: the [https://en.wikipedia.org/wiki/Das_U-Boot U-Boot] embedded systems bootloader
* trust: secrets that can be encrypted with a key stored in the [https://en.wikipedia.org/wiki/Trusted_Platform_Module TPM]
* waveform: important files controlling the e-ink screen's state changes
* misc: miscellaneous files needed by the firmware
* dtbo: [https://en.wikipedia.org/wiki/Devicetree Device Tree Blob for Overlay], files describing the PineNote's hardware configuration
* vbmeta: data required for verified boot
* boot, security, recovery, backup, cache, metadata, super, logo, device
* userdata: the big one; this is where all your files are stored in the stock Android install

=== Patch U-Boot ===

Before we can back up our partitions, we have a problem to solve.
The version of U-Boot installed on the stock PineNote contains a bug where it can't dump partitions beyond 32 MB (above that limit all bytes in the dump are just <code>0xCC</code>), meaning the PineNote must be flashed with a fixed version of U-Boot before it is possible to take a backup of the larger partitions.
It is possible to extract and modify the U-Boot image from your PineNote if you're interested in some light reverse-engineering (following Dorian's notes), or you can simply download a patched U-Boot image directly [https://github.com/DorianRudolph/pinenotes/blob/main/static/uboot_patched.img here].

Once you've acquired a patched U-Boot image, run:
# <code>rkdeveloptool read-partition uboot uboot_backup.img</code>
# <code>rkdeveloptool write-partition uboot uboot_patched.img</code>
# <code>rkdeveloptool reboot</code>

=== Taking the backup ===

There is a second backup limit preventing dumping partitions larger than 2 GB, this time from <code>rkdeveloptool</code>.
This means if you have a large number of documents in the Android userdata partition they might not all make it into the backup.
If you don't have many documents (or don't care about losing them) this should not be a problem.
If you do have a lot of documents, workarounds include:
* A possible patch written by Thomas exists [https://github.com/tpwrules/nixos-pinenote/blob/96d2c9158edb9da59afcb952cc864fada18382f9/nix/rkdeveloptool/0001-fix-large-dumps.patch here] but has not yet been upstreamed; consider investigating how to get the patch tested & upstreamed, or just apply it to your own local copy of <code>rkdeveloptool</code>
* Use [https://github.com/talpadk/pinenote-backup this] Python script written by Visti Andresen to automatically backup your entire partition by splitting reads into 2 GB chunks

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].

=== 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.

== 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 ==

=== 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 current version (current as of 2022-01-02), there might have to be made 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>

You can now download u-boot onto the PineNote:

./rkdeveloptool boot ../u-boot-rockchip/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

{{Note|'''TODO:''' Section needs to be finished}}

=== 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 [[PineNote Development/Flashing#Creating a mainline boot image|Creating a mainline boot image]], 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 or
* get a U-Boot prompt and run <code>fastboot usb 0</code>.

[[Category:PineNote]]

PineNote Development/Flashing

2023-10-14T02:10:11Z

Ahelwer: /* U-Boot */

{{Under construction}}

{{Info|These instructions are directed towards experienced developers only!}}

This page contains information on flashing software to the [https://wiki.pine64.org/wiki/PineNote PineNote].

Currently, software can be flashed using rkdeveloptool or from the factory Android installation (UART shell, adb, or fastboot).

== Getting <code>rkdeveloptool</code> ==

Most flashing operations on the PineNote are done through <code>rkdeveloptool</code>, a command line utility built on libusb.
PINE64 maintains its own fork [https://gitlab.com/pine64-org/quartz-bsp/rkdeveloptool here] that you will need to get.
The repo's README contains a list of dependencies (libusb 1.0) and instructions for building the tool.

Installing (not just building) <code>rkdeveloptool</code> will configure PAM to elevate privileges where necessary on your system; you can configure this manually as follows:
<pre>
sudo cp 99-rk-rockusb.rules /etc/udev/rules.d/
sudo udevadm control --reload
</pre>

== Entering Maskrom/Rockusb mode ==

Interfacing with the PineNote over USB using <code>rkdeveloptool</code> requires first booting the PineNote into [http://opensource.rock-chips.com/wiki_Rockusb an alternative operating mode] called Maskrom or Rockusb mode.

=== Possible Methods ===

There are three possible methods of entering Maskrom/Rockusb mode:

==== Hardware Magnet Switch ====

# Connect the PineNote to your computer via USB and boot the PineNote into Android
# Locate & identify the small circular marking on the back of the PineNote, in the top right quadrant; have the PineNote pen close at hand, or any other small magnet
# Hold the PineNote power button to bring up the reboot/shutdown menu; select reboot, then place the PineNote face down with the "eraser" end of the pen (or your magnet) resting on the small circular marking

<gallery>
Download mode.jpeg|Pen method
PineNoteMagnetOnBack.jpg|Magnet method
</gallery>

==== U-Boot ====
This method requires a [[PineNote_Development/UART#USB_passthrough|UART dongle with passthrough]] allowing simultaneous UART & USB connections.
It is nice because you can easily switch back & forth between U-Boot and Rockusb without having to physically manipulate the PineNote or its connectors; this is especially helpful when trying to develop U-Boot.

# Connect to the PineNote via UART and USB simultaneously
# Interrupt the U-Boot startup using <code>ctrl-c</code> sent over UART
# In the U-Boot terminal over UART, run <code>rockusb 0 mmc 0</code>

==== 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]]

=== Success ===

No matter what approach you take, you can tell whether you succeeded by running the <code>lsusb</code> command on your computer:
* If you find the entry <code>2207:0018 Fuzhou Rockchip Electronics Company rk3566_eink</code> in the list, the process did not succeed; reboot and retry
* The entry <code>2207:350a Fuzhou Rockchip Electronics Company</code> will occur if you detach then reattach the USB-C cable while the PineNote is in Maskrom/Rockusb mode; <code>rkdeveloptool</code> won't work and you will have to do a hard reboot (hold down power button for 30 seconds to shutdown)
* If you find the entry <code>2207:350a Fuzhou Rockchip Electronics Company USB download gadget</code> then the process succeeded

You can also look at the output of the <code>rkdeveloptool list</code> command:
* If this prints out <code>No devices in rockusb mode found</code> the process did not succeed; reboot and retry
* If this prints out <code>DevNo=1 Vid=0x2207,Pid=0x350a,LocationID=305 Maskrom</code> then you probably detached/reattached the USB-C cable while in Maskrom/Rockusb mode and <code>rkdeveloptool</code> won't work; perform a hard reboot to fix
* If this prints out <code>DevNo=1 Vid=0x2207,Pid=0x350a,LocationID=303 Loader</code> then the process succeeded

=== Exiting mode ===

You can boot the PineNote back into its normal mode of operation by powercycling the PineNote with its hardware power switch, or running the <code>rkdeveloptool reboot</code> command.
If you used the magnetic switch method be sure to remove the pen/magnet before rebooting.

== Backup ==

A backup of the content of the internal eMMC before anything gets messed up is '''mandatory'''.

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

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) contain data you may also 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.

This process was developed by Dorian Rudolph, originally described [https://github.com/DorianRudolph/pinenotes here].

=== List partitions ===

First, run <code>rkdeveloptool list-partitions</code> to print out your PineNote's partitions to get an idea of what you're dealing with.
The stock PineNote has a fairly standard Android partition setup, including:
* uboot: the [https://en.wikipedia.org/wiki/Das_U-Boot U-Boot] embedded systems bootloader
* trust: secrets that can be encrypted with a key stored in the [https://en.wikipedia.org/wiki/Trusted_Platform_Module TPM]
* waveform: important files controlling the e-ink screen's state changes
* misc: miscellaneous files needed by the firmware
* dtbo: [https://en.wikipedia.org/wiki/Devicetree Device Tree Blob for Overlay], files describing the PineNote's hardware configuration
* vbmeta: data required for verified boot
* boot, security, recovery, backup, cache, metadata, super, logo, device
* userdata: the big one; this is where all your files are stored in the stock Android install

=== Patch U-Boot ===

Before we can back up our partitions, we have a problem to solve.
The version of U-Boot installed on the stock PineNote contains a bug where it can't dump partitions beyond 32 MB (above that limit all bytes in the dump are just <code>0xCC</code>), meaning the PineNote must be flashed with a fixed version of U-Boot before it is possible to take a backup of the larger partitions.
It is possible to extract and modify the U-Boot image from your PineNote if you're interested in some light reverse-engineering (following Dorian's notes), or you can simply download a patched U-Boot image directly [https://github.com/DorianRudolph/pinenotes/blob/main/static/uboot_patched.img here].

Once you've acquired a patched U-Boot image, run:
# <code>rkdeveloptool read-partition uboot uboot_backup.img</code>
# <code>rkdeveloptool write-partition uboot uboot_patched.img</code>
# <code>rkdeveloptool reboot</code>

=== Taking the backup ===

There is a second backup limit preventing dumping partitions larger than 2 GB, this time from <code>rkdeveloptool</code>.
This means if you have a large number of documents in the Android userdata partition they might not all make it into the backup.
If you don't have many documents (or don't care about losing them) this should not be a problem.
If you do have a lot of documents, workarounds include:
* A possible patch written by Thomas exists [https://github.com/tpwrules/nixos-pinenote/blob/96d2c9158edb9da59afcb952cc864fada18382f9/nix/rkdeveloptool/0001-fix-large-dumps.patch here] but has not yet been upstreamed; consider investigating how to get the patch tested & upstreamed, or just apply it to your own local copy of <code>rkdeveloptool</code>
* Use [https://github.com/talpadk/pinenote-backup this] Python script written by Visti Andresen to automatically backup your entire partition by splitting reads into 2 GB chunks

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].

=== 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.

== 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 ==

=== 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 current version (current as of 2022-01-02), there might have to be made 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>

You can now download u-boot onto the PineNote:

./rkdeveloptool boot ../u-boot-rockchip/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

{{Note|'''TODO:''' Section needs to be finished}}

=== 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 [[PineNote Development/Flashing#Creating a mainline boot image|Creating a mainline boot image]], 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 or
* get a U-Boot prompt and run <code>fastboot usb 0</code>.

[[Category:PineNote]]

PineNote Development/UART

2023-10-14T01:46:24Z

Ahelwer: /* Assembly */

[[File:Pinenote-uart-dongle.jpeg|thumb|Basic non-stock PineNote UART dongle]]

This page contains information on creating and using a [https://en.wikipedia.org/wiki/Universal_asynchronous_receiver-transmitter UART] dongle for the [[PineNote]].
The PineNote was shipped with a compatible UART dongle, but replacements are not available to order in case of loss or hardware fault.
Thankfully it is not difficult to make your own from easily-acquired components and a small bit of soldering.
Fear not if you've never soldered anything before!
This serves as an excellent first soldering project.
Borrow the tools from a friend or a local hackerspace or tool library.

A PineNote UART dongle enables you to:
# Interact with the system boot menu
# Read system events in real time as the PineNote is used
# Fix the PineNote without opening the case if something goes wrong while [[PineNote Development/Flashing|flashing it]]

Since the PineNote is an embedded system, interfacing with it during boot is more complicated than with an ordinary computer.
The UART dongle enables you to do this.

The PineNote factory firmware runs UART at a baud rate of 1500000 bps, 8 data bits, 1 stop bit, no parity and no flow control.
The process by which the PineNote design was modified to include closed-case UART is documented [[PineNote/Hardware Changes/Closed Case UART|here]].

== Stock dongle ==

The stock UART dongle included with the PineNote was a simple device plugging directly into the PineNote's USB-C port.
The dongle exposed a female USB-C port, which the user plugged into to get UART access.
This design unfortunately ruled out passthrough USB connections, where the user connects to the PineNote via UART and USB simultaneously.
The dongle is not currently available for purchase.

<gallery>
Pinenote-stock-uart-dongle-front.jpg|Front
Pinenote-stock-uart-dongle-back.jpg|Back
</gallery>

== Creating a dongle ==

A typical self-built PineNote UART dongle design has the following components:
# A USB-C breakout board with a male connector exposing the 24 pins of the PineNote's USB-C port
# A USB-UART adapter, to plug into a USB port of the computer you'll use to interface with the PineNote
# [https://en.wikipedia.org/wiki/Jump_wire Jump wires] to connect specific breakout board pins to pins on the USB-UART adapter
# Two 1,000 Ohm through-hole resistors to splice into the jump wires
# Electrical tape or heat shrink to wrap connectors and prevent shorts

You will also need the following tools:
# Soldering iron with solder
# Wire cutters & strippers

The PineNote's internal UART system is documented in [https://files.pine64.org/doc/PineNote/PineNote_USB-C_Console_UART_breakout_board_schematic_v1.0_20210903.pdf this schematic].
The purpose of all 24 USB-C pins is documented [https://en.wikipedia.org/wiki/USB-C#Receptacles on the USB-C Wikipedia page].
We are interested in three sets of pins:
# The SBU1 (A8) and SBU2 (B8) side band use pins
# The CC1 (A5) and CC2 (B5) configuration channel pins
# The GND [https://en.wikipedia.org/wiki/Ground_(electricity) ground return] pins (A1, A12, B1, and B12)

In the PineNote UART schematic you can see (on the bottom right diagram labeled <code>USB_TYPEC_Male</code>) the side band pins are given the labels <code>UART2_TX_SUB1</code> for A8 and <code>UART2_RX_SUB2</code> for B8.
The first (TX) is used for transmitting data and the second (RX) is used for receiving data, from the perspective of the PineNote.
Also note the configuration channel pins labeled <code>TYPEC_CC1</code> for A5 and <code>TYPEC_CC2</code> for B5.
These pins are used to signal to the PineNote that a UART dongle is present.
The diagram shows they must be connected to a 3.3V source in parallel, mediated by resistors.
The schematic indicates 10,000 Ohm resistors, but community member talpadk experimented and found 1,000 Ohm resistors work better.
Our mission is to wire up pins from a USB-UART adapter to a USB-C breakout board following these requirements.

=== Buying components ===

There are many possible USB-C breakout board designs available for purchase online.
One particularly useful design is a "passthrough" or "intercept" style, with both male and female USB-C ports.
This design is more versatile in case you want to reuse it in other projects, and also enables you to connect to the PineNote via UART and USB at the same time.
An example of this product can be found [https://pmdway.com/products/usb-3-1-type-c-male-to-female-breakout-test-board here], although you are encouraged to shop around for cheaper options.
If you're fine with a bit more soldering, there is a very cheap one [https://www.ebay.com/itm/275407037613 here].

Similarly, there are many USB-UART adapter designs available.
These devices plug into your computer and expose a number of pins themselves, connecting to specific pins on the breakout board with jump wires.
It is important to get a 3.3V model, or at least a model with the option of 3.3V, as a 5V source might fry the PineNote.
[https://pmdway.com/products/usb-to-ttl-serial-cp2104-6-pin-converter-module Here] is one example with jump wires included, although you are again encouraged to shop around for alternatives.

All other necessary components of our UART dongle are readily & cheaply available in many locations.

=== Splicing resistors ===

[[File:PineNote-UART-Y-pull-up-resistor-cable.jpg|thumb|The desired end result; wrap removed from resistors for illustration purposes.]]

This is the only difficult part of the whole process.
Your goal is to create a Y-shaped jump wire with 1,000 Ohm through-hole resistors spliced into each of the twin arms.
The solitary leg will connect to a 3.3V source on your USB-UART adapter.
The twin arms will connect to the configuration channel pins on your USB-C breakout board.
This setup is called using pull-up resistors, and you can read a nice introduction to their purpose [https://www.electronics-tutorials.ws/logic/pull-up-resistor.html here].

For this project you'll need:
# A soldering iron with solder
# Wire cutters & strippers
# 2x jumper wires, male/female as compatible with your board designs
# 2x 1,000 Ohm through-hole resistors
# Electrical tape or heat shrink wrap

Consider buying extra jumper wires and resistors in case you mess up.
Also double-check that you have 1K resistors with [https://resistorcolorcodecalc.com/ this color code calculator].
Although the PineNote UART schematic says to use 10K Ohm resistors, community member talpadk experimented and found 1K is more appropriate.
Assemble your Y-cable as follows:
# Graft one jump wire onto the other to form a Y shape using [https://www.youtube.com/watch?v=KpiEfuhPqew this] technique, ensuring solitary leg end is compatible with your USB-UART adapter
# Splice resistors into the twin arms using [https://www.youtube.com/watch?v=RMgMVqqjPZ0 this] technique
# Splice remaining jump wire onto the ends of the resistors, ensuring ends are compatible with your USB-C breakout board
# Cover all exposed wire & resistors with electrical tape or heat shrink wrap

=== Assembly ===

Once you have acquired all necessary components, assemble the UART dongle as follows:
# Connect a jump wire from the GND pin on the USB-UART adapter to any one of the four GND pins on the USB-C breakout board (A1, A12, B1, or B12)
# Connect a jump wire from the RXD pin on the USB-UART adapter to the <code>UART2_TX_SUB1</code> SBU1 pin on the USB-C breakout board (A8)
# Connect a jump wire from the TXD pin on the USB-UART adapter to the <code>UART2_RX_SUB2</code> SBU2 pin on the USB-C breakout board (B8)
# Connect your Y-shaped jump wire from the 3.3V source pin on the USB-UART adapter to the CC1 and CC2 pins on the USB-C breakout board (A5 and B5)
# Wrap all metal connectors in electrical tape or heat shrink to prevent accidental shorts

Be '''very certain''' of your connections for the 3.3V source and its cable, as there is a real risk of irreparably frying your PineNote if they're wrong!
Especially be sure you are connecting to a 3.3V source and not a 5V source.

Note that if you mix up the TX/RX pins, it will still work but the USB-C breakout board will just plug into the PineNote upside down.
You can therefore choose which orientation you want by swapping the TX/RX pin connections.

== Using UART ==

First, use your UART dongle to physically connect your PineNote to your computer:
# Plug the USB-UART adapter into one of your computer's USB ports
# Plug the USB-C breakout board into the USB-C port on the bottom of your PineNote; the orientation matters, so try both and remember which one works

Once the hardware is connected, set up your computer's software as follows:
# Install [https://www.gnu.org/software/screen/ GNU Screen] (or [https://askubuntu.com/q/40959 some other option], but the instructions below are written for <code>screen</code>)
# Identify the USB-UART adapter in your <code>/dev</code> directory by running <code>ls /dev</code> with it plugged in, unplugging it, then again running <code>ls /dev</code> and seeing what changes; it is likely to be called <code>/dev/ttyUSB0</code>
# In a terminal window, run <code>screen -L /dev/ttyUSB0 1500000</code> (you may need to run this as sudo depending on your user's permissions; on most Linux distributions you need to be in the <code>dialout</code> usergroup)

Once the software is set up, power-cycle your PineNote; as the system boots you should see text appearing in your terminal window.
You can exit the screen session with <code>ctrl+a k</code> then pressing <code>y</code> to confirm.
The <code>screen -L</code> flag outputs a text log of the session to the current working directory, probably called <code>screenlog.0</code>.

==== Troubleshooting ====

If you don't see any text in your terminal as the PineNote boots, or the text is garbled, try the following:
* Ensure your GND, RX and TX jump wires are connected to the correct pins on both the USB-UART adapter and the USB-C breakout board
* Connect your USB-C breakout board to your PineNote in the opposite orientation
* Run the screen command as sudo in case your user doesn't have appropriate permissions
* Ensure you are setting the baud rate in the <code>screen</code> command to 1500000 (1.5 million)

== USB passthrough ==

If your USB-C breakout board has a passthrough/intercept design, you can connect to your PineNote over USB and UART at the same time.
This can be useful when you're doing development work on the PineNote boot process so you don't have to continually reconnect cables.
You'll need a USB-A to USB-C cable, connecting directly from your computer's USB-A hub to your USB-C breakout board's female USB-C port.
It's important to connect directly from USB-A, without any intermediate USB-C components.
Note that connecting a live USB cable to your USB-C breakout board in this way dramatically increases the danger of frying your PineNote with a short, so you should only do this if all connectors are safely wrapped in electrical tape.

[[Category:PineNote]]

PineNote Development/UART

2023-10-14T01:45:36Z

Ahelwer: /* Assembly */

[[File:Pinenote-uart-dongle.jpeg|thumb|Basic non-stock PineNote UART dongle]]

This page contains information on creating and using a [https://en.wikipedia.org/wiki/Universal_asynchronous_receiver-transmitter UART] dongle for the [[PineNote]].
The PineNote was shipped with a compatible UART dongle, but replacements are not available to order in case of loss or hardware fault.
Thankfully it is not difficult to make your own from easily-acquired components and a small bit of soldering.
Fear not if you've never soldered anything before!
This serves as an excellent first soldering project.
Borrow the tools from a friend or a local hackerspace or tool library.

A PineNote UART dongle enables you to:
# Interact with the system boot menu
# Read system events in real time as the PineNote is used
# Fix the PineNote without opening the case if something goes wrong while [[PineNote Development/Flashing|flashing it]]

Since the PineNote is an embedded system, interfacing with it during boot is more complicated than with an ordinary computer.
The UART dongle enables you to do this.

The PineNote factory firmware runs UART at a baud rate of 1500000 bps, 8 data bits, 1 stop bit, no parity and no flow control.
The process by which the PineNote design was modified to include closed-case UART is documented [[PineNote/Hardware Changes/Closed Case UART|here]].

== Stock dongle ==

The stock UART dongle included with the PineNote was a simple device plugging directly into the PineNote's USB-C port.
The dongle exposed a female USB-C port, which the user plugged into to get UART access.
This design unfortunately ruled out passthrough USB connections, where the user connects to the PineNote via UART and USB simultaneously.
The dongle is not currently available for purchase.

<gallery>
Pinenote-stock-uart-dongle-front.jpg|Front
Pinenote-stock-uart-dongle-back.jpg|Back
</gallery>

== Creating a dongle ==

A typical self-built PineNote UART dongle design has the following components:
# A USB-C breakout board with a male connector exposing the 24 pins of the PineNote's USB-C port
# A USB-UART adapter, to plug into a USB port of the computer you'll use to interface with the PineNote
# [https://en.wikipedia.org/wiki/Jump_wire Jump wires] to connect specific breakout board pins to pins on the USB-UART adapter
# Two 1,000 Ohm through-hole resistors to splice into the jump wires
# Electrical tape or heat shrink to wrap connectors and prevent shorts

You will also need the following tools:
# Soldering iron with solder
# Wire cutters & strippers

The PineNote's internal UART system is documented in [https://files.pine64.org/doc/PineNote/PineNote_USB-C_Console_UART_breakout_board_schematic_v1.0_20210903.pdf this schematic].
The purpose of all 24 USB-C pins is documented [https://en.wikipedia.org/wiki/USB-C#Receptacles on the USB-C Wikipedia page].
We are interested in three sets of pins:
# The SBU1 (A8) and SBU2 (B8) side band use pins
# The CC1 (A5) and CC2 (B5) configuration channel pins
# The GND [https://en.wikipedia.org/wiki/Ground_(electricity) ground return] pins (A1, A12, B1, and B12)

In the PineNote UART schematic you can see (on the bottom right diagram labeled <code>USB_TYPEC_Male</code>) the side band pins are given the labels <code>UART2_TX_SUB1</code> for A8 and <code>UART2_RX_SUB2</code> for B8.
The first (TX) is used for transmitting data and the second (RX) is used for receiving data, from the perspective of the PineNote.
Also note the configuration channel pins labeled <code>TYPEC_CC1</code> for A5 and <code>TYPEC_CC2</code> for B5.
These pins are used to signal to the PineNote that a UART dongle is present.
The diagram shows they must be connected to a 3.3V source in parallel, mediated by resistors.
The schematic indicates 10,000 Ohm resistors, but community member talpadk experimented and found 1,000 Ohm resistors work better.
Our mission is to wire up pins from a USB-UART adapter to a USB-C breakout board following these requirements.

=== Buying components ===

There are many possible USB-C breakout board designs available for purchase online.
One particularly useful design is a "passthrough" or "intercept" style, with both male and female USB-C ports.
This design is more versatile in case you want to reuse it in other projects, and also enables you to connect to the PineNote via UART and USB at the same time.
An example of this product can be found [https://pmdway.com/products/usb-3-1-type-c-male-to-female-breakout-test-board here], although you are encouraged to shop around for cheaper options.
If you're fine with a bit more soldering, there is a very cheap one [https://www.ebay.com/itm/275407037613 here].

Similarly, there are many USB-UART adapter designs available.
These devices plug into your computer and expose a number of pins themselves, connecting to specific pins on the breakout board with jump wires.
It is important to get a 3.3V model, or at least a model with the option of 3.3V, as a 5V source might fry the PineNote.
[https://pmdway.com/products/usb-to-ttl-serial-cp2104-6-pin-converter-module Here] is one example with jump wires included, although you are again encouraged to shop around for alternatives.

All other necessary components of our UART dongle are readily & cheaply available in many locations.

=== Splicing resistors ===

[[File:PineNote-UART-Y-pull-up-resistor-cable.jpg|thumb|The desired end result; wrap removed from resistors for illustration purposes.]]

This is the only difficult part of the whole process.
Your goal is to create a Y-shaped jump wire with 1,000 Ohm through-hole resistors spliced into each of the twin arms.
The solitary leg will connect to a 3.3V source on your USB-UART adapter.
The twin arms will connect to the configuration channel pins on your USB-C breakout board.
This setup is called using pull-up resistors, and you can read a nice introduction to their purpose [https://www.electronics-tutorials.ws/logic/pull-up-resistor.html here].

For this project you'll need:
# A soldering iron with solder
# Wire cutters & strippers
# 2x jumper wires, male/female as compatible with your board designs
# 2x 1,000 Ohm through-hole resistors
# Electrical tape or heat shrink wrap

Consider buying extra jumper wires and resistors in case you mess up.
Also double-check that you have 1K resistors with [https://resistorcolorcodecalc.com/ this color code calculator].
Although the PineNote UART schematic says to use 10K Ohm resistors, community member talpadk experimented and found 1K is more appropriate.
Assemble your Y-cable as follows:
# Graft one jump wire onto the other to form a Y shape using [https://www.youtube.com/watch?v=KpiEfuhPqew this] technique, ensuring solitary leg end is compatible with your USB-UART adapter
# Splice resistors into the twin arms using [https://www.youtube.com/watch?v=RMgMVqqjPZ0 this] technique
# Splice remaining jump wire onto the ends of the resistors, ensuring ends are compatible with your USB-C breakout board
# Cover all exposed wire & resistors with electrical tape or heat shrink wrap

=== Assembly ===

Once you have acquired all necessary components, assemble the UART dongle as follows:
# Connect a jump wire from the GND pin on the USB-UART adapter to any one of the four GND pins on the USB-C breakout board (A1, A12, B1, or B12)
# Connect a jump wire from the RXD pin on the USB-UART adapter to the <code>UART2_TX_SUB1</code> SBU1 pin on the USB-C breakout board (A8)
# Connect a jump wire from the TXD pin on the USB-UART adapter to the <code>UART2_RX_SUB2</code> SBU2 pin on the USB-C breakout board (B8)
# Connect your Y-shaped jump wire from the 3.3V source pin on the USB-UART adapter to the CC1 and CC2 pins on the USB-C breakout board (A5 and B5)
# Wrap all metal connectors in electrical tape or heat shrink to prevent accidental shorts

Be '''very certain''' of your connections for the 3.3V source, as there is a real risk of irreparably frying your PineNote if they're wrong!
Especially be sure you are connecting to a 3.3V source and not a 5V source.

Note that if you mix up the TX/RX pins, it will still work but the USB-C breakout board will just plug into the PineNote upside down.
You can therefore choose which orientation you want by swapping the TX/RX pin connections.

== Using UART ==

First, use your UART dongle to physically connect your PineNote to your computer:
# Plug the USB-UART adapter into one of your computer's USB ports
# Plug the USB-C breakout board into the USB-C port on the bottom of your PineNote; the orientation matters, so try both and remember which one works

Once the hardware is connected, set up your computer's software as follows:
# Install [https://www.gnu.org/software/screen/ GNU Screen] (or [https://askubuntu.com/q/40959 some other option], but the instructions below are written for <code>screen</code>)
# Identify the USB-UART adapter in your <code>/dev</code> directory by running <code>ls /dev</code> with it plugged in, unplugging it, then again running <code>ls /dev</code> and seeing what changes; it is likely to be called <code>/dev/ttyUSB0</code>
# In a terminal window, run <code>screen -L /dev/ttyUSB0 1500000</code> (you may need to run this as sudo depending on your user's permissions; on most Linux distributions you need to be in the <code>dialout</code> usergroup)

Once the software is set up, power-cycle your PineNote; as the system boots you should see text appearing in your terminal window.
You can exit the screen session with <code>ctrl+a k</code> then pressing <code>y</code> to confirm.
The <code>screen -L</code> flag outputs a text log of the session to the current working directory, probably called <code>screenlog.0</code>.

==== Troubleshooting ====

If you don't see any text in your terminal as the PineNote boots, or the text is garbled, try the following:
* Ensure your GND, RX and TX jump wires are connected to the correct pins on both the USB-UART adapter and the USB-C breakout board
* Connect your USB-C breakout board to your PineNote in the opposite orientation
* Run the screen command as sudo in case your user doesn't have appropriate permissions
* Ensure you are setting the baud rate in the <code>screen</code> command to 1500000 (1.5 million)

== USB passthrough ==

If your USB-C breakout board has a passthrough/intercept design, you can connect to your PineNote over USB and UART at the same time.
This can be useful when you're doing development work on the PineNote boot process so you don't have to continually reconnect cables.
You'll need a USB-A to USB-C cable, connecting directly from your computer's USB-A hub to your USB-C breakout board's female USB-C port.
It's important to connect directly from USB-A, without any intermediate USB-C components.
Note that connecting a live USB cable to your USB-C breakout board in this way dramatically increases the danger of frying your PineNote with a short, so you should only do this if all connectors are safely wrapped in electrical tape.

[[Category:PineNote]]

PineNote Development/UART

2023-10-14T01:44:34Z

Ahelwer: /* Assembly */

[[File:Pinenote-uart-dongle.jpeg|thumb|Basic non-stock PineNote UART dongle]]

This page contains information on creating and using a [https://en.wikipedia.org/wiki/Universal_asynchronous_receiver-transmitter UART] dongle for the [[PineNote]].
The PineNote was shipped with a compatible UART dongle, but replacements are not available to order in case of loss or hardware fault.
Thankfully it is not difficult to make your own from easily-acquired components and a small bit of soldering.
Fear not if you've never soldered anything before!
This serves as an excellent first soldering project.
Borrow the tools from a friend or a local hackerspace or tool library.

A PineNote UART dongle enables you to:
# Interact with the system boot menu
# Read system events in real time as the PineNote is used
# Fix the PineNote without opening the case if something goes wrong while [[PineNote Development/Flashing|flashing it]]

Since the PineNote is an embedded system, interfacing with it during boot is more complicated than with an ordinary computer.
The UART dongle enables you to do this.

The PineNote factory firmware runs UART at a baud rate of 1500000 bps, 8 data bits, 1 stop bit, no parity and no flow control.
The process by which the PineNote design was modified to include closed-case UART is documented [[PineNote/Hardware Changes/Closed Case UART|here]].

== Stock dongle ==

The stock UART dongle included with the PineNote was a simple device plugging directly into the PineNote's USB-C port.
The dongle exposed a female USB-C port, which the user plugged into to get UART access.
This design unfortunately ruled out passthrough USB connections, where the user connects to the PineNote via UART and USB simultaneously.
The dongle is not currently available for purchase.

<gallery>
Pinenote-stock-uart-dongle-front.jpg|Front
Pinenote-stock-uart-dongle-back.jpg|Back
</gallery>

== Creating a dongle ==

A typical self-built PineNote UART dongle design has the following components:
# A USB-C breakout board with a male connector exposing the 24 pins of the PineNote's USB-C port
# A USB-UART adapter, to plug into a USB port of the computer you'll use to interface with the PineNote
# [https://en.wikipedia.org/wiki/Jump_wire Jump wires] to connect specific breakout board pins to pins on the USB-UART adapter
# Two 1,000 Ohm through-hole resistors to splice into the jump wires
# Electrical tape or heat shrink to wrap connectors and prevent shorts

You will also need the following tools:
# Soldering iron with solder
# Wire cutters & strippers

The PineNote's internal UART system is documented in [https://files.pine64.org/doc/PineNote/PineNote_USB-C_Console_UART_breakout_board_schematic_v1.0_20210903.pdf this schematic].
The purpose of all 24 USB-C pins is documented [https://en.wikipedia.org/wiki/USB-C#Receptacles on the USB-C Wikipedia page].
We are interested in three sets of pins:
# The SBU1 (A8) and SBU2 (B8) side band use pins
# The CC1 (A5) and CC2 (B5) configuration channel pins
# The GND [https://en.wikipedia.org/wiki/Ground_(electricity) ground return] pins (A1, A12, B1, and B12)

In the PineNote UART schematic you can see (on the bottom right diagram labeled <code>USB_TYPEC_Male</code>) the side band pins are given the labels <code>UART2_TX_SUB1</code> for A8 and <code>UART2_RX_SUB2</code> for B8.
The first (TX) is used for transmitting data and the second (RX) is used for receiving data, from the perspective of the PineNote.
Also note the configuration channel pins labeled <code>TYPEC_CC1</code> for A5 and <code>TYPEC_CC2</code> for B5.
These pins are used to signal to the PineNote that a UART dongle is present.
The diagram shows they must be connected to a 3.3V source in parallel, mediated by resistors.
The schematic indicates 10,000 Ohm resistors, but community member talpadk experimented and found 1,000 Ohm resistors work better.
Our mission is to wire up pins from a USB-UART adapter to a USB-C breakout board following these requirements.

=== Buying components ===

There are many possible USB-C breakout board designs available for purchase online.
One particularly useful design is a "passthrough" or "intercept" style, with both male and female USB-C ports.
This design is more versatile in case you want to reuse it in other projects, and also enables you to connect to the PineNote via UART and USB at the same time.
An example of this product can be found [https://pmdway.com/products/usb-3-1-type-c-male-to-female-breakout-test-board here], although you are encouraged to shop around for cheaper options.
If you're fine with a bit more soldering, there is a very cheap one [https://www.ebay.com/itm/275407037613 here].

Similarly, there are many USB-UART adapter designs available.
These devices plug into your computer and expose a number of pins themselves, connecting to specific pins on the breakout board with jump wires.
It is important to get a 3.3V model, or at least a model with the option of 3.3V, as a 5V source might fry the PineNote.
[https://pmdway.com/products/usb-to-ttl-serial-cp2104-6-pin-converter-module Here] is one example with jump wires included, although you are again encouraged to shop around for alternatives.

All other necessary components of our UART dongle are readily & cheaply available in many locations.

=== Splicing resistors ===

[[File:PineNote-UART-Y-pull-up-resistor-cable.jpg|thumb|The desired end result; wrap removed from resistors for illustration purposes.]]

This is the only difficult part of the whole process.
Your goal is to create a Y-shaped jump wire with 1,000 Ohm through-hole resistors spliced into each of the twin arms.
The solitary leg will connect to a 3.3V source on your USB-UART adapter.
The twin arms will connect to the configuration channel pins on your USB-C breakout board.
This setup is called using pull-up resistors, and you can read a nice introduction to their purpose [https://www.electronics-tutorials.ws/logic/pull-up-resistor.html here].

For this project you'll need:
# A soldering iron with solder
# Wire cutters & strippers
# 2x jumper wires, male/female as compatible with your board designs
# 2x 1,000 Ohm through-hole resistors
# Electrical tape or heat shrink wrap

Consider buying extra jumper wires and resistors in case you mess up.
Also double-check that you have 1K resistors with [https://resistorcolorcodecalc.com/ this color code calculator].
Although the PineNote UART schematic says to use 10K Ohm resistors, community member talpadk experimented and found 1K is more appropriate.
Assemble your Y-cable as follows:
# Graft one jump wire onto the other to form a Y shape using [https://www.youtube.com/watch?v=KpiEfuhPqew this] technique, ensuring solitary leg end is compatible with your USB-UART adapter
# Splice resistors into the twin arms using [https://www.youtube.com/watch?v=RMgMVqqjPZ0 this] technique
# Splice remaining jump wire onto the ends of the resistors, ensuring ends are compatible with your USB-C breakout board
# Cover all exposed wire & resistors with electrical tape or heat shrink wrap

=== Assembly ===

Once you have acquired all necessary components, assemble the UART dongle as follows:
# Connect a jump wire from the GND pin on the USB-UART adapter to any one of the four GND pins on the USB-C breakout board (A1, A12, B1, or B12)
# Connect a jump wire from the RXD pin on the USB-UART adapter to the TX SBU1 pin on the USB-C breakout board (A8)
# Connect a jump wire from the TXD pin on the USB-UART adapter to the RX SBU2 pin on the USB-C breakout board (B8)
# Connect your Y-shaped jump wire from the 3.3V source pin on the USB-UART adapter to the CC1 and CC2 pins on the USB-C breakout board (A5 and B5)
# Wrap all metal connectors in electrical tape or heat shrink to prevent accidental shorts

Be '''very certain''' of your connections for the 3.3V source, as there is a real risk of irreparably frying your PineNote if they're wrong!
Especially be sure you are connecting to a 3.3V source and not a 5V source.

Note that if you mix up the TX/RX pins, it will still work but the USB-C breakout board will just plug into the PineNote upside down.
You can therefore choose which orientation you want by swapping the TX/RX pin connections.

== Using UART ==

First, use your UART dongle to physically connect your PineNote to your computer:
# Plug the USB-UART adapter into one of your computer's USB ports
# Plug the USB-C breakout board into the USB-C port on the bottom of your PineNote; the orientation matters, so try both and remember which one works

Once the hardware is connected, set up your computer's software as follows:
# Install [https://www.gnu.org/software/screen/ GNU Screen] (or [https://askubuntu.com/q/40959 some other option], but the instructions below are written for <code>screen</code>)
# Identify the USB-UART adapter in your <code>/dev</code> directory by running <code>ls /dev</code> with it plugged in, unplugging it, then again running <code>ls /dev</code> and seeing what changes; it is likely to be called <code>/dev/ttyUSB0</code>
# In a terminal window, run <code>screen -L /dev/ttyUSB0 1500000</code> (you may need to run this as sudo depending on your user's permissions; on most Linux distributions you need to be in the <code>dialout</code> usergroup)

Once the software is set up, power-cycle your PineNote; as the system boots you should see text appearing in your terminal window.
You can exit the screen session with <code>ctrl+a k</code> then pressing <code>y</code> to confirm.
The <code>screen -L</code> flag outputs a text log of the session to the current working directory, probably called <code>screenlog.0</code>.

==== Troubleshooting ====

If you don't see any text in your terminal as the PineNote boots, or the text is garbled, try the following:
* Ensure your GND, RX and TX jump wires are connected to the correct pins on both the USB-UART adapter and the USB-C breakout board
* Connect your USB-C breakout board to your PineNote in the opposite orientation
* Run the screen command as sudo in case your user doesn't have appropriate permissions
* Ensure you are setting the baud rate in the <code>screen</code> command to 1500000 (1.5 million)

== USB passthrough ==

If your USB-C breakout board has a passthrough/intercept design, you can connect to your PineNote over USB and UART at the same time.
This can be useful when you're doing development work on the PineNote boot process so you don't have to continually reconnect cables.
You'll need a USB-A to USB-C cable, connecting directly from your computer's USB-A hub to your USB-C breakout board's female USB-C port.
It's important to connect directly from USB-A, without any intermediate USB-C components.
Note that connecting a live USB cable to your USB-C breakout board in this way dramatically increases the danger of frying your PineNote with a short, so you should only do this if all connectors are safely wrapped in electrical tape.

[[Category:PineNote]]

File:Pinenote-uart-dongle.jpeg

2023-10-14T01:36:11Z

Ahelwer: Ahelwer uploaded a new version of File:Pinenote-uart-dongle.jpeg

== Summary ==
Photo of a USB-UART adapter connected via jump wires to a USB-C breakout board, connecting the PineNote to a computer.
== Licensing ==
{{CC0}}
[[Category:PineNote]]

PineNote Development/UART

2023-10-14T01:29:05Z

Ahelwer: /* Splicing resistors */

[[File:Pinenote-uart-dongle.jpeg|thumb|Basic non-stock PineNote UART dongle]]

This page contains information on creating and using a [https://en.wikipedia.org/wiki/Universal_asynchronous_receiver-transmitter UART] dongle for the [[PineNote]].
The PineNote was shipped with a compatible UART dongle, but replacements are not available to order in case of loss or hardware fault.
Thankfully it is not difficult to make your own from easily-acquired components and a small bit of soldering.
Fear not if you've never soldered anything before!
This serves as an excellent first soldering project.
Borrow the tools from a friend or a local hackerspace or tool library.

A PineNote UART dongle enables you to:
# Interact with the system boot menu
# Read system events in real time as the PineNote is used
# Fix the PineNote without opening the case if something goes wrong while [[PineNote Development/Flashing|flashing it]]

Since the PineNote is an embedded system, interfacing with it during boot is more complicated than with an ordinary computer.
The UART dongle enables you to do this.

The PineNote factory firmware runs UART at a baud rate of 1500000 bps, 8 data bits, 1 stop bit, no parity and no flow control.
The process by which the PineNote design was modified to include closed-case UART is documented [[PineNote/Hardware Changes/Closed Case UART|here]].

== Stock dongle ==

The stock UART dongle included with the PineNote was a simple device plugging directly into the PineNote's USB-C port.
The dongle exposed a female USB-C port, which the user plugged into to get UART access.
This design unfortunately ruled out passthrough USB connections, where the user connects to the PineNote via UART and USB simultaneously.
The dongle is not currently available for purchase.

<gallery>
Pinenote-stock-uart-dongle-front.jpg|Front
Pinenote-stock-uart-dongle-back.jpg|Back
</gallery>

== Creating a dongle ==

A typical self-built PineNote UART dongle design has the following components:
# A USB-C breakout board with a male connector exposing the 24 pins of the PineNote's USB-C port
# A USB-UART adapter, to plug into a USB port of the computer you'll use to interface with the PineNote
# [https://en.wikipedia.org/wiki/Jump_wire Jump wires] to connect specific breakout board pins to pins on the USB-UART adapter
# Two 1,000 Ohm through-hole resistors to splice into the jump wires
# Electrical tape or heat shrink to wrap connectors and prevent shorts

You will also need the following tools:
# Soldering iron with solder
# Wire cutters & strippers

The PineNote's internal UART system is documented in [https://files.pine64.org/doc/PineNote/PineNote_USB-C_Console_UART_breakout_board_schematic_v1.0_20210903.pdf this schematic].
The purpose of all 24 USB-C pins is documented [https://en.wikipedia.org/wiki/USB-C#Receptacles on the USB-C Wikipedia page].
We are interested in three sets of pins:
# The SBU1 (A8) and SBU2 (B8) side band use pins
# The CC1 (A5) and CC2 (B5) configuration channel pins
# The GND [https://en.wikipedia.org/wiki/Ground_(electricity) ground return] pins (A1, A12, B1, and B12)

In the PineNote UART schematic you can see (on the bottom right diagram labeled <code>USB_TYPEC_Male</code>) the side band pins are given the labels <code>UART2_TX_SUB1</code> for A8 and <code>UART2_RX_SUB2</code> for B8.
The first (TX) is used for transmitting data and the second (RX) is used for receiving data, from the perspective of the PineNote.
Also note the configuration channel pins labeled <code>TYPEC_CC1</code> for A5 and <code>TYPEC_CC2</code> for B5.
These pins are used to signal to the PineNote that a UART dongle is present.
The diagram shows they must be connected to a 3.3V source in parallel, mediated by resistors.
The schematic indicates 10,000 Ohm resistors, but community member talpadk experimented and found 1,000 Ohm resistors work better.
Our mission is to wire up pins from a USB-UART adapter to a USB-C breakout board following these requirements.

=== Buying components ===

There are many possible USB-C breakout board designs available for purchase online.
One particularly useful design is a "passthrough" or "intercept" style, with both male and female USB-C ports.
This design is more versatile in case you want to reuse it in other projects, and also enables you to connect to the PineNote via UART and USB at the same time.
An example of this product can be found [https://pmdway.com/products/usb-3-1-type-c-male-to-female-breakout-test-board here], although you are encouraged to shop around for cheaper options.
If you're fine with a bit more soldering, there is a very cheap one [https://www.ebay.com/itm/275407037613 here].

Similarly, there are many USB-UART adapter designs available.
These devices plug into your computer and expose a number of pins themselves, connecting to specific pins on the breakout board with jump wires.
It is important to get a 3.3V model, or at least a model with the option of 3.3V, as a 5V source might fry the PineNote.
[https://pmdway.com/products/usb-to-ttl-serial-cp2104-6-pin-converter-module Here] is one example with jump wires included, although you are again encouraged to shop around for alternatives.

All other necessary components of our UART dongle are readily & cheaply available in many locations.

=== Splicing resistors ===

[[File:PineNote-UART-Y-pull-up-resistor-cable.jpg|thumb|The desired end result; wrap removed from resistors for illustration purposes.]]

This is the only difficult part of the whole process.
Your goal is to create a Y-shaped jump wire with 1,000 Ohm through-hole resistors spliced into each of the twin arms.
The solitary leg will connect to a 3.3V source on your USB-UART adapter.
The twin arms will connect to the configuration channel pins on your USB-C breakout board.
This setup is called using pull-up resistors, and you can read a nice introduction to their purpose [https://www.electronics-tutorials.ws/logic/pull-up-resistor.html here].

For this project you'll need:
# A soldering iron with solder
# Wire cutters & strippers
# 2x jumper wires, male/female as compatible with your board designs
# 2x 1,000 Ohm through-hole resistors
# Electrical tape or heat shrink wrap

Consider buying extra jumper wires and resistors in case you mess up.
Also double-check that you have 1K resistors with [https://resistorcolorcodecalc.com/ this color code calculator].
Although the PineNote UART schematic says to use 10K Ohm resistors, community member talpadk experimented and found 1K is more appropriate.
Assemble your Y-cable as follows:
# Graft one jump wire onto the other to form a Y shape using [https://www.youtube.com/watch?v=KpiEfuhPqew this] technique, ensuring solitary leg end is compatible with your USB-UART adapter
# Splice resistors into the twin arms using [https://www.youtube.com/watch?v=RMgMVqqjPZ0 this] technique
# Splice remaining jump wire onto the ends of the resistors, ensuring ends are compatible with your USB-C breakout board
# Cover all exposed wire & resistors with electrical tape or heat shrink wrap

=== Assembly ===

Once you have acquired all necessary components, assemble the UART dongle as follows:
# Connect a jump wire from the GND pin on the USB-UART adapter to any one of the four GND pins on the USB-C breakout board (A1, A12, B1, or B12)
# Connect a jump wire from the RXD pin on the USB-UART adapter to the SBU1 pin on the USB-C breakout board (A8)
# Connect a jump wire from the TXD pin on the USB-UART adapter to the SBU2 pin on the USB-C breakout board (B8)
# Connect your Y-shaped jump wire from the 3.3V source pin on the USB-UART adapter to the CC1 and CC2 pins on the USB-C breakout board (A5 and B5)
# Wrap all metal connectors in electrical tape or heat shrink to prevent accidental shorts

Be '''very certain''' of your connections for the 3.3V source, as there is a real risk of irreparably frying your PineNote if they're wrong!
Especially be sure you are connecting to a 3.3V source and not a 5V source.

Note that if you mix up the TX/RX pins, it will still work but the USB-C breakout board will just plug into the PineNote upside down.
You can therefore choose which orientation you want by swapping the TX/RX pin connections.

== Using UART ==

First, use your UART dongle to physically connect your PineNote to your computer:
# Plug the USB-UART adapter into one of your computer's USB ports
# Plug the USB-C breakout board into the USB-C port on the bottom of your PineNote; the orientation matters, so try both and remember which one works

Once the hardware is connected, set up your computer's software as follows:
# Install [https://www.gnu.org/software/screen/ GNU Screen] (or [https://askubuntu.com/q/40959 some other option], but the instructions below are written for <code>screen</code>)
# Identify the USB-UART adapter in your <code>/dev</code> directory by running <code>ls /dev</code> with it plugged in, unplugging it, then again running <code>ls /dev</code> and seeing what changes; it is likely to be called <code>/dev/ttyUSB0</code>
# In a terminal window, run <code>screen -L /dev/ttyUSB0 1500000</code> (you may need to run this as sudo depending on your user's permissions; on most Linux distributions you need to be in the <code>dialout</code> usergroup)

Once the software is set up, power-cycle your PineNote; as the system boots you should see text appearing in your terminal window.
You can exit the screen session with <code>ctrl+a k</code> then pressing <code>y</code> to confirm.
The <code>screen -L</code> flag outputs a text log of the session to the current working directory, probably called <code>screenlog.0</code>.

==== Troubleshooting ====

If you don't see any text in your terminal as the PineNote boots, or the text is garbled, try the following:
* Ensure your GND, RX and TX jump wires are connected to the correct pins on both the USB-UART adapter and the USB-C breakout board
* Connect your USB-C breakout board to your PineNote in the opposite orientation
* Run the screen command as sudo in case your user doesn't have appropriate permissions
* Ensure you are setting the baud rate in the <code>screen</code> command to 1500000 (1.5 million)

== USB passthrough ==

If your USB-C breakout board has a passthrough/intercept design, you can connect to your PineNote over USB and UART at the same time.
This can be useful when you're doing development work on the PineNote boot process so you don't have to continually reconnect cables.
You'll need a USB-A to USB-C cable, connecting directly from your computer's USB-A hub to your USB-C breakout board's female USB-C port.
It's important to connect directly from USB-A, without any intermediate USB-C components.
Note that connecting a live USB cable to your USB-C breakout board in this way dramatically increases the danger of frying your PineNote with a short, so you should only do this if all connectors are safely wrapped in electrical tape.

[[Category:PineNote]]

PineNote Development/UART

2023-10-14T01:26:35Z

Ahelwer: Added photo of Y cable

[[File:Pinenote-uart-dongle.jpeg|thumb|Basic non-stock PineNote UART dongle]]

This page contains information on creating and using a [https://en.wikipedia.org/wiki/Universal_asynchronous_receiver-transmitter UART] dongle for the [[PineNote]].
The PineNote was shipped with a compatible UART dongle, but replacements are not available to order in case of loss or hardware fault.
Thankfully it is not difficult to make your own from easily-acquired components and a small bit of soldering.
Fear not if you've never soldered anything before!
This serves as an excellent first soldering project.
Borrow the tools from a friend or a local hackerspace or tool library.

A PineNote UART dongle enables you to:
# Interact with the system boot menu
# Read system events in real time as the PineNote is used
# Fix the PineNote without opening the case if something goes wrong while [[PineNote Development/Flashing|flashing it]]

Since the PineNote is an embedded system, interfacing with it during boot is more complicated than with an ordinary computer.
The UART dongle enables you to do this.

The PineNote factory firmware runs UART at a baud rate of 1500000 bps, 8 data bits, 1 stop bit, no parity and no flow control.
The process by which the PineNote design was modified to include closed-case UART is documented [[PineNote/Hardware Changes/Closed Case UART|here]].

== Stock dongle ==

The stock UART dongle included with the PineNote was a simple device plugging directly into the PineNote's USB-C port.
The dongle exposed a female USB-C port, which the user plugged into to get UART access.
This design unfortunately ruled out passthrough USB connections, where the user connects to the PineNote via UART and USB simultaneously.
The dongle is not currently available for purchase.

<gallery>
Pinenote-stock-uart-dongle-front.jpg|Front
Pinenote-stock-uart-dongle-back.jpg|Back
</gallery>

== Creating a dongle ==

A typical self-built PineNote UART dongle design has the following components:
# A USB-C breakout board with a male connector exposing the 24 pins of the PineNote's USB-C port
# A USB-UART adapter, to plug into a USB port of the computer you'll use to interface with the PineNote
# [https://en.wikipedia.org/wiki/Jump_wire Jump wires] to connect specific breakout board pins to pins on the USB-UART adapter
# Two 1,000 Ohm through-hole resistors to splice into the jump wires
# Electrical tape or heat shrink to wrap connectors and prevent shorts

You will also need the following tools:
# Soldering iron with solder
# Wire cutters & strippers

The PineNote's internal UART system is documented in [https://files.pine64.org/doc/PineNote/PineNote_USB-C_Console_UART_breakout_board_schematic_v1.0_20210903.pdf this schematic].
The purpose of all 24 USB-C pins is documented [https://en.wikipedia.org/wiki/USB-C#Receptacles on the USB-C Wikipedia page].
We are interested in three sets of pins:
# The SBU1 (A8) and SBU2 (B8) side band use pins
# The CC1 (A5) and CC2 (B5) configuration channel pins
# The GND [https://en.wikipedia.org/wiki/Ground_(electricity) ground return] pins (A1, A12, B1, and B12)

In the PineNote UART schematic you can see (on the bottom right diagram labeled <code>USB_TYPEC_Male</code>) the side band pins are given the labels <code>UART2_TX_SUB1</code> for A8 and <code>UART2_RX_SUB2</code> for B8.
The first (TX) is used for transmitting data and the second (RX) is used for receiving data, from the perspective of the PineNote.
Also note the configuration channel pins labeled <code>TYPEC_CC1</code> for A5 and <code>TYPEC_CC2</code> for B5.
These pins are used to signal to the PineNote that a UART dongle is present.
The diagram shows they must be connected to a 3.3V source in parallel, mediated by resistors.
The schematic indicates 10,000 Ohm resistors, but community member talpadk experimented and found 1,000 Ohm resistors work better.
Our mission is to wire up pins from a USB-UART adapter to a USB-C breakout board following these requirements.

=== Buying components ===

There are many possible USB-C breakout board designs available for purchase online.
One particularly useful design is a "passthrough" or "intercept" style, with both male and female USB-C ports.
This design is more versatile in case you want to reuse it in other projects, and also enables you to connect to the PineNote via UART and USB at the same time.
An example of this product can be found [https://pmdway.com/products/usb-3-1-type-c-male-to-female-breakout-test-board here], although you are encouraged to shop around for cheaper options.
If you're fine with a bit more soldering, there is a very cheap one [https://www.ebay.com/itm/275407037613 here].

Similarly, there are many USB-UART adapter designs available.
These devices plug into your computer and expose a number of pins themselves, connecting to specific pins on the breakout board with jump wires.
It is important to get a 3.3V model, or at least a model with the option of 3.3V, as a 5V source might fry the PineNote.
[https://pmdway.com/products/usb-to-ttl-serial-cp2104-6-pin-converter-module Here] is one example with jump wires included, although you are again encouraged to shop around for alternatives.

All other necessary components of our UART dongle are readily & cheaply available in many locations.

=== Splicing resistors ===

[[File:PineNote-UART-Y-pull-up-resistor-cable.jpg|thumb|The goal]]

This is the only difficult part of the whole process.
Your goal is to create a Y-shaped jump wire with 1,000 Ohm through-hole resistors spliced into each of the twin arms.
The solitary leg will connect to a 3.3V source on your USB-UART adapter.
The twin arms will connect to the configuration channel pins on your USB-C breakout board.
This setup is called using pull-up resistors, and you can read a nice introduction to their purpose [https://www.electronics-tutorials.ws/logic/pull-up-resistor.html here].

For this project you'll need:
# A soldering iron with solder
# Wire cutters & strippers
# 2x jumper wires, male/female as compatible with your board designs
# 2x 1,000 Ohm through-hole resistors
# Electrical tape or heat shrink wrap

Consider buying extra jumper wires and resistors in case you mess up.
Also double-check that you have 1K resistors with [https://resistorcolorcodecalc.com/ this color code calculator].
Although the PineNote UART schematic says to use 10K Ohm resistors, community member talpadk experimented and found 1K is more appropriate.
Assemble your Y-cable as follows:
# Graft one jump wire onto the other to form a Y shape using [https://www.youtube.com/watch?v=KpiEfuhPqew this] technique, ensuring solitary leg end is compatible with your USB-UART adapter
# Splice resistors into the twin arms using [https://www.youtube.com/watch?v=RMgMVqqjPZ0 this] technique
# Splice remaining jump wire onto the ends of the resistors, ensuring ends are compatible with your USB-C breakout board
# Cover all exposed wire & resistors with electrical tape or heat shrink wrap

=== Assembly ===

Once you have acquired all necessary components, assemble the UART dongle as follows:
# Connect a jump wire from the GND pin on the USB-UART adapter to any one of the four GND pins on the USB-C breakout board (A1, A12, B1, or B12)
# Connect a jump wire from the RXD pin on the USB-UART adapter to the SBU1 pin on the USB-C breakout board (A8)
# Connect a jump wire from the TXD pin on the USB-UART adapter to the SBU2 pin on the USB-C breakout board (B8)
# Connect your Y-shaped jump wire from the 3.3V source pin on the USB-UART adapter to the CC1 and CC2 pins on the USB-C breakout board (A5 and B5)
# Wrap all metal connectors in electrical tape or heat shrink to prevent accidental shorts

Be '''very certain''' of your connections for the 3.3V source, as there is a real risk of irreparably frying your PineNote if they're wrong!
Especially be sure you are connecting to a 3.3V source and not a 5V source.

Note that if you mix up the TX/RX pins, it will still work but the USB-C breakout board will just plug into the PineNote upside down.
You can therefore choose which orientation you want by swapping the TX/RX pin connections.

== Using UART ==

First, use your UART dongle to physically connect your PineNote to your computer:
# Plug the USB-UART adapter into one of your computer's USB ports
# Plug the USB-C breakout board into the USB-C port on the bottom of your PineNote; the orientation matters, so try both and remember which one works

Once the hardware is connected, set up your computer's software as follows:
# Install [https://www.gnu.org/software/screen/ GNU Screen] (or [https://askubuntu.com/q/40959 some other option], but the instructions below are written for <code>screen</code>)
# Identify the USB-UART adapter in your <code>/dev</code> directory by running <code>ls /dev</code> with it plugged in, unplugging it, then again running <code>ls /dev</code> and seeing what changes; it is likely to be called <code>/dev/ttyUSB0</code>
# In a terminal window, run <code>screen -L /dev/ttyUSB0 1500000</code> (you may need to run this as sudo depending on your user's permissions; on most Linux distributions you need to be in the <code>dialout</code> usergroup)

Once the software is set up, power-cycle your PineNote; as the system boots you should see text appearing in your terminal window.
You can exit the screen session with <code>ctrl+a k</code> then pressing <code>y</code> to confirm.
The <code>screen -L</code> flag outputs a text log of the session to the current working directory, probably called <code>screenlog.0</code>.

==== Troubleshooting ====

If you don't see any text in your terminal as the PineNote boots, or the text is garbled, try the following:
* Ensure your GND, RX and TX jump wires are connected to the correct pins on both the USB-UART adapter and the USB-C breakout board
* Connect your USB-C breakout board to your PineNote in the opposite orientation
* Run the screen command as sudo in case your user doesn't have appropriate permissions
* Ensure you are setting the baud rate in the <code>screen</code> command to 1500000 (1.5 million)

== USB passthrough ==

If your USB-C breakout board has a passthrough/intercept design, you can connect to your PineNote over USB and UART at the same time.
This can be useful when you're doing development work on the PineNote boot process so you don't have to continually reconnect cables.
You'll need a USB-A to USB-C cable, connecting directly from your computer's USB-A hub to your USB-C breakout board's female USB-C port.
It's important to connect directly from USB-A, without any intermediate USB-C components.
Note that connecting a live USB cable to your USB-C breakout board in this way dramatically increases the danger of frying your PineNote with a short, so you should only do this if all connectors are safely wrapped in electrical tape.

[[Category:PineNote]]

File:PineNote-UART-Y-pull-up-resistor-cable.jpg

2023-10-14T01:24:49Z

Ahelwer: Photo of a Y-shaped cable with resistors spliced into each of the twin arms.

== Summary ==
Photo of a Y-shaped cable with resistors spliced into each of the twin arms.
== Licensing ==
{{CC0}}

PineNote Development/UART

2023-10-14T01:19:46Z

Ahelwer: /* Creating a dongle */ Added note about tools

[[File:Pinenote-uart-dongle.jpeg|thumb|Basic non-stock PineNote UART dongle]]

This page contains information on creating and using a [https://en.wikipedia.org/wiki/Universal_asynchronous_receiver-transmitter UART] dongle for the [[PineNote]].
The PineNote was shipped with a compatible UART dongle, but replacements are not available to order in case of loss or hardware fault.
Thankfully it is not difficult to make your own from easily-acquired components and a small bit of soldering.
Fear not if you've never soldered anything before!
This serves as an excellent first soldering project.
Borrow the tools from a friend or a local hackerspace or tool library.

A PineNote UART dongle enables you to:
# Interact with the system boot menu
# Read system events in real time as the PineNote is used
# Fix the PineNote without opening the case if something goes wrong while [[PineNote Development/Flashing|flashing it]]

Since the PineNote is an embedded system, interfacing with it during boot is more complicated than with an ordinary computer.
The UART dongle enables you to do this.

The PineNote factory firmware runs UART at a baud rate of 1500000 bps, 8 data bits, 1 stop bit, no parity and no flow control.
The process by which the PineNote design was modified to include closed-case UART is documented [[PineNote/Hardware Changes/Closed Case UART|here]].

== Stock dongle ==

The stock UART dongle included with the PineNote was a simple device plugging directly into the PineNote's USB-C port.
The dongle exposed a female USB-C port, which the user plugged into to get UART access.
This design unfortunately ruled out passthrough USB connections, where the user connects to the PineNote via UART and USB simultaneously.
The dongle is not currently available for purchase.

<gallery>
Pinenote-stock-uart-dongle-front.jpg|Front
Pinenote-stock-uart-dongle-back.jpg|Back
</gallery>

== Creating a dongle ==

A typical self-built PineNote UART dongle design has the following components:
# A USB-C breakout board with a male connector exposing the 24 pins of the PineNote's USB-C port
# A USB-UART adapter, to plug into a USB port of the computer you'll use to interface with the PineNote
# [https://en.wikipedia.org/wiki/Jump_wire Jump wires] to connect specific breakout board pins to pins on the USB-UART adapter
# Two 1,000 Ohm through-hole resistors to splice into the jump wires
# Electrical tape or heat shrink to wrap connectors and prevent shorts

You will also need the following tools:
# Soldering iron with solder
# Wire cutters & strippers

The PineNote's internal UART system is documented in [https://files.pine64.org/doc/PineNote/PineNote_USB-C_Console_UART_breakout_board_schematic_v1.0_20210903.pdf this schematic].
The purpose of all 24 USB-C pins is documented [https://en.wikipedia.org/wiki/USB-C#Receptacles on the USB-C Wikipedia page].
We are interested in three sets of pins:
# The SBU1 (A8) and SBU2 (B8) side band use pins
# The CC1 (A5) and CC2 (B5) configuration channel pins
# The GND [https://en.wikipedia.org/wiki/Ground_(electricity) ground return] pins (A1, A12, B1, and B12)

In the PineNote UART schematic you can see (on the bottom right diagram labeled <code>USB_TYPEC_Male</code>) the side band pins are given the labels <code>UART2_TX_SUB1</code> for A8 and <code>UART2_RX_SUB2</code> for B8.
The first (TX) is used for transmitting data and the second (RX) is used for receiving data, from the perspective of the PineNote.
Also note the configuration channel pins labeled <code>TYPEC_CC1</code> for A5 and <code>TYPEC_CC2</code> for B5.
These pins are used to signal to the PineNote that a UART dongle is present.
The diagram shows they must be connected to a 3.3V source in parallel, mediated by resistors.
The schematic indicates 10,000 Ohm resistors, but community member talpadk experimented and found 1,000 Ohm resistors work better.
Our mission is to wire up pins from a USB-UART adapter to a USB-C breakout board following these requirements.

=== Buying components ===

There are many possible USB-C breakout board designs available for purchase online.
One particularly useful design is a "passthrough" or "intercept" style, with both male and female USB-C ports.
This design is more versatile in case you want to reuse it in other projects, and also enables you to connect to the PineNote via UART and USB at the same time.
An example of this product can be found [https://pmdway.com/products/usb-3-1-type-c-male-to-female-breakout-test-board here], although you are encouraged to shop around for cheaper options.
If you're fine with a bit more soldering, there is a very cheap one [https://www.ebay.com/itm/275407037613 here].

Similarly, there are many USB-UART adapter designs available.
These devices plug into your computer and expose a number of pins themselves, connecting to specific pins on the breakout board with jump wires.
It is important to get a 3.3V model, or at least a model with the option of 3.3V, as a 5V source might fry the PineNote.
[https://pmdway.com/products/usb-to-ttl-serial-cp2104-6-pin-converter-module Here] is one example with jump wires included, although you are again encouraged to shop around for alternatives.

All other necessary components of our UART dongle are readily & cheaply available in many locations.

=== Splicing resistors ===

This is the only difficult part of the whole process.
Your goal is to create a Y-shaped jump wire with 1,000 Ohm through-hole resistors spliced into each of the twin arms.
The solitary leg will connect to a 3.3V source on your USB-UART adapter.
The twin arms will connect to the configuration channel pins on your USB-C breakout board.
This setup is called using pull-up resistors, and you can read a nice introduction to their purpose [https://www.electronics-tutorials.ws/logic/pull-up-resistor.html here].

For this project you'll need:
# A soldering iron with solder
# Wire cutters & strippers
# 2x jumper wires, male/female as compatible with your board designs
# 2x 1,000 Ohm through-hole resistors
# Electrical tape or heat shrink wrap

Consider buying extra jumper wires and resistors in case you mess up.
Also double-check that you have 1K resistors with [https://resistorcolorcodecalc.com/ this color code calculator].
Although the PineNote UART schematic says to use 10K Ohm resistors, community member talpadk experimented and found 1K is more appropriate.
Assemble your Y-cable as follows:
# Graft one jump wire onto the other to form a Y shape using [https://www.youtube.com/watch?v=KpiEfuhPqew this] technique, ensuring solitary leg end is compatible with your USB-UART adapter
# Splice resistors into the twin arms using [https://www.youtube.com/watch?v=RMgMVqqjPZ0 this] technique
# Splice remaining jump wire onto the ends of the resistors, ensuring ends are compatible with your USB-C breakout board
# Cover all exposed wire & resistors with electrical tape or heat shrink wrap

=== Assembly ===

Once you have acquired all necessary components, assemble the UART dongle as follows:
# Connect a jump wire from the GND pin on the USB-UART adapter to any one of the four GND pins on the USB-C breakout board (A1, A12, B1, or B12)
# Connect a jump wire from the RXD pin on the USB-UART adapter to the SBU1 pin on the USB-C breakout board (A8)
# Connect a jump wire from the TXD pin on the USB-UART adapter to the SBU2 pin on the USB-C breakout board (B8)
# Connect your Y-shaped jump wire from the 3.3V source pin on the USB-UART adapter to the CC1 and CC2 pins on the USB-C breakout board (A5 and B5)
# Wrap all metal connectors in electrical tape or heat shrink to prevent accidental shorts

Be '''very certain''' of your connections for the 3.3V source, as there is a real risk of irreparably frying your PineNote if they're wrong!
Especially be sure you are connecting to a 3.3V source and not a 5V source.

Note that if you mix up the TX/RX pins, it will still work but the USB-C breakout board will just plug into the PineNote upside down.
You can therefore choose which orientation you want by swapping the TX/RX pin connections.

== Using UART ==

First, use your UART dongle to physically connect your PineNote to your computer:
# Plug the USB-UART adapter into one of your computer's USB ports
# Plug the USB-C breakout board into the USB-C port on the bottom of your PineNote; the orientation matters, so try both and remember which one works

Once the hardware is connected, set up your computer's software as follows:
# Install [https://www.gnu.org/software/screen/ GNU Screen] (or [https://askubuntu.com/q/40959 some other option], but the instructions below are written for <code>screen</code>)
# Identify the USB-UART adapter in your <code>/dev</code> directory by running <code>ls /dev</code> with it plugged in, unplugging it, then again running <code>ls /dev</code> and seeing what changes; it is likely to be called <code>/dev/ttyUSB0</code>
# In a terminal window, run <code>screen -L /dev/ttyUSB0 1500000</code> (you may need to run this as sudo depending on your user's permissions; on most Linux distributions you need to be in the <code>dialout</code> usergroup)

Once the software is set up, power-cycle your PineNote; as the system boots you should see text appearing in your terminal window.
You can exit the screen session with <code>ctrl+a k</code> then pressing <code>y</code> to confirm.
The <code>screen -L</code> flag outputs a text log of the session to the current working directory, probably called <code>screenlog.0</code>.

==== Troubleshooting ====

If you don't see any text in your terminal as the PineNote boots, or the text is garbled, try the following:
* Ensure your GND, RX and TX jump wires are connected to the correct pins on both the USB-UART adapter and the USB-C breakout board
* Connect your USB-C breakout board to your PineNote in the opposite orientation
* Run the screen command as sudo in case your user doesn't have appropriate permissions
* Ensure you are setting the baud rate in the <code>screen</code> command to 1500000 (1.5 million)

== USB passthrough ==

If your USB-C breakout board has a passthrough/intercept design, you can connect to your PineNote over USB and UART at the same time.
This can be useful when you're doing development work on the PineNote boot process so you don't have to continually reconnect cables.
You'll need a USB-A to USB-C cable, connecting directly from your computer's USB-A hub to your USB-C breakout board's female USB-C port.
It's important to connect directly from USB-A, without any intermediate USB-C components.
Note that connecting a live USB cable to your USB-C breakout board in this way dramatically increases the danger of frying your PineNote with a short, so you should only do this if all connectors are safely wrapped in electrical tape.

[[Category:PineNote]]

PineNote Development/UART

2023-10-14T01:16:23Z

Ahelwer: /* Splicing resistors */

[[File:Pinenote-uart-dongle.jpeg|thumb|Basic non-stock PineNote UART dongle]]

This page contains information on creating and using a [https://en.wikipedia.org/wiki/Universal_asynchronous_receiver-transmitter UART] dongle for the [[PineNote]].
The PineNote was shipped with a compatible UART dongle, but replacements are not available to order in case of loss or hardware fault.
Thankfully it is not difficult to make your own from easily-acquired components and a small bit of soldering.
Fear not if you've never soldered anything before!
This serves as an excellent first soldering project.
Borrow the tools from a friend or a local hackerspace or tool library.

A PineNote UART dongle enables you to:
# Interact with the system boot menu
# Read system events in real time as the PineNote is used
# Fix the PineNote without opening the case if something goes wrong while [[PineNote Development/Flashing|flashing it]]

Since the PineNote is an embedded system, interfacing with it during boot is more complicated than with an ordinary computer.
The UART dongle enables you to do this.

The PineNote factory firmware runs UART at a baud rate of 1500000 bps, 8 data bits, 1 stop bit, no parity and no flow control.
The process by which the PineNote design was modified to include closed-case UART is documented [[PineNote/Hardware Changes/Closed Case UART|here]].

== Stock dongle ==

The stock UART dongle included with the PineNote was a simple device plugging directly into the PineNote's USB-C port.
The dongle exposed a female USB-C port, which the user plugged into to get UART access.
This design unfortunately ruled out passthrough USB connections, where the user connects to the PineNote via UART and USB simultaneously.
The dongle is not currently available for purchase.

<gallery>
Pinenote-stock-uart-dongle-front.jpg|Front
Pinenote-stock-uart-dongle-back.jpg|Back
</gallery>

== Creating a dongle ==

A typical self-built PineNote UART dongle design has the following components:
# A USB-C breakout board with a male connector exposing the 24 pins of the PineNote's USB-C port
# A USB-UART adapter, to plug into a USB port of the computer you'll use to interface with the PineNote
# [https://en.wikipedia.org/wiki/Jump_wire Jump wires] to connect specific breakout board pins to pins on the USB-UART adapter
# Two 1,000 Ohm through-hole resistors to splice into the jump wires
# Electrical tape or heat shrink to wrap connectors and prevent shorts

The PineNote's internal UART system is documented in [https://files.pine64.org/doc/PineNote/PineNote_USB-C_Console_UART_breakout_board_schematic_v1.0_20210903.pdf this schematic].
The purpose of all 24 USB-C pins is documented [https://en.wikipedia.org/wiki/USB-C#Receptacles on the USB-C Wikipedia page].
We are interested in three sets of pins:
# The SBU1 (A8) and SBU2 (B8) side band use pins
# The CC1 (A5) and CC2 (B5) configuration channel pins
# The GND [https://en.wikipedia.org/wiki/Ground_(electricity) ground return] pins (A1, A12, B1, and B12)

In the PineNote UART schematic you can see (on the bottom right diagram labeled <code>USB_TYPEC_Male</code>) the side band pins are given the labels <code>UART2_TX_SUB1</code> for A8 and <code>UART2_RX_SUB2</code> for B8.
The first (TX) is used for transmitting data and the second (RX) is used for receiving data, from the perspective of the PineNote.
Also note the configuration channel pins labeled <code>TYPEC_CC1</code> for A5 and <code>TYPEC_CC2</code> for B5.
These pins are used to signal to the PineNote that a UART dongle is present.
The diagram shows they must be connected to a 3.3V source in parallel, mediated by resistors.
The schematic indicates 10,000 Ohm resistors, but community member talpadk experimented and found 1,000 Ohm resistors work better.
Our mission is to wire up pins from a USB-UART adapter to a USB-C breakout board following these requirements.

=== Buying components ===

There are many possible USB-C breakout board designs available for purchase online.
One particularly useful design is a "passthrough" or "intercept" style, with both male and female USB-C ports.
This design is more versatile in case you want to reuse it in other projects, and also enables you to connect to the PineNote via UART and USB at the same time.
An example of this product can be found [https://pmdway.com/products/usb-3-1-type-c-male-to-female-breakout-test-board here], although you are encouraged to shop around for cheaper options.
If you're fine with a bit more soldering, there is a very cheap one [https://www.ebay.com/itm/275407037613 here].

Similarly, there are many USB-UART adapter designs available.
These devices plug into your computer and expose a number of pins themselves, connecting to specific pins on the breakout board with jump wires.
It is important to get a 3.3V model, or at least a model with the option of 3.3V, as a 5V source might fry the PineNote.
[https://pmdway.com/products/usb-to-ttl-serial-cp2104-6-pin-converter-module Here] is one example with jump wires included, although you are again encouraged to shop around for alternatives.

All other necessary components of our UART dongle are readily & cheaply available in many locations.

=== Splicing resistors ===

This is the only difficult part of the whole process.
Your goal is to create a Y-shaped jump wire with 1,000 Ohm through-hole resistors spliced into each of the twin arms.
The solitary leg will connect to a 3.3V source on your USB-UART adapter.
The twin arms will connect to the configuration channel pins on your USB-C breakout board.
This setup is called using pull-up resistors, and you can read a nice introduction to their purpose [https://www.electronics-tutorials.ws/logic/pull-up-resistor.html here].

For this project you'll need:
# A soldering iron with solder
# Wire cutters & strippers
# 2x jumper wires, male/female as compatible with your board designs
# 2x 1,000 Ohm through-hole resistors
# Electrical tape or heat shrink wrap

Consider buying extra jumper wires and resistors in case you mess up.
Also double-check that you have 1K resistors with [https://resistorcolorcodecalc.com/ this color code calculator].
Although the PineNote UART schematic says to use 10K Ohm resistors, community member talpadk experimented and found 1K is more appropriate.
Assemble your Y-cable as follows:
# Graft one jump wire onto the other to form a Y shape using [https://www.youtube.com/watch?v=KpiEfuhPqew this] technique, ensuring solitary leg end is compatible with your USB-UART adapter
# Splice resistors into the twin arms using [https://www.youtube.com/watch?v=RMgMVqqjPZ0 this] technique
# Splice remaining jump wire onto the ends of the resistors, ensuring ends are compatible with your USB-C breakout board
# Cover all exposed wire & resistors with electrical tape or heat shrink wrap

=== Assembly ===

Once you have acquired all necessary components, assemble the UART dongle as follows:
# Connect a jump wire from the GND pin on the USB-UART adapter to any one of the four GND pins on the USB-C breakout board (A1, A12, B1, or B12)
# Connect a jump wire from the RXD pin on the USB-UART adapter to the SBU1 pin on the USB-C breakout board (A8)
# Connect a jump wire from the TXD pin on the USB-UART adapter to the SBU2 pin on the USB-C breakout board (B8)
# Connect your Y-shaped jump wire from the 3.3V source pin on the USB-UART adapter to the CC1 and CC2 pins on the USB-C breakout board (A5 and B5)
# Wrap all metal connectors in electrical tape or heat shrink to prevent accidental shorts

Be '''very certain''' of your connections for the 3.3V source, as there is a real risk of irreparably frying your PineNote if they're wrong!
Especially be sure you are connecting to a 3.3V source and not a 5V source.

Note that if you mix up the TX/RX pins, it will still work but the USB-C breakout board will just plug into the PineNote upside down.
You can therefore choose which orientation you want by swapping the TX/RX pin connections.

== Using UART ==

First, use your UART dongle to physically connect your PineNote to your computer:
# Plug the USB-UART adapter into one of your computer's USB ports
# Plug the USB-C breakout board into the USB-C port on the bottom of your PineNote; the orientation matters, so try both and remember which one works

Once the hardware is connected, set up your computer's software as follows:
# Install [https://www.gnu.org/software/screen/ GNU Screen] (or [https://askubuntu.com/q/40959 some other option], but the instructions below are written for <code>screen</code>)
# Identify the USB-UART adapter in your <code>/dev</code> directory by running <code>ls /dev</code> with it plugged in, unplugging it, then again running <code>ls /dev</code> and seeing what changes; it is likely to be called <code>/dev/ttyUSB0</code>
# In a terminal window, run <code>screen -L /dev/ttyUSB0 1500000</code> (you may need to run this as sudo depending on your user's permissions; on most Linux distributions you need to be in the <code>dialout</code> usergroup)

Once the software is set up, power-cycle your PineNote; as the system boots you should see text appearing in your terminal window.
You can exit the screen session with <code>ctrl+a k</code> then pressing <code>y</code> to confirm.
The <code>screen -L</code> flag outputs a text log of the session to the current working directory, probably called <code>screenlog.0</code>.

==== Troubleshooting ====

If you don't see any text in your terminal as the PineNote boots, or the text is garbled, try the following:
* Ensure your GND, RX and TX jump wires are connected to the correct pins on both the USB-UART adapter and the USB-C breakout board
* Connect your USB-C breakout board to your PineNote in the opposite orientation
* Run the screen command as sudo in case your user doesn't have appropriate permissions
* Ensure you are setting the baud rate in the <code>screen</code> command to 1500000 (1.5 million)

== USB passthrough ==

If your USB-C breakout board has a passthrough/intercept design, you can connect to your PineNote over USB and UART at the same time.
This can be useful when you're doing development work on the PineNote boot process so you don't have to continually reconnect cables.
You'll need a USB-A to USB-C cable, connecting directly from your computer's USB-A hub to your USB-C breakout board's female USB-C port.
It's important to connect directly from USB-A, without any intermediate USB-C components.
Note that connecting a live USB cable to your USB-C breakout board in this way dramatically increases the danger of frying your PineNote with a short, so you should only do this if all connectors are safely wrapped in electrical tape.

[[Category:PineNote]]

PineNote Development/UART

2023-10-14T01:13:10Z

Ahelwer: /* Buying components */

[[File:Pinenote-uart-dongle.jpeg|thumb|Basic non-stock PineNote UART dongle]]

This page contains information on creating and using a [https://en.wikipedia.org/wiki/Universal_asynchronous_receiver-transmitter UART] dongle for the [[PineNote]].
The PineNote was shipped with a compatible UART dongle, but replacements are not available to order in case of loss or hardware fault.
Thankfully it is not difficult to make your own from easily-acquired components and a small bit of soldering.
Fear not if you've never soldered anything before!
This serves as an excellent first soldering project.
Borrow the tools from a friend or a local hackerspace or tool library.

A PineNote UART dongle enables you to:
# Interact with the system boot menu
# Read system events in real time as the PineNote is used
# Fix the PineNote without opening the case if something goes wrong while [[PineNote Development/Flashing|flashing it]]

Since the PineNote is an embedded system, interfacing with it during boot is more complicated than with an ordinary computer.
The UART dongle enables you to do this.

The PineNote factory firmware runs UART at a baud rate of 1500000 bps, 8 data bits, 1 stop bit, no parity and no flow control.
The process by which the PineNote design was modified to include closed-case UART is documented [[PineNote/Hardware Changes/Closed Case UART|here]].

== Stock dongle ==

The stock UART dongle included with the PineNote was a simple device plugging directly into the PineNote's USB-C port.
The dongle exposed a female USB-C port, which the user plugged into to get UART access.
This design unfortunately ruled out passthrough USB connections, where the user connects to the PineNote via UART and USB simultaneously.
The dongle is not currently available for purchase.

<gallery>
Pinenote-stock-uart-dongle-front.jpg|Front
Pinenote-stock-uart-dongle-back.jpg|Back
</gallery>

== Creating a dongle ==

A typical self-built PineNote UART dongle design has the following components:
# A USB-C breakout board with a male connector exposing the 24 pins of the PineNote's USB-C port
# A USB-UART adapter, to plug into a USB port of the computer you'll use to interface with the PineNote
# [https://en.wikipedia.org/wiki/Jump_wire Jump wires] to connect specific breakout board pins to pins on the USB-UART adapter
# Two 1,000 Ohm through-hole resistors to splice into the jump wires
# Electrical tape or heat shrink to wrap connectors and prevent shorts

The PineNote's internal UART system is documented in [https://files.pine64.org/doc/PineNote/PineNote_USB-C_Console_UART_breakout_board_schematic_v1.0_20210903.pdf this schematic].
The purpose of all 24 USB-C pins is documented [https://en.wikipedia.org/wiki/USB-C#Receptacles on the USB-C Wikipedia page].
We are interested in three sets of pins:
# The SBU1 (A8) and SBU2 (B8) side band use pins
# The CC1 (A5) and CC2 (B5) configuration channel pins
# The GND [https://en.wikipedia.org/wiki/Ground_(electricity) ground return] pins (A1, A12, B1, and B12)

In the PineNote UART schematic you can see (on the bottom right diagram labeled <code>USB_TYPEC_Male</code>) the side band pins are given the labels <code>UART2_TX_SUB1</code> for A8 and <code>UART2_RX_SUB2</code> for B8.
The first (TX) is used for transmitting data and the second (RX) is used for receiving data, from the perspective of the PineNote.
Also note the configuration channel pins labeled <code>TYPEC_CC1</code> for A5 and <code>TYPEC_CC2</code> for B5.
These pins are used to signal to the PineNote that a UART dongle is present.
The diagram shows they must be connected to a 3.3V source in parallel, mediated by resistors.
The schematic indicates 10,000 Ohm resistors, but community member talpadk experimented and found 1,000 Ohm resistors work better.
Our mission is to wire up pins from a USB-UART adapter to a USB-C breakout board following these requirements.

=== Buying components ===

There are many possible USB-C breakout board designs available for purchase online.
One particularly useful design is a "passthrough" or "intercept" style, with both male and female USB-C ports.
This design is more versatile in case you want to reuse it in other projects, and also enables you to connect to the PineNote via UART and USB at the same time.
An example of this product can be found [https://pmdway.com/products/usb-3-1-type-c-male-to-female-breakout-test-board here], although you are encouraged to shop around for cheaper options.
If you're fine with a bit more soldering, there is a very cheap one [https://www.ebay.com/itm/275407037613 here].

Similarly, there are many USB-UART adapter designs available.
These devices plug into your computer and expose a number of pins themselves, connecting to specific pins on the breakout board with jump wires.
It is important to get a 3.3V model, or at least a model with the option of 3.3V, as a 5V source might fry the PineNote.
[https://pmdway.com/products/usb-to-ttl-serial-cp2104-6-pin-converter-module Here] is one example with jump wires included, although you are again encouraged to shop around for alternatives.

All other necessary components of our UART dongle are readily & cheaply available in many locations.

=== Splicing resistors ===

This is the only difficult part of the whole process.
Your goal is to create a Y-shaped jump wire with 1,000 Ohm through-hole resistors spliced into each of the twin arms.
The solitary leg will connect to a 3.3V source on your USB-UART adapter.
The twin arms will connect to the configuration channel pins on your USB-C breakout board.
These are called pull-up resistors, and you can read a nice introduction to their purpose [https://www.electronics-tutorials.ws/logic/pull-up-resistor.html here].

For this project you'll need:
# A soldering iron with solder
# Wire cutters & strippers
# 2x jumper wires, male/female as compatible with your board designs
# 2x 1,000 Ohm through-hole resistors
# Electrical tape or heat shrink wrap

Consider buying extra jumper wires and resistors in case you mess up.
Also double-check that you have 1K resistors with [https://resistorcolorcodecalc.com/ this color code calculator].
Although the PineNote UART schematic says to use 10K Ohm resistors, community member talpadk experimented and found 1K is more appropriate.
Assemble your Y-cable as follows:
# Graft one jump wire onto the other to form a Y shape using [https://www.youtube.com/watch?v=KpiEfuhPqew this] technique, ensuring solitary leg end is compatible with your USB-UART adapter
# Splice resistors into the twin arms using [https://www.youtube.com/watch?v=RMgMVqqjPZ0 this] technique
# Splice remaining jump wire onto the ends of the resistors, ensuring ends are compatible with your USB-C breakout board
# Cover all exposed wire & resistors with electrical tape or heat shrink wrap

=== Assembly ===

Once you have acquired all necessary components, assemble the UART dongle as follows:
# Connect a jump wire from the GND pin on the USB-UART adapter to any one of the four GND pins on the USB-C breakout board (A1, A12, B1, or B12)
# Connect a jump wire from the RXD pin on the USB-UART adapter to the SBU1 pin on the USB-C breakout board (A8)
# Connect a jump wire from the TXD pin on the USB-UART adapter to the SBU2 pin on the USB-C breakout board (B8)
# Connect your Y-shaped jump wire from the 3.3V source pin on the USB-UART adapter to the CC1 and CC2 pins on the USB-C breakout board (A5 and B5)
# Wrap all metal connectors in electrical tape or heat shrink to prevent accidental shorts

Be '''very certain''' of your connections for the 3.3V source, as there is a real risk of irreparably frying your PineNote if they're wrong!
Especially be sure you are connecting to a 3.3V source and not a 5V source.

Note that if you mix up the TX/RX pins, it will still work but the USB-C breakout board will just plug into the PineNote upside down.
You can therefore choose which orientation you want by swapping the TX/RX pin connections.

== Using UART ==

First, use your UART dongle to physically connect your PineNote to your computer:
# Plug the USB-UART adapter into one of your computer's USB ports
# Plug the USB-C breakout board into the USB-C port on the bottom of your PineNote; the orientation matters, so try both and remember which one works

Once the hardware is connected, set up your computer's software as follows:
# Install [https://www.gnu.org/software/screen/ GNU Screen] (or [https://askubuntu.com/q/40959 some other option], but the instructions below are written for <code>screen</code>)
# Identify the USB-UART adapter in your <code>/dev</code> directory by running <code>ls /dev</code> with it plugged in, unplugging it, then again running <code>ls /dev</code> and seeing what changes; it is likely to be called <code>/dev/ttyUSB0</code>
# In a terminal window, run <code>screen -L /dev/ttyUSB0 1500000</code> (you may need to run this as sudo depending on your user's permissions; on most Linux distributions you need to be in the <code>dialout</code> usergroup)

Once the software is set up, power-cycle your PineNote; as the system boots you should see text appearing in your terminal window.
You can exit the screen session with <code>ctrl+a k</code> then pressing <code>y</code> to confirm.
The <code>screen -L</code> flag outputs a text log of the session to the current working directory, probably called <code>screenlog.0</code>.

==== Troubleshooting ====

If you don't see any text in your terminal as the PineNote boots, or the text is garbled, try the following:
* Ensure your GND, RX and TX jump wires are connected to the correct pins on both the USB-UART adapter and the USB-C breakout board
* Connect your USB-C breakout board to your PineNote in the opposite orientation
* Run the screen command as sudo in case your user doesn't have appropriate permissions
* Ensure you are setting the baud rate in the <code>screen</code> command to 1500000 (1.5 million)

== USB passthrough ==

If your USB-C breakout board has a passthrough/intercept design, you can connect to your PineNote over USB and UART at the same time.
This can be useful when you're doing development work on the PineNote boot process so you don't have to continually reconnect cables.
You'll need a USB-A to USB-C cable, connecting directly from your computer's USB-A hub to your USB-C breakout board's female USB-C port.
It's important to connect directly from USB-A, without any intermediate USB-C components.
Note that connecting a live USB cable to your USB-C breakout board in this way dramatically increases the danger of frying your PineNote with a short, so you should only do this if all connectors are safely wrapped in electrical tape.

[[Category:PineNote]]

PineNote Development/UART

2023-10-14T01:10:27Z

Ahelwer: /* Creating a dongle */ Adding instructions for creating Y-shaped pull-up resistor cable

[[File:Pinenote-uart-dongle.jpeg|thumb|Basic non-stock PineNote UART dongle]]

This page contains information on creating and using a [https://en.wikipedia.org/wiki/Universal_asynchronous_receiver-transmitter UART] dongle for the [[PineNote]].
The PineNote was shipped with a compatible UART dongle, but replacements are not available to order in case of loss or hardware fault.
Thankfully it is not difficult to make your own from easily-acquired components and a small bit of soldering.
Fear not if you've never soldered anything before!
This serves as an excellent first soldering project.
Borrow the tools from a friend or a local hackerspace or tool library.

A PineNote UART dongle enables you to:
# Interact with the system boot menu
# Read system events in real time as the PineNote is used
# Fix the PineNote without opening the case if something goes wrong while [[PineNote Development/Flashing|flashing it]]

Since the PineNote is an embedded system, interfacing with it during boot is more complicated than with an ordinary computer.
The UART dongle enables you to do this.

The PineNote factory firmware runs UART at a baud rate of 1500000 bps, 8 data bits, 1 stop bit, no parity and no flow control.
The process by which the PineNote design was modified to include closed-case UART is documented [[PineNote/Hardware Changes/Closed Case UART|here]].

== Stock dongle ==

The stock UART dongle included with the PineNote was a simple device plugging directly into the PineNote's USB-C port.
The dongle exposed a female USB-C port, which the user plugged into to get UART access.
This design unfortunately ruled out passthrough USB connections, where the user connects to the PineNote via UART and USB simultaneously.
The dongle is not currently available for purchase.

<gallery>
Pinenote-stock-uart-dongle-front.jpg|Front
Pinenote-stock-uart-dongle-back.jpg|Back
</gallery>

== Creating a dongle ==

A typical self-built PineNote UART dongle design has the following components:
# A USB-C breakout board with a male connector exposing the 24 pins of the PineNote's USB-C port
# A USB-UART adapter, to plug into a USB port of the computer you'll use to interface with the PineNote
# [https://en.wikipedia.org/wiki/Jump_wire Jump wires] to connect specific breakout board pins to pins on the USB-UART adapter
# Two 1,000 Ohm through-hole resistors to splice into the jump wires
# Electrical tape or heat shrink to wrap connectors and prevent shorts

The PineNote's internal UART system is documented in [https://files.pine64.org/doc/PineNote/PineNote_USB-C_Console_UART_breakout_board_schematic_v1.0_20210903.pdf this schematic].
The purpose of all 24 USB-C pins is documented [https://en.wikipedia.org/wiki/USB-C#Receptacles on the USB-C Wikipedia page].
We are interested in three sets of pins:
# The SBU1 (A8) and SBU2 (B8) side band use pins
# The CC1 (A5) and CC2 (B5) configuration channel pins
# The GND [https://en.wikipedia.org/wiki/Ground_(electricity) ground return] pins (A1, A12, B1, and B12)

In the PineNote UART schematic you can see (on the bottom right diagram labeled <code>USB_TYPEC_Male</code>) the side band pins are given the labels <code>UART2_TX_SUB1</code> for A8 and <code>UART2_RX_SUB2</code> for B8.
The first (TX) is used for transmitting data and the second (RX) is used for receiving data, from the perspective of the PineNote.
Also note the configuration channel pins labeled <code>TYPEC_CC1</code> for A5 and <code>TYPEC_CC2</code> for B5.
These pins are used to signal to the PineNote that a UART dongle is present.
The diagram shows they must be connected to a 3.3V source in parallel, mediated by resistors.
The schematic indicates 10,000 Ohm resistors, but community member talpadk experimented and found 1,000 Ohm resistors work better.
Our mission is to wire up pins from a USB-UART adapter to a USB-C breakout board following these requirements.

=== Buying components ===

There are many possible USB-C breakout board designs available for purchase online.
One particularly useful design is a "passthrough" or "intercept" style, with both male and female USB-C ports.
This design is more versatile in case you want to reuse it in other projects, and also enables you to connect to the PineNote via UART and USB at the same time.
An example of this product can be found [https://pmdway.com/products/usb-3-1-type-c-male-to-female-breakout-test-board here], although you are encouraged to shop around for cheaper options.
If you're fine with a bit more soldering, there is a very cheap one [https://www.ebay.com/itm/275407037613 here].

Similarly, there are many USB-UART adapter designs available.
These devices plug into your computer and expose a number of pins themselves, connecting to specific pins on the breakout board with jump wires.
It is important to get a 3.3V model, or at least a model with the option of 3.3V, as a 5V model might fry the PineNote.
[https://pmdway.com/products/usb-to-ttl-serial-cp2104-6-pin-converter-module Here] is one example with jump wires included, although you are again encouraged to shop around for alternatives.

All other necessary components of our UART dongle are readily & cheaply available in many locations.

=== Splicing resistors ===

This is the only difficult part of the whole process.
Your goal is to create a Y-shaped jump wire with 1,000 Ohm through-hole resistors spliced into each of the twin arms.
The solitary leg will connect to a 3.3V source on your USB-UART adapter.
The twin arms will connect to the configuration channel pins on your USB-C breakout board.
These are called pull-up resistors, and you can read a nice introduction to their purpose [https://www.electronics-tutorials.ws/logic/pull-up-resistor.html here].

For this project you'll need:
# A soldering iron with solder
# Wire cutters & strippers
# 2x jumper wires, male/female as compatible with your board designs
# 2x 1,000 Ohm through-hole resistors
# Electrical tape or heat shrink wrap

Consider buying extra jumper wires and resistors in case you mess up.
Also double-check that you have 1K resistors with [https://resistorcolorcodecalc.com/ this color code calculator].
Although the PineNote UART schematic says to use 10K Ohm resistors, community member talpadk experimented and found 1K is more appropriate.
Assemble your Y-cable as follows:
# Graft one jump wire onto the other to form a Y shape using [https://www.youtube.com/watch?v=KpiEfuhPqew this] technique, ensuring solitary leg end is compatible with your USB-UART adapter
# Splice resistors into the twin arms using [https://www.youtube.com/watch?v=RMgMVqqjPZ0 this] technique
# Splice remaining jump wire onto the ends of the resistors, ensuring ends are compatible with your USB-C breakout board
# Cover all exposed wire & resistors with electrical tape or heat shrink wrap

=== Assembly ===

Once you have acquired all necessary components, assemble the UART dongle as follows:
# Connect a jump wire from the GND pin on the USB-UART adapter to any one of the four GND pins on the USB-C breakout board (A1, A12, B1, or B12)
# Connect a jump wire from the RXD pin on the USB-UART adapter to the SBU1 pin on the USB-C breakout board (A8)
# Connect a jump wire from the TXD pin on the USB-UART adapter to the SBU2 pin on the USB-C breakout board (B8)
# Connect your Y-shaped jump wire from the 3.3V source pin on the USB-UART adapter to the CC1 and CC2 pins on the USB-C breakout board (A5 and B5)
# Wrap all metal connectors in electrical tape or heat shrink to prevent accidental shorts

Be '''very certain''' of your connections for the 3.3V source, as there is a real risk of irreparably frying your PineNote if they're wrong!
Especially be sure you are connecting to a 3.3V source and not a 5V source.

Note that if you mix up the TX/RX pins, it will still work but the USB-C breakout board will just plug into the PineNote upside down.
You can therefore choose which orientation you want by swapping the TX/RX pin connections.

== Using UART ==

First, use your UART dongle to physically connect your PineNote to your computer:
# Plug the USB-UART adapter into one of your computer's USB ports
# Plug the USB-C breakout board into the USB-C port on the bottom of your PineNote; the orientation matters, so try both and remember which one works

Once the hardware is connected, set up your computer's software as follows:
# Install [https://www.gnu.org/software/screen/ GNU Screen] (or [https://askubuntu.com/q/40959 some other option], but the instructions below are written for <code>screen</code>)
# Identify the USB-UART adapter in your <code>/dev</code> directory by running <code>ls /dev</code> with it plugged in, unplugging it, then again running <code>ls /dev</code> and seeing what changes; it is likely to be called <code>/dev/ttyUSB0</code>
# In a terminal window, run <code>screen -L /dev/ttyUSB0 1500000</code> (you may need to run this as sudo depending on your user's permissions; on most Linux distributions you need to be in the <code>dialout</code> usergroup)

Once the software is set up, power-cycle your PineNote; as the system boots you should see text appearing in your terminal window.
You can exit the screen session with <code>ctrl+a k</code> then pressing <code>y</code> to confirm.
The <code>screen -L</code> flag outputs a text log of the session to the current working directory, probably called <code>screenlog.0</code>.

==== Troubleshooting ====

If you don't see any text in your terminal as the PineNote boots, or the text is garbled, try the following:
* Ensure your GND, RX and TX jump wires are connected to the correct pins on both the USB-UART adapter and the USB-C breakout board
* Connect your USB-C breakout board to your PineNote in the opposite orientation
* Run the screen command as sudo in case your user doesn't have appropriate permissions
* Ensure you are setting the baud rate in the <code>screen</code> command to 1500000 (1.5 million)

== USB passthrough ==

If your USB-C breakout board has a passthrough/intercept design, you can connect to your PineNote over USB and UART at the same time.
This can be useful when you're doing development work on the PineNote boot process so you don't have to continually reconnect cables.
You'll need a USB-A to USB-C cable, connecting directly from your computer's USB-A hub to your USB-C breakout board's female USB-C port.
It's important to connect directly from USB-A, without any intermediate USB-C components.
Note that connecting a live USB cable to your USB-C breakout board in this way dramatically increases the danger of frying your PineNote with a short, so you should only do this if all connectors are safely wrapped in electrical tape.

[[Category:PineNote]]

PineNote Development/UART

2023-10-13T21:47:29Z

Ahelwer: Began documenting process of splicing resistors into wires

PineNote Development/UART

2023-10-12T21:18:10Z

Ahelwer: /* Creating a dongle */ Added note about 3.3V UART

PineNote Development/Flashing

2023-10-12T20:52:30Z

Ahelwer: /* Entering Maskrom/Rockusb Mode */

{{Under construction}}

{{Info|These instructions are directed towards experienced developers only!}}

This page contains information on flashing software to the [https://wiki.pine64.org/wiki/PineNote PineNote].

Currently, software can be flashed using rkdeveloptool or from the factory Android installation (UART shell, adb, or fastboot).

== Getting <code>rkdeveloptool</code> ==

Most flashing operations on the PineNote are done through <code>rkdeveloptool</code>, a command line utility built on libusb.
PINE64 maintains its own fork [https://gitlab.com/pine64-org/quartz-bsp/rkdeveloptool here] that you will need to get.
The repo's README contains a list of dependencies (libusb 1.0) and instructions for building the tool.

Installing (not just building) <code>rkdeveloptool</code> will configure PAM to elevate privileges where necessary on your system; you can configure this manually as follows:
<pre>
sudo cp 99-rk-rockusb.rules /etc/udev/rules.d/
sudo udevadm control --reload
</pre>

== Entering Maskrom/Rockusb mode ==

Interfacing with the PineNote over USB using <code>rkdeveloptool</code> requires first booting the PineNote into [http://opensource.rock-chips.com/wiki_Rockusb an alternative operating mode] called Maskrom or Rockusb mode.

=== Possible Methods ===

There are three possible methods of entering Maskrom/Rockusb mode:

==== Hardware Magnet Switch ====

# Connect the PineNote to your computer via USB and boot the PineNote into Android
# Locate & identify the small circular marking on the back of the PineNote, in the top right quadrant; have the PineNote pen close at hand, or any other small magnet
# Hold the PineNote power button to bring up the reboot/shutdown menu; select reboot, then place the PineNote face down with the "eraser" end of the pen (or your magnet) resting on the small circular marking

<gallery>
Download mode.jpeg|Pen method
PineNoteMagnetOnBack.jpg|Magnet method
</gallery>

==== U-Boot ====
This method requires a [[PineNote Development/UART|UART dongle for the PineNote]] with passthrough allowing simultaneous UART & USB connections.
It is nice because you can easily switch back & forth between U-Boot and Rockusb without having to physically manipulate the PineNote or its connectors; this is especially helpful when trying to develop U-Boot.

# 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.

==== 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]]

=== Success ===

No matter what approach you take, you can tell whether you succeeded by running the <code>lsusb</code> command on your computer:
* If you find the entry <code>2207:0018 Fuzhou Rockchip Electronics Company rk3566_eink</code> in the list, the process did not succeed; reboot and retry
* The entry <code>2207:350a Fuzhou Rockchip Electronics Company</code> will occur if you detach then reattach the USB-C cable while the PineNote is in Maskrom/Rockusb mode; <code>rkdeveloptool</code> won't work and you will have to do a hard reboot (hold down power button for 30 seconds to shutdown)
* If you find the entry <code>2207:350a Fuzhou Rockchip Electronics Company USB download gadget</code> then the process succeeded

You can also look at the output of the <code>rkdeveloptool list</code> command:
* If this prints out <code>No devices in rockusb mode found</code> the process did not succeed; reboot and retry
* If this prints out <code>DevNo=1 Vid=0x2207,Pid=0x350a,LocationID=305 Maskrom</code> then you probably detached/reattached the USB-C cable while in Maskrom/Rockusb mode and <code>rkdeveloptool</code> won't work; perform a hard reboot to fix
* If this prints out <code>DevNo=1 Vid=0x2207,Pid=0x350a,LocationID=303 Loader</code> then the process succeeded

=== Exiting mode ===

You can boot the PineNote back into its normal mode of operation by powercycling the PineNote with its hardware power switch, or running the <code>rkdeveloptool reboot</code> command.
If you used the magnetic switch method be sure to remove the pen/magnet before rebooting.

== Backup ==

A backup of the content of the internal eMMC before anything gets messed up is '''mandatory'''.

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

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) contain data you may also 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.

This process was developed by Dorian Rudolph, originally described [https://github.com/DorianRudolph/pinenotes here].

=== List partitions ===

First, run <code>rkdeveloptool list-partitions</code> to print out your PineNote's partitions to get an idea of what you're dealing with.
The stock PineNote has a fairly standard Android partition setup, including:
* uboot: the [https://en.wikipedia.org/wiki/Das_U-Boot U-Boot] embedded systems bootloader
* trust: secrets that can be encrypted with a key stored in the [https://en.wikipedia.org/wiki/Trusted_Platform_Module TPM]
* waveform: important files controlling the e-ink screen's state changes
* misc: miscellaneous files needed by the firmware
* dtbo: [https://en.wikipedia.org/wiki/Devicetree Device Tree Blob for Overlay], files describing the PineNote's hardware configuration
* vbmeta: data required for verified boot
* boot, security, recovery, backup, cache, metadata, super, logo, device
* userdata: the big one; this is where all your files are stored in the stock Android install

=== Patch U-Boot ===

Before we can back up our partitions, we have a problem to solve.
The version of U-Boot installed on the stock PineNote contains a bug where it can't dump partitions beyond 32 MB (above that limit all bytes in the dump are just <code>0xCC</code>), meaning the PineNote must be flashed with a fixed version of U-Boot before it is possible to take a backup of the larger partitions.
It is possible to extract and modify the U-Boot image from your PineNote if you're interested in some light reverse-engineering (following Dorian's notes), or you can simply download a patched U-Boot image directly [https://github.com/DorianRudolph/pinenotes/blob/main/static/uboot_patched.img here].

Once you've acquired a patched U-Boot image, run:
# <code>rkdeveloptool read-partition uboot uboot_backup.img</code>
# <code>rkdeveloptool write-partition uboot uboot_patched.img</code>
# <code>rkdeveloptool reboot</code>

=== Taking the backup ===

There is a second backup limit preventing dumping partitions larger than 2 GB, this time from <code>rkdeveloptool</code>.
This means if you have a large number of documents in the Android userdata partition they might not all make it into the backup.
If you don't have many documents (or don't care about losing them) this should not be a problem.
If you do have a lot of documents, workarounds include:
* A possible patch written by Thomas exists [https://github.com/tpwrules/nixos-pinenote/blob/96d2c9158edb9da59afcb952cc864fada18382f9/nix/rkdeveloptool/0001-fix-large-dumps.patch here] but has not yet been upstreamed; consider investigating how to get the patch tested & upstreamed, or just apply it to your own local copy of <code>rkdeveloptool</code>
* Use [https://github.com/talpadk/pinenote-backup this] Python script written by Visti Andresen to automatically backup your entire partition by splitting reads into 2 GB chunks

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].

=== 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.

== 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 ==

=== 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 current version (current as of 2022-01-02), there might have to be made 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>

You can now download u-boot onto the PineNote:

./rkdeveloptool boot ../u-boot-rockchip/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

{{Note|'''TODO:''' Section needs to be finished}}

=== 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 [[PineNote Development/Flashing#Creating a mainline boot image|Creating a mainline boot image]], 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 or
* get a U-Boot prompt and run <code>fastboot usb 0</code>.

[[Category:PineNote]]

PineNote Development/Flashing

2023-10-12T15:55:45Z

Ahelwer: /* Exiting mode */ Added note about removing magnet before rebooting

{{Under construction}}

{{Info|These instructions are directed towards experienced developers only!}}

This page contains information on flashing software to the [https://wiki.pine64.org/wiki/PineNote PineNote].

Currently, software can be flashed using rkdeveloptool or from the factory Android installation (UART shell, adb, or fastboot).

== Getting <code>rkdeveloptool</code> ==

Most flashing operations on the PineNote are done through <code>rkdeveloptool</code>, a command line utility built on libusb.
PINE64 maintains its own fork [https://gitlab.com/pine64-org/quartz-bsp/rkdeveloptool here] that you will need to get.
The repo's README contains a list of dependencies (libusb 1.0) and instructions for building the tool.

Installing (not just building) <code>rkdeveloptool</code> will configure PAM to elevate privileges where necessary on your system; you can configure this manually as follows:
<pre>
sudo cp 99-rk-rockusb.rules /etc/udev/rules.d/
sudo udevadm control --reload
</pre>

== Entering Maskrom/Rockusb Mode ==

Interfacing with the PineNote over USB using <code>rkdeveloptool</code> requires first booting the PineNote into an alternative operating mode called Maskrom or Rockusb mode.

=== Possible Methods ===

There are three possible methods of entering Maskrom/Rockusb mode:

==== Hardware Magnet Switch ====

# Connect the PineNote to your computer via USB and boot the PineNote into Android
# Locate & identify the small circular marking on the back of the PineNote, in the top right quadrant; have the PineNote pen close at hand, or any other small magnet
# Hold the PineNote power button to bring up the reboot/shutdown menu; select reboot, then place the PineNote face down with the "eraser" end of the pen (or your magnet) resting on the small circular marking

<gallery>
Download mode.jpeg|Pen method
PineNoteMagnetOnBack.jpg|Magnet method
</gallery>

==== U-Boot ====
This method requires a [[PineNote Development/UART|UART dongle for the PineNote]] with passthrough allowing simultaneous UART & USB connections.
It is nice because you can easily switch back & forth between U-Boot and Rockusb without having to physically manipulate the PineNote or its connectors; this is especially helpful when trying to develop U-Boot.

# 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.

==== 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]]

=== Success ===

No matter what approach you take, you can tell whether you succeeded by running the <code>lsusb</code> command on your computer:
* If you find the entry <code>2207:0018 Fuzhou Rockchip Electronics Company rk3566_eink</code> in the list, the process did not succeed; reboot and retry
* The entry <code>2207:350a Fuzhou Rockchip Electronics Company</code> will occur if you detach then reattach the USB-C cable while the PineNote is in Maskrom/Rockusb mode; <code>rkdeveloptool</code> won't work and you will have to do a hard reboot (hold down power button for 30 seconds to shutdown)
* If you find the entry <code>2207:350a Fuzhou Rockchip Electronics Company USB download gadget</code> then the process succeeded

You can also look at the output of the <code>rkdeveloptool list</code> command:
* If this prints out <code>No devices in rockusb mode found</code> the process did not succeed; reboot and retry
* If this prints out <code>DevNo=1 Vid=0x2207,Pid=0x350a,LocationID=305 Maskrom</code> then you probably detached/reattached the USB-C cable while in Maskrom/Rockusb mode and <code>rkdeveloptool</code> won't work; perform a hard reboot to fix
* If this prints out <code>DevNo=1 Vid=0x2207,Pid=0x350a,LocationID=303 Loader</code> then the process succeeded

=== Exiting mode ===

You can boot the PineNote back into its normal mode of operation by powercycling the PineNote with its hardware power switch, or running the <code>rkdeveloptool reboot</code> command.
If you used the magnetic switch method be sure to remove the pen/magnet before rebooting.

== Backup ==

A backup of the content of the internal eMMC before anything gets messed up is '''mandatory'''.

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

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) contain data you may also 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.

This process was developed by Dorian Rudolph, originally described [https://github.com/DorianRudolph/pinenotes here].

=== List partitions ===

First, run <code>rkdeveloptool list-partitions</code> to print out your PineNote's partitions to get an idea of what you're dealing with.
The stock PineNote has a fairly standard Android partition setup, including:
* uboot: the [https://en.wikipedia.org/wiki/Das_U-Boot U-Boot] embedded systems bootloader
* trust: secrets that can be encrypted with a key stored in the [https://en.wikipedia.org/wiki/Trusted_Platform_Module TPM]
* waveform: important files controlling the e-ink screen's state changes
* misc: miscellaneous files needed by the firmware
* dtbo: [https://en.wikipedia.org/wiki/Devicetree Device Tree Blob for Overlay], files describing the PineNote's hardware configuration
* vbmeta: data required for verified boot
* boot, security, recovery, backup, cache, metadata, super, logo, device
* userdata: the big one; this is where all your files are stored in the stock Android install

=== Patch U-Boot ===

Before we can back up our partitions, we have a problem to solve.
The version of U-Boot installed on the stock PineNote contains a bug where it can't dump partitions beyond 32 MB (above that limit all bytes in the dump are just <code>0xCC</code>), meaning the PineNote must be flashed with a fixed version of U-Boot before it is possible to take a backup of the larger partitions.
It is possible to extract and modify the U-Boot image from your PineNote if you're interested in some light reverse-engineering (following Dorian's notes), or you can simply download a patched U-Boot image directly [https://github.com/DorianRudolph/pinenotes/blob/main/static/uboot_patched.img here].

Once you've acquired a patched U-Boot image, run:
# <code>rkdeveloptool read-partition uboot uboot_backup.img</code>
# <code>rkdeveloptool write-partition uboot uboot_patched.img</code>
# <code>rkdeveloptool reboot</code>

=== Taking the backup ===

There is a second backup limit preventing dumping partitions larger than 2 GB, this time from <code>rkdeveloptool</code>.
This means if you have a large number of documents in the Android userdata partition they might not all make it into the backup.
If you don't have many documents (or don't care about losing them) this should not be a problem.
If you do have a lot of documents, workarounds include:
* A possible patch written by Thomas exists [https://github.com/tpwrules/nixos-pinenote/blob/96d2c9158edb9da59afcb952cc864fada18382f9/nix/rkdeveloptool/0001-fix-large-dumps.patch here] but has not yet been upstreamed; consider investigating how to get the patch tested & upstreamed, or just apply it to your own local copy of <code>rkdeveloptool</code>
* Use [https://github.com/talpadk/pinenote-backup this] Python script written by Visti Andresen to automatically backup your entire partition by splitting reads into 2 GB chunks

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].

=== 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.

== 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 ==

=== 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 current version (current as of 2022-01-02), there might have to be made 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>

You can now download u-boot onto the PineNote:

./rkdeveloptool boot ../u-boot-rockchip/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

{{Note|'''TODO:''' Section needs to be finished}}

=== 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 [[PineNote Development/Flashing#Creating a mainline boot image|Creating a mainline boot image]], 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 or
* get a U-Boot prompt and run <code>fastboot usb 0</code>.

[[Category:PineNote]]

PineNote Development/Flashing

2023-10-12T15:52:38Z

Ahelwer: /* Success */ Added note about detaching USB cable in Maskrom/Rockusb mode

{{Under construction}}

{{Info|These instructions are directed towards experienced developers only!}}

This page contains information on flashing software to the [https://wiki.pine64.org/wiki/PineNote PineNote].

Currently, software can be flashed using rkdeveloptool or from the factory Android installation (UART shell, adb, or fastboot).

== Getting <code>rkdeveloptool</code> ==

Most flashing operations on the PineNote are done through <code>rkdeveloptool</code>, a command line utility built on libusb.
PINE64 maintains its own fork [https://gitlab.com/pine64-org/quartz-bsp/rkdeveloptool here] that you will need to get.
The repo's README contains a list of dependencies (libusb 1.0) and instructions for building the tool.

Installing (not just building) <code>rkdeveloptool</code> will configure PAM to elevate privileges where necessary on your system; you can configure this manually as follows:
<pre>
sudo cp 99-rk-rockusb.rules /etc/udev/rules.d/
sudo udevadm control --reload
</pre>

== Entering Maskrom/Rockusb Mode ==

Interfacing with the PineNote over USB using <code>rkdeveloptool</code> requires first booting the PineNote into an alternative operating mode called Maskrom or Rockusb mode.

=== Possible Methods ===

There are three possible methods of entering Maskrom/Rockusb mode:

==== Hardware Magnet Switch ====

# Connect the PineNote to your computer via USB and boot the PineNote into Android
# Locate & identify the small circular marking on the back of the PineNote, in the top right quadrant; have the PineNote pen close at hand, or any other small magnet
# Hold the PineNote power button to bring up the reboot/shutdown menu; select reboot, then place the PineNote face down with the "eraser" end of the pen (or your magnet) resting on the small circular marking

<gallery>
Download mode.jpeg|Pen method
PineNoteMagnetOnBack.jpg|Magnet method
</gallery>

==== U-Boot ====
This method requires a [[PineNote Development/UART|UART dongle for the PineNote]] with passthrough allowing simultaneous UART & USB connections.
It is nice because you can easily switch back & forth between U-Boot and Rockusb without having to physically manipulate the PineNote or its connectors; this is especially helpful when trying to develop U-Boot.

# 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.

==== 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]]

=== Success ===

No matter what approach you take, you can tell whether you succeeded by running the <code>lsusb</code> command on your computer:
* If you find the entry <code>2207:0018 Fuzhou Rockchip Electronics Company rk3566_eink</code> in the list, the process did not succeed; reboot and retry
* The entry <code>2207:350a Fuzhou Rockchip Electronics Company</code> will occur if you detach then reattach the USB-C cable while the PineNote is in Maskrom/Rockusb mode; <code>rkdeveloptool</code> won't work and you will have to do a hard reboot (hold down power button for 30 seconds to shutdown)
* If you find the entry <code>2207:350a Fuzhou Rockchip Electronics Company USB download gadget</code> then the process succeeded

You can also look at the output of the <code>rkdeveloptool list</code> command:
* If this prints out <code>No devices in rockusb mode found</code> the process did not succeed; reboot and retry
* If this prints out <code>DevNo=1 Vid=0x2207,Pid=0x350a,LocationID=305 Maskrom</code> then you probably detached/reattached the USB-C cable while in Maskrom/Rockusb mode and <code>rkdeveloptool</code> won't work; perform a hard reboot to fix
* If this prints out <code>DevNo=1 Vid=0x2207,Pid=0x350a,LocationID=303 Loader</code> then the process succeeded

=== Exiting mode ===

You can boot the PineNote back into its normal mode of operation by powercycling the PineNote with its hardware power switch, or running the <code>rkdeveloptool reset</code> command.

== Backup ==

A backup of the content of the internal eMMC before anything gets messed up is '''mandatory'''.

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

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) contain data you may also 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.

This process was developed by Dorian Rudolph, originally described [https://github.com/DorianRudolph/pinenotes here].

=== List partitions ===

First, run <code>rkdeveloptool list-partitions</code> to print out your PineNote's partitions to get an idea of what you're dealing with.
The stock PineNote has a fairly standard Android partition setup, including:
* uboot: the [https://en.wikipedia.org/wiki/Das_U-Boot U-Boot] embedded systems bootloader
* trust: secrets that can be encrypted with a key stored in the [https://en.wikipedia.org/wiki/Trusted_Platform_Module TPM]
* waveform: important files controlling the e-ink screen's state changes
* misc: miscellaneous files needed by the firmware
* dtbo: [https://en.wikipedia.org/wiki/Devicetree Device Tree Blob for Overlay], files describing the PineNote's hardware configuration
* vbmeta: data required for verified boot
* boot, security, recovery, backup, cache, metadata, super, logo, device
* userdata: the big one; this is where all your files are stored in the stock Android install

=== Patch U-Boot ===

Before we can back up our partitions, we have a problem to solve.
The version of U-Boot installed on the stock PineNote contains a bug where it can't dump partitions beyond 32 MB (above that limit all bytes in the dump are just <code>0xCC</code>), meaning the PineNote must be flashed with a fixed version of U-Boot before it is possible to take a backup of the larger partitions.
It is possible to extract and modify the U-Boot image from your PineNote if you're interested in some light reverse-engineering (following Dorian's notes), or you can simply download a patched U-Boot image directly [https://github.com/DorianRudolph/pinenotes/blob/main/static/uboot_patched.img here].

Once you've acquired a patched U-Boot image, run:
# <code>rkdeveloptool read-partition uboot uboot_backup.img</code>
# <code>rkdeveloptool write-partition uboot uboot_patched.img</code>
# <code>rkdeveloptool reboot</code>

=== Taking the backup ===

There is a second backup limit preventing dumping partitions larger than 2 GB, this time from <code>rkdeveloptool</code>.
This means if you have a large number of documents in the Android userdata partition they might not all make it into the backup.
If you don't have many documents (or don't care about losing them) this should not be a problem.
If you do have a lot of documents, workarounds include:
* A possible patch written by Thomas exists [https://github.com/tpwrules/nixos-pinenote/blob/96d2c9158edb9da59afcb952cc864fada18382f9/nix/rkdeveloptool/0001-fix-large-dumps.patch here] but has not yet been upstreamed; consider investigating how to get the patch tested & upstreamed, or just apply it to your own local copy of <code>rkdeveloptool</code>
* Use [https://github.com/talpadk/pinenote-backup this] Python script written by Visti Andresen to automatically backup your entire partition by splitting reads into 2 GB chunks

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].

=== 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.

== 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 ==

=== 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 current version (current as of 2022-01-02), there might have to be made 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>

You can now download u-boot onto the PineNote:

./rkdeveloptool boot ../u-boot-rockchip/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

{{Note|'''TODO:''' Section needs to be finished}}

=== 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 [[PineNote Development/Flashing#Creating a mainline boot image|Creating a mainline boot image]], 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 or
* get a U-Boot prompt and run <code>fastboot usb 0</code>.

[[Category:PineNote]]

PineNote Development/UART

2023-10-12T15:29:08Z

Ahelwer: /* Creating a dongle */

PineNote Development/UART

2023-10-12T15:23:50Z

Ahelwer: /* Creating a dongle */

PineNote Development/UART

2023-10-12T15:22:03Z

Ahelwer: TX/RX pin connections and orientation

PineNote Development/UART

2023-10-12T15:17:33Z

Ahelwer: /* Creating a dongle */ reverse TXD/RXD pin instructions

PineNote Development/UART

2023-10-12T13:19:45Z

Ahelwer: /* Using UART */ added note about dialout usergroup

PineNote Development/UART

2023-10-12T13:10:17Z

Ahelwer: Added explanatory links to wikipedia

File:Pinenote-stock-uart-dongle-back.jpg

2023-10-12T00:18:01Z

Ahelwer: Ahelwer uploaded a new version of File:Pinenote-stock-uart-dongle-back.jpg

== Summary ==
Photo of the back of the stock UART dongle shipped from Pine64 with the PineNote. Photo provided by user aarondabomb.
== Licensing ==
{{CC0}}
[[Category:PineNote]]

File:Pinenote-stock-uart-dongle-front.jpg

2023-10-12T00:17:02Z

Ahelwer: Ahelwer uploaded a new version of File:Pinenote-stock-uart-dongle-front.jpg

== Summary ==
Photo of the front of the stock UART dongle shipped from Pine64 with the PineNote. Photo provided by user aarondabomb.
== Licensing ==
{{CC0}}
[[Category:PineNote]]

PineNote Development/Flashing

2023-10-12T00:11:49Z

Ahelwer: /* Backup */ Expanded manual backup section

{{Under construction}}

{{Info|These instructions are directed towards experienced developers only!}}

This page contains information on flashing software to the [https://wiki.pine64.org/wiki/PineNote PineNote].

Currently, software can be flashed using rkdeveloptool or from the factory Android installation (UART shell, adb, or fastboot).

== Getting <code>rkdeveloptool</code> ==

Most flashing operations on the PineNote are done through <code>rkdeveloptool</code>, a command line utility built on libusb.
PINE64 maintains its own fork [https://gitlab.com/pine64-org/quartz-bsp/rkdeveloptool here] that you will need to get.
The repo's README contains a list of dependencies (libusb 1.0) and instructions for building the tool.

Installing (not just building) <code>rkdeveloptool</code> will configure PAM to elevate privileges where necessary on your system; you can configure this manually as follows:
<pre>
sudo cp 99-rk-rockusb.rules /etc/udev/rules.d/
sudo udevadm control --reload
</pre>

== Entering Maskrom/Rockusb Mode ==

Interfacing with the PineNote over USB using <code>rkdeveloptool</code> requires first booting the PineNote into an alternative operating mode called Maskrom or Rockusb mode.

=== Possible Methods ===

There are three possible methods of entering Maskrom/Rockusb mode:

==== Hardware Magnet Switch ====

# Connect the PineNote to your computer via USB and boot the PineNote into Android
# Locate & identify the small circular marking on the back of the PineNote, in the top right quadrant; have the PineNote pen close at hand, or any other small magnet
# Hold the PineNote power button to bring up the reboot/shutdown menu; select reboot, then place the PineNote face down with the "eraser" end of the pen (or your magnet) resting on the small circular marking

<gallery>
Download mode.jpeg|Pen method
PineNoteMagnetOnBack.jpg|Magnet method
</gallery>

==== U-Boot ====
This method requires a [[PineNote Development/UART|UART dongle for the PineNote]] with passthrough allowing simultaneous UART & USB connections.
It is nice because you can easily switch back & forth between U-Boot and Rockusb without having to physically manipulate the PineNote or its connectors; this is especially helpful when trying to develop U-Boot.

# 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.

==== 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]]

=== Success ===

No matter what approach you take, you can tell whether you succeeded by running the <code>lsusb</code> command on your computer:
* If you find the entry <code>2207:0018 Fuzhou Rockchip Electronics Company rk3566_eink</code> in the list, the process did not succeed; reboot and retry
* If you find the entry <code>2207:350a Fuzhou Rockchip Electronics Company USB download gadget</code> then the process succeeded

You can also look at the output of the <code>rkdeveloptool list</code> command:
* If this prints out <code>No devices in rockusb mode found</code> the process did not succeed; reboot and retry
* If this prints out something like <code>DevNo=1 Vid=0x2207,Pid=0x350a,LocationID=303 Loader</code> then the process succeeded

=== Exiting mode ===

You can boot the PineNote back into its normal mode of operation by powercycling the PineNote with its hardware power switch, or running the <code>rkdeveloptool reset</code> command.

== Backup ==

A backup of the content of the internal eMMC before anything gets messed up is '''mandatory'''.

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

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) contain data you may also 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.

This process was developed by Dorian Rudolph, originally described [https://github.com/DorianRudolph/pinenotes here].

=== List partitions ===

First, run <code>rkdeveloptool list-partitions</code> to print out your PineNote's partitions to get an idea of what you're dealing with.
The stock PineNote has a fairly standard Android partition setup, including:
* uboot: the [https://en.wikipedia.org/wiki/Das_U-Boot U-Boot] embedded systems bootloader
* trust: secrets that can be encrypted with a key stored in the [https://en.wikipedia.org/wiki/Trusted_Platform_Module TPM]
* waveform: important files controlling the e-ink screen's state changes
* misc: miscellaneous files needed by the firmware
* dtbo: [https://en.wikipedia.org/wiki/Devicetree Device Tree Blob for Overlay], files describing the PineNote's hardware configuration
* vbmeta: data required for verified boot
* boot, security, recovery, backup, cache, metadata, super, logo, device
* userdata: the big one; this is where all your files are stored in the stock Android install

=== Patch U-Boot ===

Before we can back up our partitions, we have a problem to solve.
The version of U-Boot installed on the stock PineNote contains a bug where it can't dump partitions beyond 32 MB (above that limit all bytes in the dump are just <code>0xCC</code>), meaning the PineNote must be flashed with a fixed version of U-Boot before it is possible to take a backup of the larger partitions.
It is possible to extract and modify the U-Boot image from your PineNote if you're interested in some light reverse-engineering (following Dorian's notes), or you can simply download a patched U-Boot image directly [https://github.com/DorianRudolph/pinenotes/blob/main/static/uboot_patched.img here].

Once you've acquired a patched U-Boot image, run:
# <code>rkdeveloptool read-partition uboot uboot_backup.img</code>
# <code>rkdeveloptool write-partition uboot uboot_patched.img</code>
# <code>rkdeveloptool reboot</code>

=== Taking the backup ===

There is a second backup limit preventing dumping partitions larger than 2 GB, this time from <code>rkdeveloptool</code>.
This means if you have a large number of documents in the Android userdata partition they might not all make it into the backup.
If you don't have many documents (or don't care about losing them) this should not be a problem.
If you do have a lot of documents, workarounds include:
* A possible patch written by Thomas exists [https://github.com/tpwrules/nixos-pinenote/blob/96d2c9158edb9da59afcb952cc864fada18382f9/nix/rkdeveloptool/0001-fix-large-dumps.patch here] but has not yet been upstreamed; consider investigating how to get the patch tested & upstreamed, or just apply it to your own local copy of <code>rkdeveloptool</code>
* Use [https://github.com/talpadk/pinenote-backup this] Python script written by Visti Andresen to automatically backup your entire partition by splitting reads into 2 GB chunks

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].

=== 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.

== 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 ==

=== 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 current version (current as of 2022-01-02), there might have to be made 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>

You can now download u-boot onto the PineNote:

./rkdeveloptool boot ../u-boot-rockchip/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

{{Note|'''TODO:''' Section needs to be finished}}

=== 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 [[PineNote Development/Flashing#Creating a mainline boot image|Creating a mainline boot image]], 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 or
* get a U-Boot prompt and run <code>fastboot usb 0</code>.

[[Category:PineNote]]

PineNote

2023-10-11T23:01:15Z

Ahelwer: /* UART Dongle */

[[File:PineNote-1.jpg|400px|thumb|right|The PineNote]]

The '''PineNote''' is the first hybrid notepad computer device combination of notebook, tablet and e-reader using an e-ink panel. It is derived from the Quartz64 model A SBC and powered by a Rockchip RK3566 quad-core ARM Cortex A55 64-bit processor with a MALI G-52 GPU.

== Introduction ==

=== State of the software ===

The PineNote is based on the in 2021 released Rockchip RK3566 SoC. The upstreaming status of the SoC functionality can be found on the [[Quartz64 Development#Upstreaming Status|Quartz64 development]] wiki page of the Quartz64 single-board computer using the same SoC. In the [[PineNote_Development#Kernel_modules_/_mainlining_status|PineNote development]] wiki page you'll find the items specific for the PineNote.

The early adopter's batch of the PineNote is aimed solely at early adopters - more specifically, the units are solely intended to find their way into the hands of users with extensive Linux experience. If you’re looking to buy a PineNote in the first batch, you must expect to write software for it, not to write notes on it. The software shipping from the factory for the first batch will not be suitable for taking notes, reading e-books, or writing your dissertation. It may not even boot to a graphical environment.

An early version of a GNOME-based Debian image is available for [[PineNote_Software_Releases|testing]], but should not be expected to meet general-user readiness.

=== Help and support ===

Still have any questions regarding software, shipping, or ordering after reading this wiki? Please don't hesitate to contact the community in the bridged community channels for detailed answers or simply to chat with friendly people in the community! See [[Main Page#Community and Support]].

Please keep in mind that PINE64 is not like a regular company (see the [https://www.pine64.org/philosophy/ PINE64 philosophy]) and that support resources are limited - the best way to get support quickly is to ask in the community chat! Please only contact the PINE64 support directly if questions couldn't be solved via the community chat or this wiki.

== Software releases ==
While there are no robust and tested operating system releases for the PineNote available at this time, various linux distributions can be installed on the PineNote, with various degrees of working functionality.
Operating system software releases, or efforts to create them, can be found in the [[PineNote Software Releases]] section. Please join the development effort and help creating one.

== Development efforts ==

The following page discusses the development efforts for the PineNote:

* [[PineNote Development]] for general information regarding how to flash the device and other development information.

=== Software ===

* [[PineNote Development/Flashing]] for general flashing instructions of data to the PineNote
* [[PineNote Development/TODOs]]

==== Linux Kernel ====

* [[RK3566 EBC Reverse-Engineering]] for the EBC (eInk Panel) driver.
* [[PineNote Development/Building Kernel]]
* BSP Linux SDK version 4.19 for the PineNote and [[Quartz64|Quartz64 Model A]]:
** [http://files.pine64.org/SDK/Quartz64/QUARTZ64-model-A_BSP%20Linux.tar.gz Direct download] from ''pine64.org'' (32.67GB, MD5 of the TAR-GZip file ''24554419aec29700add97167a3a4c9ed'')
** [https://tmp.mwfc.info/pinenote/QUARTZ64-model-A_BSP%20Linux.tar.gz Mirror by mwfc]
** An unofficial torrent download provided by a community member of the BSP Linux and Android SDKs can be found [https://cdn.discordapp.com/attachments/870707390998282292/907726420204208148/pinenote.torrent here] (100GB).

==== User Space ====

* [[PineNote Development/Booting Linux]]

For tweaks and tricks see:
* [[PineNote Development/Software Tweaks]]

For app development see:
* [[PineNote Development/Apps]]

==== Android ====

Android 11 e-ink SDK for the PineNote and [[Quartz64|Quartz64 Model A]. This is the Android SDK build for 10.3" eink panels on Quartz64 Model A.

Download:
* [http://files.pine64.org/SDK/Quartz64/QUARTZ64-model-A_eink.android11_SDK.tar.gz Direct download] from ''pine64.org'' (72.88GB, MD5 of the TAR-GZip file ''293a550584298de4fb95ceae18103672'')
* [https://tmp.mwfc.info/pinenote/QUARTZ64-model-A_eink.android11_SDK.tar.gz Mirror by mwfc]
* An unofficial torrent download provided by a community member of the BSP Linux and Android SDKs can be found [https://cdn.discordapp.com/attachments/870707390998282292/907726420204208148/pinenote.torrent here] (100GB).
* Just the boot blobs (<1MB): [[File:Rk35-blobs.tar.gz]]

Notes:
* View [[Android SDK for RK3566]] for more information how to compile an image for the PineNote using this SDK

==== Related ====
* [[Quartz64 Development]] for the mainlining status of various functions on the Rockchip RK3566 SoC.

=== Hardware ===

This section includes discussions and their results regarding hardware changes and debugging of the PineNote.

==== Resolved issues ====

The following topics have resolved:

* [[PineNote/Hardware Changes/Closed Case UART]]
* '''Could the USB-C port support USB 3.1 5Gbps?''' Yes and no. The RK3566 only has a host-mode 5Gbps controller, meaning it can only negotiate such a high data rate with a device such as a flash drive. When the RK3566 is acting as a device, it only supports 480Mbps transfer rates. The hardware required to switch between these modes would raise the PineNote's price unreasonably. Therefore, the USB-C port will remain at USB 2.0 speeds for Host and Device mode.
* '''Could the USB-C port output DisplayPort?''' Yes and no. The hardware required to support such a feature would raise the PineNote's price unreasonably. Therefore, DisplayPort output will not be possible through the USB-C port.
* '''Where is the microSD card slot?''' The case design of the PineNote is fixed, making physical changes like adding a microSD card slot would raise the cost unreasonably.
* '''How will I install software to the PineNote?''' This is a hardware and software question. If the software on your PineNote is completely broken and cannot boot to a recoverable state, a Hall (magnet) sensor was fitted to the PineTab motherboard as U9009. This sensor is attached to SARADC_VIN0_KEY/RECOVERY on the RK3566. With the device powered off, and screen face down, holding a magnet over U9009 and plugging in a USB-C cable causes the device to boot into [http://opensource.rock-chips.com/wiki_Rockusb "rockusb"] flash mode. With proper flashing software and drivers, it should be possible to load a new operating system using rockusb if the system is soft-bricked. Of course, software vendors will need to be more careful with flashing firmware and providing useful "recovery" options on this device due to this process's relative difficulty to other PINE64 devices.
* [[PineNote/Battery Replacement]]

==== Unresolved issues ====

The following concerns have been brought up as open, unanswered topics:

* Does [https://en.wikipedia.org/wiki/USB-C#Audio_Adapter_Accessory_Mode_2|USB-C Audio Adapter Accessory Mode] work? It appears that the Headphone output of the audio codec was routed to the USB-C audio+USB switch, but it's unclear whether CC lines are hooked up correctly for detection of such a device. The PineNote hardware team will be testing this functionality soon (as of August 19, 2021). Note that Audio Accessory mode is detectable by reading the I2C registers of the WUSB3801Q. So connecting ASEL to a GPIO would be enough to get this working if it is not working already.
* Why is the Headphone output of the audio codec routed to the speakers? HPL_OUT is routed from the RK817 PMIC and audio codec to U9010 (the USB-C switch) and U6 (the audio amplifier). SPK_OUT is unused. It seems like SPK_OUT should be routed to U6 and HPL_OUT to U9010.
* Nitpick: The cold white charging LED bleeds through the gap between the rear case and the device's face. It does not bleed onto the screen, but it is jarring in low-light conditions or when the screen is amber. Could be resolved in software by turning off the charge LED when the screen is on.
* Is there any way to indicate when the device is in rockusb mode, such as connecting a certain magic pin to the power LED?
* The modem/4G connector (J6010) has its I2C and UART pins unconnected. Could those be connected to the SoC?

==== UART Dongle ====
{{Note|See main article: [[PineNote Development/UART]]}}

The USB UART dongle delivered with the PineNote allows you to have access to a serial port via USB-C Debug Accessory Mode (''DAM'') without having to open up the device.
The factory firmware runs at a baud rate of 1500000bps, 8 data bits 1 stop bit, no parity and no flow control. The USB-C male end should go into the PineNote and the female end can be connected with a standard USB-C cable to your computer.

In case you lose your dongle, you can rebuild one using a USB-C Breakout board.

It is also relatively easy to build your own UART interface with a USB-C breakout board (for example https://www.ebay.com/itm/275407037613), two resistors and a 3.3V USB serial adapter. It is basically just two 1K pull up resistors (R3, R4), the data sheet values of 10K isn't whats on the real hardware, see the [https://files.pine64.org/doc/PineNote/PineNote_USB-C_Console_UART_breakout_board_schematic_v1.0_20210903.pdf schematic]. The pull ups enable the serial output on SBU1 and SBU2 you can use with any 3.3V USB serial adapter.

The UART dongle is not necessary to flash the PineNote, but is essential if something goes wrong to fix it without having to open the case.

You can flash premade images with the following links:
* https://github.com/m-weigand/pinenote_uboot_patching_dorians_backup (Note: this creates a U-Boot image to flash, do not worry about idblock.bin on the instructions for the next link)
* https://github.com/m-weigand/pinenote-debian-recipes/releases/

== Specification ==
[[File:PineNote_Pen_function.jpg|300px|right]]
[[File:PineNote_Cover-1.jpg|300px|right]]

=== General Information ===
* Dimensions: 191.1x232.5x7.4mm
* Weight: 438g

=== Core ===
* CPU: RK3566 1.8GHz 64-bit quad-core A55
* GPU: MALI G52 2EE
* System memory: 4GB LPDDR4
* Flash: 128GB eMMC

=== E-ink Display ===
* Size: 10.3"
* Resolution: 1404x1872
* DPI: 227
* Grayscale: 16
* Front Light: 36 level cold and warm
* Capacitive multi-touch panel
* EMR pen digitizer

=== Network ===
* WiFi: 2.4/5GHz 802.11a/b/g/n/ac
* Bluetooth: 5.0

=== Audio ===
* Built in stereo speakers
* 4 x DMIC microphone

=== Sensor ===
* G-Sensor for portrait and landscape sensing

=== Power ===
* 4000mAH LiPo battery
* DC 5V @ 3A USB-C connector

=== Accessories ===
* Optional EMR pen with magnetic attachment (included in the first production batch)
* Optional Cover (included in the first production batch)

== SoC and Memory Specifications ==
* Based on [https://www.rock-chips.com/a/en/products/RK35_Series/2021/0113/1274.html Rockchip RK3566]
[[File:RK3566_icon.png|right]]

=== CPU Architecture ===
* [https://developer.arm.com/ip-products/processors/cortex-a/cortex-a55 Quad-core ARM Cortex-A55@1.8GHz]
* AArch32 for full backwards compatibility with ARMv7
* ARM Neon Advanced SIMD (single instruction, multiple data) support for accelerated media and signal processing computation
* Includes VFP hardware to support single and double-precision operations
* ARMv8 Cryptography Extensions
* Integrated 32KB L1 instruction cache and 32KB L1 data cache per core
* 512KB unified system L3 cache
* [https://developer.arm.com/ip-products/security-ip/trustzone TrustZone] technology support
* [https://www.cnx-software.com/2020/12/01/rockchip-rk3568-processor-to-power-edge-computing-and-nvr-applications 22nm process, believed to be FD-SOI]

=== GPU (Graphics Processing Unit) Capabilities ===
* [https://developer.arm.com/ip-products/graphics-and-multimedia/mali-gpus/mali-g52-gpu Mali-G52 2EE Bifrost GPU@800MHz]
* 4x Multi-Sampling Anti-Aliasing (MSAA) with minimal performance drop
* 128KB L2 Cache configurations
* Supports OpenGL ES 1.1, 2.0, and 3.2
* Supports Vulkan 1.0 and 1.1
* Supports OpenCL 2.0 Full Profile
* Supports 1600 Mpix/s fill rate when at 800MHz clock frequency
* Supports 38.4 GLOP/s when at 800MHz clock frequency

=== NPU (Neural Processing Unit) Capabilities ===
* Neural network acceleration engine with processing performance of up to 0.8 TOPS
* Supports integer 8 and integer 16 convolution operations
* Supports the following deep learning frameworks: TensorFlow, TF-lite, Pytorch, Caffe, ONNX, MXNet, Keras, Darknet

=== System Memory ===
* RAM Memory : 4GB LPDDR4.
* Flash Memory: 128GB eMMC

== Information, Schematics, and Certifications ==

=== PineNote Developer kit version ===
Version v1.2 is the PineNote production version that was sold through the Pines64 store
* [https://files.pine64.org/doc/PineNote/PINENOTE_MAIN-V1R2%20-%20Schematic-20210824.pdf PineNote Mainboard Schematic ver 1.2 20210824 PDF file]
* [https://files.pine64.org/doc/PineNote/PINENOTE_USB-C-Board-V1.0-sch.pdf PineNote USB-C Daughter Board Schematic ver 1.0 PDF file]
* [https://files.pine64.org/doc/PineNote/PineNote_USB-C_Console_UART_breakout_board_schematic_v1.0_20210903.pdf PineNote USB-C Console UART Breakout Board Schematic ver 1.0 PDF file] Note: When building USB-C console breakout board, please be aware 10k CC pin pull-up is too weak to pull CC to logically high level. Replacing it to lower resistance, such as 1k is recommended.

The v1.1 is early release schematic just for reference only and used by developers who received the prototype.
* [https://files.pine64.org/doc/PineNote/PINENOTE_MAIN-V1R1%20-%20Schematic-20210726.pdf PineNote early released Schematic ver 1.1 20210726 PDF file]
* [https://files.pine64.org/doc/PineNote/PINENOTE_MAIN-V1R1-REF-TOP-20210726.pdf PineNote early released ver 1.1 20210726 PCB Connector placement PDF file]

Certifications:
* [https://files.pine64.org/doc/cert/PineNote%20FCC15C%20Certificate%20DTS-TC561262.pdf PineNote FCC-15C Certificate]
* [https://files.pine64.org/doc/cert/PineNote%20FCC15E%20Certificate%20NII-TC973072.pdf PineNote FCC-15E Certificate]
* [https://files.pine64.org/doc/cert/PineNote%20CE%20RED%20Certicate%20ET-21090682EC.pdf PineNote CE RED Certificate]
* [https://files.pine64.org/doc/cert/PineNote%20RoHS%20Certificate%20ET-210900082C.pdf PineNote ROHS Certificate]

== Datasheets for Components and Peripherals ==

Rockchip RK3566 SoC information:
* [https://files.pine64.org/doc/quartz64/Rockchip%20RK3566%20Datasheet%20V1.0-20201210.pdf Rockchip RK3566 ver 1.0 datasheet, release permission from Rockchip]

Rockchip RK817 PMU (Power Management Unit) Information:
* [https://www.rockchip.fr/RK817%20datasheet%20V1.01.pdf Rockchip RK817 version 1.01 datasheet]

LPDDR4 (200 Balls) SDRAM:
* ---

eMMC information:
* [https://en.biwin.com.cn/product/detail/6 Biwin 128GB eMMC model: BWCTASC41P128G]

E-ink Panel information:
* [https://files.pine64.org/doc/quartz64/Eink%20P-511-828-V1_ED103TC2%20Formal%20Spec%20V1.0_20190514.pdf E-Ink 10.3" 1872x1404 ED103TC2 Glass Panel Specification]
* [https://files.pine64.org/doc/datasheet/PineNote/TI%20PMU-TPS651851.pdf TPS65185x PMIC for E-Ink Enabled Electronic Paper Display Datasheet]

Touch Screen information:
* [https://files.pine64.org/doc/datasheet/PineNote/CYTMA448_Summary_RevC_5-26-16.pdf Cypress CYTMA448 multi-Point Capacitive Touch Controller Datasheet]
* Wacom Pen Digitizer Unit Model: SUDE-10S15MI-01X for 10.3" Display Module

WiFi/BT module information:
* [https://files.pine64.org/doc/datasheet/rockpro64/AW-CM256SM_DS_DF_V1.9_STD.pdf Azurewave CM256SM 11AC WiFi + Bluetooth5.0 Datasheet]]

G Sensor information:
* [http://www.silan.com.cn/en/product/details/47.html#app01 Silan SC7A20 3-Axis MEMS Accelerometer]

Audio Amplifier information:
* [https://files.pine64.org/doc/datasheet/PineNote/Awinic%20AW87318%20Class-K%20Audio%20Amp%20Datasheet.pdf Awinic AW87318 Class-K Audio Amp Datasheet]

== Resources ==
* [[PineNote Press]]

[[Category:PineNote]] [[Category:Rockchip RK3566]]