This site is significiantly improved by visting through the Gemini Protocol.

Why use Gemini?See the Gemini Quickstart to get started!

⇒ ↩ go back to index

a comprehensive guide to setting up a pocketchip

april 15, 2021

This is a tutorial for getting a PocketCHIP upgraded to the newest Debian version and getting it all set up how I like it. This is mostly a guide for me because I always end up messing something up and reflashing and want to keep notes on what to do, but if you're a lucky duck that has a PocketCHIP of your own, then feel free to follow this guide. If you don't have a PocketCHIP, then why are you still reading? Although, I recommend you go get one, they're amazing :).

Right off the bat, if you know what you're doing then just check out my forked repos that have a bunch of useful fixes and patches:

⇒ NextThingCo's CHIP-tools for flashing CHIPs

⇒ AllGray's PocketDesk

To give credit where credit is due, there are a lot of guides, and mine is mostly an amalgamation of the other guides, as all the ones I found had at least one missing piece to them. I referenced:

⇒ this gist

⇒ this repo

⇒ jfpossibilities' instructions

flashing stock image

First we'll flash the stock image, both to get back to the known working defaults and to make sure the kernel is the most up-to-date one that NextThingCo made. Since it's a custom kernel it's not easy to update it, so it's best to keep it on the most updated one available.

First, install fastboot (android-tools usually provides it), sunxi-tools, and uboot-tools from your repos.

Remove the CHIP from the PocketCHIP and connect the FEL pin to ground using a paperclip or jumper or whatver. Connect it via MicroUSB to your computer, then run these commands:

Replace the `-p` flag (PocketCHIP image) in the final command with `-s` for headless server, `-g` for regular CHIP desktop, and `-b` for buildroot. Also you can add a `-n` flag for a “no limit” image that doesn't have power limits.

Now the PocketCHIP is freshly flashed with the latest and greatest image. Ready your typing thumbs, because we're going to be doing a bit of typing on the PocketCHIP itself to get SSH working.

initial setup

Plug the CHIP back into the PocketCHIP if you haven't already, and boot it up. Once it boots, connect to Wi-Fi (using the GUI or `nmcli`, your choice). Then open terminal and edit `/etc/apt/sources.list` with `sudoedit` (the password is `chip`).

Replace all instances of `` and `` with ``. Also replace `` with ``. Comment out the `jessie-backports` lines!

The final sources.list should look like:

Edit `/etc/apt/preferences` and again replace `` with ``. It should look like:

Now run:

If you're nagged about unauthenticated packages, just hit yes, it's because the GPG key for the jessie repos expired.


and on your desktop run (you can also copy your ssh key over first):

doing more setup

Most of this setup is getting everything PocketCHIP specific installed and upgraded now since we have to remove the NextThingCo repos for the Stretch upgrade.

Setting up locales, which apparently aren't set up by default.

Changing the hostname:

Now we're going to install a few more utilities and get my dotfiles repo cloned. If you don't want my personal dotfiles (understandable) at least check out them out, in particular `.pocket-home/config.json` and `.bashrc`, as they have a few tweaks to fix breakages and such:

⇒ dotfiles for pocketchip

Now we'll update sunvox to the newest version (currently 1.9.6c). First, download the newest working version of sunvox:

⇒ sunvox 1.9.4c

You can then `rsync` or `scp` (or flash drive) that over to the PocketCHIP.

Updating PICO-8. You can replace the zip file being downloaded with the newest version available, check here:

⇒ zep keeps this post edited, so it's still tracks the newest version of PICO-8 despite NextThingCo being insolvent for so long.

Finally, we're going to install PocketDesk. PocketDesk is an awesome patch that includes O-Marshmallow's awesome Pocket Home fork that lets you add icons, set wallpapers, and is all around what NextThingCo's original Pocket Home should've been. PocketDesk also includes a regular XFCE desktop, so you can switch between Pocket Home and a regular desktop whenever you want. You can also add any other DE, I like to use i3.

I have my own custom patches, as the original PocketDesk relies on NextThingCo servers and it's all around just broken, so make sure to use my version as it actually works.

If you want to use i3 like previously mentioned, follow this guide now (skip the installing PocketDesk part!):

⇒ An updated guide for installing i3 window manager on pocket C.H.I.P. on Reddit.

At this point, most people should be all set, reboot and you're all good! Now I'd recommend getting some fun utilities and stuff installed.

A few more touchups I like to do:

⇒ install a better terminal without the massive bar.

⇒ If you do the above, then I recommend using tmux's clipboard to copy and paste

⇒ Set up some games and emulators compatible with the PocketCHIP

⇒ amfora works beautifully, and there's something very charming about browing Gemini on the PocketCHIP

⇒ set up the phase synthesizer, written specifically for the PocketCHIP

A few things to try out:

upgrading to stretch

If you can live with being on Debian Jessie and don't need anything special from Buster specifically, then I recommend stopping here. Upgrading is really finicky and requires a lot of manual intervention to even succeed at all. It also breaks a lot and makes the system very fragile, notably SunVox seems irrevocably broken and I can't figure out how to fix it.

Still continuing? Ok! I recommend doing the following in a tmux window. Maybe it's something with my network, but when upgrading to stretch it /will/ restart ssh, kicking you out, and if you're doing it in a raw shell that will be terminated, then it /will/ corrupt your install. Fixable, but a PITA so I'd recommend avoiding it.

Firstly, edit `/etc/apt/sources.list`, and delete the `jessie-backports` and `` lines. Then replace `jessie` with `stretch`. Also replace `` with ``. The final file should look like this:

Now we're actually upgrading.

During the upgrade, you can replace `/etc/systemd/journald.conf`. You can also replace `/etc/securetty`. Overwrite `/etc/ssh/sshd_config`, but make sure re-run the above sed commands after the upgrade is finished. Absolutely do not overwrite `/etc/lightdm/lightdm.conf`, or it will not successfully start X after a reboot. Replace `/etc/init.d/unattended-upgrades`.

Now we fix mac address randomization, which the CHIP Wi-Fi card doesn't support. Update `/etc/NetworkManager/NetworkManager.conf` to look like this (all you need to do is add the [connection] and [device] blocks):

Add the following to the end of `/etc/X11/xorg.conf`:

Replace `~/.config/awesome/rc.lua` with this:

Reboot, and the CHIP should be upgraded!

upgrading to buster

Upgrading to Buster is pretty much the same, but with less fiddling with configs.

Edit `/etc/apt/sources.list`, commenting out all but the first line:

We also have to clean up the old o-mashmallow repo:

Now just `sudo apt update && sudo apt full-upgrade`. Make sure to select “Don't touch keymap.” Don't replace `/etc/security/limits.conf`, `/etc/lightdm/lightdm.conf`, nor `/etc/plymouth/plymouthd.conf`.

Now remove both of the "device" sections of `/etc/X11/xorg.conf`, and add a new one. The full file should look like:

A few more touches:

After the update's done, then reboot. Oh yeah, the tmux version is now new enough so you can run <C-s I> to install the tmux themepack and get a better theme (if you're using my dotfiles).

EDIT: A PSA: do not do `sudo apt autoremove` after upgrading! It will break Pocket Home and you will have to reflash to fix it! You can run the following command to “mark” the packages to not be uninstalled:

And there you go! If you were successful, then you got a fancy dancy PocketCHIP with lots of extra features and running the newest Debian! Now get to hackin', you've spent valuable time on this when you could've been doing cool things!

⇒ ↩ go back to index

⇒ like this post!

⇒ add a comment!

⇒ view likes and comments

⇒ contact:

⇒ backlinks

-- © 2021 nytpu - CC-BY-SA-4.0

Proxied content from gemini://

Gemini request details:

Original URL
Status code
text/gemini; lang=en
Proxied by
nytpu's fork of kineto

Be advised that no attempt was made to verify the remote SSL certificate.