-- Leo's gemini proxy

-- Connecting to nytpu.com:1965...

-- Connected

-- Sending request

-- Meta line: 20 text/gemini;lang=en-US

↩ go back to index


a comprehensive guide to setting up a pocketchip

april 15, 2021


NOTE: this guide was last updated… around June 2021. While the majority of it is hopefully still useful, I would expect some large swaths to be out-of-date and not functional any more (particularly going from Stretch→Buster or from Buster to some even newer version). Feel free to follow the guide still, but it's currently in a state where you'll most likely have to figure some stuff out yourself.


I'd love to update it at some point, but I've been really busy lately and have a lot of other gadgets that are a lot less finicky than the PocketCHIP so I can't make any promises about when that may happen.


Also note that the post is licensed under the CC BY 4.0, so you're free to take stuff from my post and write your own version with changes if you'd like—as long as you credit me.



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:

$ git clone https://git.nytpu.com/forks/CHIP-tools
$ cd CHIP-tools
$ FEL='sudo sunxi-fel' FASTBOOT='sudo fastboot' SNIB=false ./chip-update-firmware.sh -p

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 `ftp.us.debian.org` and `http.debian.org` with `deb.debian.org`. Also replace `opensource.nextthing.co` with `chip.jfpossibilities.com`. Comment out the `jessie-backports` lines!


The final sources.list should look like:

deb http://deb.debian.org/debian/ jessie main contrib non-free
deb-src http://deb.debian.org/debian/ jessie main contrib non-free

deb http://security.debian.org/ jessie/updates main contrib non-free
deb-src http://security.debian.org/ jessie/updates main contrib non-free

#deb http://deb.debian.org/debian jessie-backports main contrib non-free
#deb-src http://deb.debian.org/debian jessie-backports main contrib non-free

deb http://chip.jfpossibilities.com/chip/debian/repo jessie main
deb http://chip.jfpossibilities.com/chip/debian/pocketchip jessie main

Edit `/etc/apt/preferences` and again replace `opensource.nextthing.co` with `chip.jfpossibilities.com`. It should look like:

Package: *
Pin: origin chip.jfpossibilities.com
Pin-Priority: 1050

Package: *
Pin: origin chip.jfpossibilities.com
Pin-Priority: 1050

Now run:

$ sudo apt update
$ sudo apt install openssh-server

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


Now:

$ sudo systemctl start ssh

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

$ ssh chip@chip.local


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.


$ sudo systemctl enable ssh

$ # if you're sshing from a tmux pane on your local computer, then run this
$ # or else it'll complain about a "broken" terminal
$ export TERM=xterm

$ sudo sed -i 's/.*PermitRootLogin.*/PermitRootLogin no/' /etc/ssh/sshd_config
$ # only run this if you have ssh keys set up
$ sudo sed -i 's/.*PasswordAuthentication.*/PasswordAuthentication no/' /etc/ssh/sshd_config
$ sudo systemctl restart ssh

$ # lock the root account from direct login
$ sudo passwd -l root
$ # change the CHIP's password
$ passwd

$ # make sure to confirm upgrading unverified packages
$ sudo apt update && sudo apt full-upgrade -y --force-yes
$ # the apt version is too old to use apt autoremove so we use apt-get
$ sudo apt-get autoremove --purge
$ sudo apt-get clean

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

$ sudo apt install locales
$ # only use "en_US" if you are in the USA
$ sudo locale-gen en_US en_US.UTF-8

$ # if in the USA, select "en_US" locales.
$ sudo dpkg-reconfigure locales
$ # select your timezone
$ sudo dpkg-reconfigure tzdata

Changing the hostname:

$ # change new-hostname to whatever you want
$ sudo sed -i 's/chip/new-hostname/g' /etc/hostname
$ sudo sed -i 's/chip/new-hostname/g' /etc/hosts

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

$ sudo apt install git vim tmux libx11-dev libxtst-dev
$ git clone https://github.com/aleh/pocketchip-batt.git
$ cd pocketchip-batt
$ sudo make install
$ cd
$ git clone --bare https://git.nytpu.com/personal/dotfiles ~/.dotfiles
$ alias config='/usr/bin/git --git-dir=$HOME/.dotfiles/ --work-tree=$HOME'
$ mkdir -p .config-backup && config checkout pocketchip 2>&1 | egrep "\s+\." | awk {'print $1'} | xargs -I{} mv {} .config-backup/{}
$ config checkout pocketchip
$ rm -r .config-backup/
$ config config --local status.showUntrackedFiles no

$ echo 'export SDL_GAMECONTROLLERCONFIG="030000001008000001e5000010010000,usb gamepad,platform:Linux,a:b2,b:b1,x:b3,y:b0,back:b8,start:b9,leftshoulder:b4,rightshoulder:b6,dpup:-a1,dpdown:+a1,dpleft:-a0,dpright:+a0,"' | sudo tee /etc/environment

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.

$ cd /path/to/sunvox-zip
$ unzip sunvox-1.9.4c.zip
$ sudo cp sunvox/sunvox/linux_arm_armhf_raspberry_pi/sunvox_lofi /usr/bin/
$ mkdir ~/.config/SunVox
$ wget -O ~/.config/SunVox/sunvox_config.ini https://raw.githubusercontent.com/mackemint/PocketCHIP-buster-update/main/assets/sunvox_config.ini

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.

$ cd /tmp/
$ wget www.lexaloffle.com/dl/chip/pico-8_0.2.2c_chip.zip
$ sudo unzip -o pico-8_0.2.2c_chip.zip -d /usr/lib
$ # it breaks after the stretch upgrade so we need to add this library
$ sudo wget -O /usr/lib/pico-8/libcurl.so.3 https://raw.githubusercontent.com/mackemint/PocketCHIP-buster-update/main/assets/libcurl.so.3

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.

$ cd
$ git clone https://git.nytpu.com/forks/PocketDesk
$ sudo ./PocketDesk/PocketDESK.sh

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:

Use ncmcpp as a remote to control MPD on another CHIP (or a Raspberry Pi) hooked up to your stereo system.

Get a portable USB or 3.5mm speaker and use CMUS to play music (CMUS is pretty much the only audio player that works reliably)



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 `chip.jfpossibilities.com` lines. Then replace `jessie` with `stretch`. Also replace `deb.debian.org` with `ftp.us.debian.org`. The final file should look like this:

deb http://ftp.us.debian.org/debian/ stretch main contrib non-free
deb-src http://ftp.us.debian.org/debian/ stretch main contrib non-free

deb http://security.debian.org/ stretch/updates main contrib non-free
deb-src http://security.debian.org/ stretch/updates main contrib non-fre

Now we're actually upgrading.

$ sudo apt update && sudo apt full-upgrade

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):

[main]
plugins=ifupdown,keyfile

[connection]
wifi.mac-address-randomization=1

[device]
wifi.scan-rand-mac-address=no

[ifupdown]
managed=false

[keyfile]
unmanaged-devices=interface-name:wlan1

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

Section "Device"
	Identifier	"Card0"
	Driver		"modesetting"
EndSection

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

wget -O ~/.config/awesome/rc.lua https://raw.githubusercontent.com/mackemint/PocketCHIP-buster-update/main/assets/rc.lua

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:

deb http://ftp.us.debian.org/debian/ buster main contrib non-free
#deb-src http://ftp.us.debian.org/debian/ buster main contrib non-free

#deb http://security.debian.org/ buster/updates main contrib non-free
#deb-src http://security.debian.org/ buster/updates main contrib non-free

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

$ sudo rm /etc/apt/sources.list.d/marshmallow-pocket-chip-home.list

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:

Section "Files"
        ModulePath "/usr/lib/arm-linux-gnueabihf/xorg/modules/"
        ModulePath "/usr/lib/xorg/modules/"
EndSection

Section "Monitor"
	Identifier	"VGA"
	Option		"PreferredMode"	"1024x768_60.00"
EndSection

Section "Monitor"
	Identifier	"HDMI"
	Option		"PreferredMode"	"1280x720_60.00"
EndSection

Section "Monitor"
	Identifier	"Composite"
	Option		"PreferredMode"	"NTSC10"
EndSection

Section "Screen"
	Identifier	"Screen0"
	Device		"Card0"
EndSection

Section "Device"
	Identifier	"Card0"
	Driver		"fbdev"
EndSection

A few more touches:

$ sudo systemctl disable wpa_supplicant

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:

$ sudo apt-mark manual $(apt-get autoremove --dry-run | sed -ne 's/Remv \(.*\) \[.*/\1/gp')

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: alex@nytpu.com


backlinks


-- Copyright © 2021 nytpu - CC BY 4.0

-- Response ended

-- Page fetched on Fri Mar 29 05:28:19 2024