Welcome to PocketC.H.I.P.

Hey! Thanks for checking out PocketC.H.I.P.!

PocketC.H.I.P. is a game console, a portable synthesizer, and a Linux field terminal. With a bit of effort, it
can become a whole lot more see PockulusC.H.I.P., PocketC.H.I.P. as a VR headset here.
The point is, PocketC.H.I.P. can be what you want it to be and were excited to see what you will do with
your PocketC.H.I.P..
These are the Docs, which are intended to help you get started with PocketC.H.I.P.. The Docs will
introduce you to the software that comes pre-installed on PocketC.H.I.P., explain how to use the system,
and hopefully plant some ideas about how you can do even more with your PocketC.H.I.P..
The Docs will not teach you how to code (though it will give tips), how to program a game (though it will
explain the tools), how to make music (though it will describe options), or how to build onto PocketC.H.I.P.
(though it will encourage it).
Have fun!

Quick Start

This section explains how to turn on PocketC.H.I.P., setup WiFi, and charge your device.

Turn on PocketC.H.I.P. by pressing down the Home/Power button at the bottom, middle of the keyboard,
for about two seconds.
PocketC.H.I.P. will take a moment to fully load, but while it does you will see the C.H.I.P. logo and then a
PocketC.H.I.P. splash screen.
Once PocketC.H.I.P. is ready you will see a series of slides showing the PocketC.H.I.P. basics. Use the right
arrow key or tap the right side of the screen to advance forward in the slideshow.
Once you have clicked through the basics, you will see a screen with six icons. This is the Home Screen.

Use a finger or stylus (or really anything thats solid and isnt sharp) to tap on the application you want
to use. Press gently enough to make contact with the screen. Theres no need to apply a lot of force. A
gentle touch will do.

While using an application, press the Home/Power button to return to the Home Screen.

WiFi Setup
From the Home Screen, tap the settings icon in the bottom right corner to access the Settings Screen.
Press the button to the right of the WiFi switch to open a menu of all the networks in range. Scroll through
the list and select your network by pressing the arrows above and below the network names. To refresh
the network list, just exit the list and enter again.
When prompted, enter the network password in the text field, then touch the [Connect] button. It may
take a few seconds to connect.
Charging

Plug in PocketC.H.I.P. to a 5-volt 1.5A power supply with a USB-micro cable to charge the 3.7V battery.
Because it is C.H.I.P.s on-board circuitry that manages the charging of PocketC.H.I.P.s battery, the C.H.I.P.
must remain attached to PocketC.H.I.P. for battery charging.
PocketC.H.I.P. is compatible with most cell phone chargers that use a USB-micro cable.
Troubleshooting
If PocketC.H.I.P. becomes unresponsive, hold down the Home/Power button for eight seconds. This will
cut power to PocketC.H.I.P., and immediately shut it down. Only use this shutdown method if no other
shutdown methods work.
PocketC.H.I.P. at a Glance

Touchscreen

PocketC.H.I.P. features a 4.3" display made up of 480 x 272 pixels. The display is resistive touch and
responds to tapping and sliding. This means you can use a finger or almost any object that isnt sharp
you dont want to scratch your screen.

Tap once to open apps, press buttons, and close windows.

Press and slide to scroll, adjust sliders, and resize windows.

Keyboard

PocketC.H.I.P. has a full QWERTY keyboard with comfortably located arrow keys for gaming.
Each button is labeled with pink text, which identifies the default button behavior. Some buttons have
two rows of pink text stacked atop each other. The bottom text is the primary behavior of the key. The
top text identifies the buttons secondary behavior, which is accessible by holding down SHIFT and
pressing the button.
For example: Holding SHIFT and pressing 1 types !
Some buttons are labeled to the top-left with white text on a pink background. These keys are mostly
located on the right side of PocketC.H.I.P.s keyboard and are for characters like function keys
(F1, F2, F11) and lesser used punctuation marks ({}<>|;). To type these specialized characters, hold the
FN key and press the desired button.

For example: Holding FN and pressing J types >

Removable enclosure

PocketC.H.I.P. is extremely hackable and we encourage you to modify the hardware. It is easy to take
apart, since there are no screws used in the assembly.

If you want to fully disassemble PocketC.H.I.P., first (carefully) remove C.H.I.P. from the back of
PocketC.H.I.P.. Then flip PocketC.H.I.P. around and remove the frame (technically known as a bezel)
around the perimeter of the screen. Remove the back case of PocketC.H.I.P. by pressing the tabs above

the screen and on either side of the Home/Power button.

While the case is open, check out the secret prototyping area and GPIO solder pads inside the
enclosure!

GPIO Access

Along the top edge of PocketC.H.I.P. are input and output pins from C.H.I.P.. These are great for attaching
and controlling sensors, motors, and LEDs.
See the C.H.I.P. documentation to learn how to use them here.

Pencil stand

Give your hands a break! You can prop PocketC.H.I.P. up on a table with a pencil or pen. Pencils go in
the right-hand-side pencil hole, and pens in the left hole. You only need one.
Power and Charging

Battery Life

Your PocketC.H.I.P. uses a 3.7-volt LiPo battery, that should last for about five hours of use. Increase
battery life by dimming the screen brightness and turning off WiFi.
The top left corner of the screen shows your battery level, and PocketC.H.I.P. will warn you when the
battery charge is getting too low for operation.

Charge PocketC.H.I.P.

Plug PocketC.H.I.P. into a 5-volt 1.5A power supply with a USB-micro cable to charge the 3.7V battery.
Because its C.H.I.P.s on-board circuitry that manages the charging of PocketC.H.I.P.s battery, the C.H.I.P.
must remain attached to PocketC.H.I.P. for battery charging.
PocketC.H.I.P. is compatible with with most cell phone chargers that use a USB-micro cable.

Sleep and Shutdown

Sleep

Sleep is a low-power state that saves battery, and also saves you time, since its faster for PocketC.H.I.P.
to wake from sleep than to boot from a powered-off state.
To enter sleep mode, tap the power icon in the bottom left corner of the home screen and select
Sleep. from the menu.
PocketC.H.I.P. is designed to turn off the screen and backlight after a few minutes without any user
interaction.
To wake from either sleep state, simply touch the screen or press a key.

Shutdown

Shutdown PocketC.H.I.P. by pressing the power icon in the bottom left corner of the home screen
and tapping shutdown.
If for some reason, PocketC.H.I.P. becomes unresponsive, you can also shut down PocketC.H.I.P.
by holding down the HOME/Power button for eight seconds. This cuts battery power to PocketC.H.I.P.
and shuts it off. Only use this method if all other methods do not work.

Using PocketC.H.I.P.
Keyboard Shortcuts

PocketC.H.I.P. has a few keyboard shortcuts that will make it faster for you to do common tasks on the
device.
Hold CTRL and press TAB to change the current window (also known as window focus).
Hold CTRL and press q to quit an application.

Flashing

To flash your PocketC.H.I.P. to the latest factory image, tap the power button and then press the flash
software button. Then use a USB cable to connect PocketC.H.I.P. to a computer and follow the directions
on flashing.

WARNING: This will permanently delete all the data on PocketC.H.I.P., so backup anything you want to
keep!

Applications

Your PocketC.H.I.P. comes with six applications on the Home Screen.

PICO-8 - play, create, share 8-bit games
SUNVOX - listen or compose electronic music
Terminal - use a Linux shell to run commands
Write - a lightweight text editor
File Browser - a graphical file browser
Help - the same documentation youre reading here, built into to PocketC.H.I.P.

PICO-8

Play PICO-8

Play games, change games, and make games with PICO-8! With a couple keystrokes, you can join the
PICO-8 community and modify their games, or even make your own!
For more resources to learn PICO-8, search YouTube for PICO-8 videos and check out the PICO-8
Fanzine link.

PICO-8 starts in splore mode, which lets you select which game to load.
If PocketC.H.I.P. is connected to WiFi, PICO-8 community made games can be downloaded and played
here. Navigate the menus using the arrow keys, and press 0 to select a game.
Favourites: Save games to this list by pressing ESC while in the game and selecting Favourite.
Games on this list are playable even when youre not connected to WiFi.
New: Lists the newest additions to the PICO-8 community.
Featured: Lists the top-rated games from the PICO-8 community.
Work In Progress: Lists recent releases of unfinished games submitted by members of the
community.
Collaboration: Lists user-submitted resources, remixes, and other useful things for others to use
in their creations.
Search: Performs a text search of PICO-8s game library
/: Lets you navigate the PICO-8 folders on your PocketC.H.I.P.
While in the splore mode, press ESC and select EXIT TO CONSOLE to start PICO-8s command line
interface. PICO-8s command line commands are listed below:
Help lists the available commands
Splore return to cart explorer
dir list the contents of the current directory
cd [directory name] change to the desired directory
cd .. go up a directory
cd / change back to top directory (on PICO-8s virtual drive)
keyconfig customize the keys used by all games
mkdir make a new directory
folder open the current directory in the host operating systems file browser
load [name of game] load a game from the current directory (this is like putting a cartridge into
the console)
run plays the cart that is currently loaded
save [filename] saves the currently loaded cart with the given name (this is used when youve
made changes to the games code, graphics, or music)

Make Games (with PICO-8)

Gamers, get ready to become game-makers. In addition to playing the communitys games, PICO-8 allows
you to modify existing games, or create games of your own using the code, graphics, and sound editors.
See the image above to learn which icon stands for which editing mode, and keep reading for an
explanation of each mode.

Code Editor

Access the code editor from the command line by pressing ESC. If you are in the middle of a game,
press ESC and select EDIT THIS CART to edit the games code. Some other helpful shortcuts are:
Hold SHIFT to select multiple characters or lines (or tap-and-drag)
CTRL-X, CTRL-C, CTRL-V to cut, copy, or paste a selection
CTRL-Z, CTRL-Y to undo, redo
CTRL-F, CTRL-G to search for text, repeat search
ALT-UP, ALT-DOWN to navigate to the previous, next function
The code editor is not the only editor in PICO-8. Access the other editors by tapping on the icons in the
upper right-hand corner of the editor.

Sprite Editor

Use the sprite editor to create the artwork that make up tiles, characters, or other graphical elements of
the game. The navigator at the bottom of the sprite editor screen shows an 8x8 pixel box that is displayed
in the sprite sheet window, but it is possible to use freeform tools (pan, select) to edit larger areas.
Use the following tools to edit sprites:

Draw Tool

Click on the desired color and then click in the editor window to apply the color to each pixel.
Hold the CTRL button and click on a pixel to replace all of the same-colored pixels in the window
with the selected color.
Stamp Tool * Select an area of the sprite sheet that you want to copy using the select tool. * Select the
stamp tool and click the location where you want the copied pixels to be pasted. * Hold CTRL to stamp
with transparency (this pastes all of the non-black pixels in the selection).

Select Tool * Use the shortcut: SHIFT or S to save time. * Click and drag with the select tool to highlight
an area of the sprite sheet. * Enter or click to select none.
Pan Tool * Use the shortcut: Spacebar. * Click and drag to move around the sprite sheet.
Fill Tool * Fill an area with the selected color. * If you have selected an area of the sprite sheet, the fill
will be limited to the selected area. * If no selection is active, the fill will be limited to the area in the
editor window.

Map Editor

The tools for the map editor work similarly to those in the sprite editor. However, rather than choosing
colors and drawing directly on the map sheet, select a sprite and use the draw or fill tool to place sprites
into the map sheet.

Sound Effects Editor

PICO-8s sound editor has two view modes: graph view and tracker view. Switch between modes by
tapping on the graph and tracker buttons in the upper-left corner of the sound editor.
In both views, the number in the top left, under the view selector is the sound effect number. PICO-8 can
handle 64 different effects.
Change the speed of the sound by clicking on the number in the box labelled SPD. Tap and drag to
change the value (dragging left decreases, dragging right increases). The SPD value describes the
duration of each note, so the higher the value, the slower the sound will play.
The LOOP values define the start and end points of a section of the sound effect that repeats. These can
be changed by tapping and dragging like the SPD values.
Select from the eight available instruments by clicking on the gray waveform boxes below the SPD and
LOOP fields.
Press the spacebar to play/stop the current sound effect.

Graph mode

In graph mode, choose an instrument and then click-and-drag left-to-right to draw the sound across the
pitch window. Draw higher in the window to create a sound with a higher pitch. Adjust the volume of
each note, with the sliders in the volume window at the bottom of the graph mode screen.

Tracker mode

In the tracker mode, each line of six dots represents a note. Each dot represents an aspect of the notes.
In left-to-right order they are: frequency, octave, instrument, volume, and effect.
Frequency * Denoted by the letter of the musical pitch. * Input the pitches, using
the q2w3er5t6y7ui keys like a piano. * Q is a C note, W is a D note. * The number keys are
the sharps and flats (like the black keys on a piano).
Octave
For each note, choose octave 1, 2, 3, or 4 in the OCT field at the top, or type the corresponding
number: 1 is the lowest octave and 4 is the highest.
Instrument
Choose one of the instruments in the gray waveform boxes or type the corresponding number (0 through
7).
Volume
Choose volume level in the VOL field or type the corresponding number (0 through 7).
Effect
Choose an effect from the boxes under the instruments or type the corresponding number (0 through
7). The 8 effects are:
0 - none
1 - slide
2 - vibrato
3 - drop

4 - fade in
5 - fade out
6 - fast arpeggio
7 - slow arpeggio

Music Editor

The music editor allows up to four effects at a time for your games soundtrack. Click on the boxes above
each column to activate the track and choose which effects will be included in each song pattern.
Patterns can be set to move to the next pattern, repeat the current pattern, or stop when finished with
the arrow and stop icons on the upper right.
PICO-8 can hold up to 64 song patterns.

SunVox

The SunVox tracker is a fully featured music production studio. Its lightweight, sounds great, and is
designed to work with a stylus on a single, small screen. As a result, its a perfect fit for for making music
and playing with sound on PocketC.H.I.P..
To get started launch SunVox, put on some headphones, press SHIFT-space to start playback, and dive
into a complete world of electronic sound. While SunVox is pretty much limitless in its configuration,
C.H.I.P. has limited CPU and memory resources. Keep in mind if you add a lot of filters, reverbs, and

delays, SunVox might stutter on playback. Its also a good idea to quit any other processes running on
C.H.I.P. using ALT-tab to go to other applications and windows and CTL-q to quit them.

Interface Overview

Heres a quick overview of what you see when you launch SunVox, and what the different parts of the
interface do. Visit the SunVox page for more information, including complete keyboard mappings. There
are also lots of introductory SunVox videos on YouTube, just search for SunVox intro videos.

Keyboard Shortcuts
Weve modified some of the default keyboard shortcuts to work better with the PocketC.H.I.P. keyboard.
Heres whats different:
Command

Keys

stop

Shift-v

play from beginning

Shift-b

play pattern

Shift-n

record

Shift-r

octaves 0-8

Shift-[0-8]

play

Shift-space

Pattern Editor

The Pattern Editor is like a page of sheet music. Instead of staffs, measures, clefs, notes, and
articulations, it has 32 rows and several columns that represent pitch, timing, and even how a pitch is
played (soft, hard, bright, etc).
Patterns represent chunks of a song that will later be dropped into the timeline of the song and arranged
with other patterns.
Note: All the numbers are in hexadecimal, so instead of the number 46, youll see 2E. These notes can
play drums, lead instruments that sound like a guitar (maybe), bass notes, or even atonal washes of
sound.
In the pattern editor you can add notes and note modifiers to compose patterns.
Spacebar toggles edit mode on and off, use the arrow keys to select rows, use letters to enter notes,
use numbers to enter (hexadecimal) values for velocity, module, and control values.

Touch Keyboard

The Touch Keyboard is in the middle of the screen. Tap on it and youll hear sound.
If youre editing a Pattern, you can use this to enter notes. Just tap in the first column in the editor where
you want a note to play and then tap the note on the touch keyboard. The editor will record the note
you play and then move to the next line so you can tap the next note you want to play.
You can also use PocketC.H.I.P.s QWERTY keyboard to enter notes. To enter notes on the QWERTY
keyboard, use it similar to a piano. For example, Z is a c note and X is a d note.
From left to right across the bottom row of the keyboard, the notes ascend.
For sharp and flat notes, use the row above. For example, S is a c-sharp because it is above and between
the Z and X keys (similar to where the c-sharp key is on a piano, above and between the c and d notes).

Modules (synths and effects)

The Module Editor is located below the Touch Keyboard on its right. This includes the different
instruments, synthesizers, or effects you can use to change the sounds that you put into the patterns
above. You can add new modules, delete current modules or rearrange modules to fit your needs.
With any sounds you make, you need something to generate the sound first. Double-tap on the
background in the module editor and then choose a generator from the list. Once youve picked a
generator need to connect it to the output. Do this by holding SHIFT and then tapping and dragging
from the generator to the OUT box
You can also add effects to the sounds made by the generator. Double-tap in the background again and
choose an effect from the list. Now change the route the sound goes through by tapping and dragging
from the generator to the effect. Then tap-and-drag from the effect to the output box.
You can have multiple instruments and different paths for the sound in the editor at one time. When
editing patterns, tap on the generator you want to use and then edit the pattern. Changes to the pattern
will be made using the currently selected generator.
To delete an effect or generator, double-tap the module and tap the delete button.

Parameter Controls

Parameter Controls for the currently selected module are in the bottom left corner of the interface.
Violin players can bend a string and change how they bow, vocalists can shape their mouths and vocal
chords, electric guitarists can stomp on pedals and hit the whammy bar, synthesizer nerds can turn knobs
and sliders. In SunVox, you can modify how a synth or effect sounds using the horizontal sliders in the
Parameter Controls.
Tap on a module and use the Parameter Controls on the left to modify the sound. Play the (piano or
PocketC.H.I.P.) keyboard to hear the sound of a synth module. Use CTRL-arrows to jump to different
modules. SHIFT-drag to connect and disconnect modules.

Resize Handles
Tap-and-drag in these areas to resize the panels.
Transport
Record new pattern into timeline, play from beginning, play, play pattern, stop.
Octave Up/Down
Change the octave of the touch keyboard.
Edit Pattern Indicator
When locked, you cant make changes to the pattern.
Spacebar unlocks the world of pattern editing!
Volume
Tap-and-drag the volume control to change output volume.
Menu Items
Sunvox has one simple menu. Tap here to save and load projects, set preferences like MIDI controllers,
and the ultra-fun Touch Theremin feature! Select it in the Menu, and start making some noise!
Switch To Timeline
The Timeline allows you to place, move, and rearrange patterns to create a song. On PocketC.H.I.P.s
small screen, youll need to use the Switch To Timeline button.
In Timeline, you can also freely record notes while you play them with the Record button, or you can
clone patterns to repeat them. Move the patterns blocks around to create your composition. When
finished, you can render a finished stereo file and distribute it as you want!

MIDI
You can attach a MIDI keyboard or controller to PocketC.H.I.P.s USB port and have even more fun with
SunVox. Not only can you play notes from a keyboard, but you can use MIDI knobs and sliders to control
parameters of different synths. Tweak on!

Terminal

Many may find the Terminal archaic or intimidating, its a place to type commands directly to the
computer for execution and evaluation by the operating system. There are no icons, just text.
Use the terminal to dive into the operating systems guts, quickly move files around, play with
PocketC.H.I.P.s GPIO, or extend its capabilities. Theres a primer on using Terminal in the C.H.I.P.
documentationhere if you want to learn more.
Terminal Top Buttons

The Terminal has a few small buttons at top. From left to right, they are:
New Tab
Close Tab
Zoom in (increase font size)
Zoom out (decrease font size)
Copy selected text
Previous tab
Next tab
Flip toolbar
Paste - Paste selected text (can be from another tab, not in another application)

Write

Write is a minimalist text editor thats well suited for basic text entry tasks. If youre looking to code with
Write, youll be pleased to learn that it supports line numbering and auto indentation, just look under
the Option menu.

File Browser

The File Browser provides a visual representation of the files on your PocketC.H.I.P. using icons. Drag,
drop, and double-click your way through this application for full control over every file on your device.

Help

You are reading it right now. No kidding! This document is available online and locally on PocketC.H.I.P.,
which means anywhere PocketC.H.I.P. goes, help will be right there with it.

Settings

Use the PocketC.H.I.P. settings to change WiFi, screen brightness, or volume levels.
To access the PocketC.H.I.P. settings, tap on the sprocket icon on the Home Screen.

WiFi & Bluetooth

From the Settings Screen, tap the switch next to the WiFi icon to turn WiFi on.
Press the button to the right of the WiFi switch to open a menu of all the networks in range. Scroll through
the list by tapping the onscreen arrows, and select your network by tapping on its name.
When prompted, enter the network password in the text field, then touch the [Connect] button. It may
take a few seconds to connect.
Currently only WiFi is configurable from the PocketC.H.I.P graphical interface. If you want to configure
Bluetooth, consult the C.H.I.P. documentation page here.
Screen Brightness

Tap the brightness slider on the left to decrease brightness or tap the right to increase. Lowering the
brightness is an easy way to increase battery life.
Volume

Adjust the volume slider by tapping on the left to decrease volume or on the right to increase it. Of
course, youll need to have headphones or speakers attached to PocketC.H.I.P. to hear anything.
Security
Just like you have a username and password for your e-mail account, PocketC.H.I.P. has a username and
password for its operating system. The main user account on PocketC.H.I.P. is chip, and the password is
also chip. Both username and password are case sensitive.
At startup, PocketC.H.I.P. automatically logs you in as chip. This means theres no need to manually
enter chips password chip. There are times when youll need to use the chip password, but you can get
most things done without it.
PocketC.H.I.P. also has a second username called root, which should only be used for administrative
tasks such as installing and removing software. The root password is also chip, and both are also case
sensitive.

Never login directly as root, since it is extremely easy to delete critical files in the system. Instead, use
the system administration command sudo, which provides a bit of protection from accidentally breaking
your system.
For more information on using sudo, see the C.H.I.P. docs here.

Username Password
chip

chip

root

chip

Changing Your Password

You should change your password for both the chip and root account to something other than chip.
Open the terminal application from the PocketC.H.I.P. Home Screen, type the following command:
passwd
and press ENTER.
Youll be prompted for your current password, which is chip and then required to enter in your new
password twice. Thats it!

Using Accessories

Just because PocketC.H.I.P. is complete with a keyboard and screen doesnt mean you cant add speakers,
storage, or wireless gadgets to make it even more fun.
PocketC.H.I.P. input and output ports are all handled by C.H.I.P.. Chances are good that if an accessory
works with C.H.I.P., it will work with PocketC.H.I.P.!

Audio

PocketC.H.I.P. does not have a built-in speaker, but that doesnt mean it cant output sound.
To listen to audio from PocketC.H.I.P., attach any wired headphones or speakers to the audio jack at the
top of the device. This jack is known as a TRRS jack and can accommodate headphones. With a simple
modification to the C.H.I.P., the TRRS jack can accomodate headphones that have built-in microphones.

Micro-USB

Use the micro-USB port for charging PocketC.H.I.P. with a 5-volt, 1-amp power supply. Most cell phone

chargers that use a USB-micro cable will work with PocketC.H.I.P.

Standard USB

Use the standard USB port for attaching

controller, sound card, hard drive, or more.

USB

accessories,

like

a keyboard, mouse, MIDI

USB devices take power to operate. If they are not independently powered, they will reduce the battery
life of PocketC.H.I.P. or cause operation to become sporadic.

Glossary

apt-get: the package manager used for installing, upgrading, and removing application in Debian Linux.
Bezel: section of the case that clips around the touchscreen.
Booting: the process of PocketC.H.I.P. powering on and loading Debian.
Command Line: the area in the Terminal where text is input for the Operating System to evaluate. Debian:
a version of the Linux Operating System that runs on PocketC.H.I.P..
Fantasy Console: a console game system that does not have dedicated, specific hardware to run its
software. For example, PICO-8.
Flashing: the process of overwriting the contents of NAND with an Operating System and Applications.

Linux: a computer Operating System that runs on all different types of hardware. Everything from bank
ATMs and cell phones to C.H.I.P. and PocketC.H.I.P.
NAND: a type of storage used on PocketC.H.I.P. for the OS, applications, and all your files.
Open Source Hardware: Open source hardware is hardware whose design is made publicly available so
that anyone can study, modify, distribute, make, and sell the design or hardware based on that design.
More info at the Open Source Hardware Association.
Open Source Software: Very briefly, Open Source Software is software where the source code for a
program is made freely available. But theres a lot more to this, as you can read at the Open Source
Initiative website.
QWERTY keyboard: is a layout of keys where the top rows first six keys spell qwerty.
SCP: a utility to transfer files to different computers.
Shell: see Terminal
SSH: (aka Secure Shell) is a utility used to login to remote computers running SSH service.
Stylus: a pointing device
Terminal: a program used to enter text commands for the Operating System to execute or interpret.
TRRS jack: a connector commonly used for audio or video equipment. TRRS stands for tip, ring, ring, and
sleeve and refers the the way the male connector is divided.

FAQ

Can I take C.H.I.P. out of PocketC.H.I.P. and use it? At this time, it will not work as expected without
reflashing. The C.H.I.P.s in PocketC.H.I.P. run a custom graphics software thats designed for the
touchscreen and PocketC.H.I.P. keyboard. C.H.I.P. may boot, but the resolution and input will not work
as expected.
Is it Legal to Modify PocketC.H.I.P.? Yes. PocketC.H.I.P. and C.H.I.P. are open source hardware. We
encourage you to modify PocketC.H.I.P. and be sure to share what youve done with our community!
Is PocketC.H.I.P. Open Source? Yes, and you can get the hardware files at our github repo.
Will my microUSB charger work with PocketC.H.I.P.? PocketC.H.I.P. is compatible with with most cell
phone chargers that use a USB-micro cable. PocketC.H.I.P. needs a power supply capable of outputting
5-volts with at least 1 amp.
Can I connect PocketC.H.I.P. to a second display? No. At this time PocketC.H.I.P. does not support

multiple displays.
Is it OK to eat PocketC.H.I.P.? No! Neither C.H.I.P. nor PocketC.H.I.P. should ever be eaten, even by
C.H.I.P.py Ruxpin.
Will my Bluetooth Device Work? Yes, so long as the device is supported under Debian Linux. However,
you will need to setup the bluetooth pairing using the terminal here. Our initial release of PocketC.H.I.P.
does not provide graphical bluetooth configuration.
Pinch-zooming isnt working, is my screen bad? Your screen is fine. The resistive touchscreen used in
PocketC.H.I.P. does not support pinch gestures.
How can I get PockulusC.H.I.P.? Good news! You already almost have one. All you need to do is 3D print
the file at here or find a friend to do it for you.
How can I contact Next Thing Co.? Send us an e-mail at [email protected].
License
U-Boot
PocketC.H.I.P. boots using U-Boot 2015.10 (GPLv2) with custom patches.
Source code is available at:
https://github.com/CHIP-u-boot
See below for the full text of the GPLv2.
Linux
PocketC.H.I.P. runs mainline Linux 4.3 (GPLv2) with custom patches.
Source code is available at:
https://github.com/CHIP-Linux
See below for the full text of the GPLv2.
PocketC.H.I.P. runs Debian 8 (Jessie)
Debian contains various open source software.
The license for a particular debian package is included in the package documentation in
/usr/share/doc/.
PocketC.H.I.P. Launcher
The PocketC.H.I.P. Launcher is Copyright 2016 Next Thing Co.
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
associated documentation files (the Software), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the
following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial
portions of the Software.
THE SOFTWARE IS PROVIDED AS IS, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE
OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

The PocketC.H.I.P. Launcher is built using JUCE

https://github.com/julianstorer/JUCE
Most JUCE modules are shared under the GNU Public Licence (GPLv2, v3, and the AGPLv3). This means
that the code can be freely copied and distributed, and costs nothing to use in other GPL applications.
One module (the juce_core module) is permissively licensed under the ISC.
PICO-8
PICO-8 v0.1.6 http://www.pico-8.com Copyright 2014-2016 Lexaloffle Games LLP
Author: Joseph White // [email protected]
PICO-8 is built with:
SDL2 http://www.libsdl.org
Lua 5.2 http://www.lua.org - see license below
GIFLIB http://giflib.sourceforge.net/
Copyright 19942015 Lua.org, PUC-Rio.
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
associated documentation files (the Software), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the
following conditions: The above copyright notice and this permission notice shall be included in all copies
or substantial portions of the Software.
THE SOFTWARE IS PROVIDED AS IS, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT
OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
OTHER DEALINGS IN THE SOFTWARE.
SunVox
SunVox modular synthesizer Copyright 2002 - 2016, Alexander Zolotov [email protected],
WarmPlace.ru SunDog engine (part of SunVox)
Copyright 2002 - 2016, Alexander Zolotov [email protected], WarmPlace.ru
Ogg Vorbis Tremor integer playback codec Copyright 2002, Xiph.org Foundation
GNU General Public License
GNU GENERAL PUBLIC LICENSE Version 2, June 1991
Copyright 1989, 1991 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
02110-1301 USA Everyone is permitted to copy and distribute verbatim copies of this license document,
but changing it is not allowed.
Preamble
The licenses for most software are designed to take away your freedom to share and change it. By
contrast, the GNU General Public License is intended to guarantee your freedom to share and change
free softwareto make sure the software is free for all its users. This General Public License applies to
most of the Free Software Foundations software and to any other program whose authors commit to
using it. (Some other Free Software Foundation software is covered by the GNU Lesser General Public

License instead.) You can apply it to your programs, too.

When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are
designed to make sure that you have the freedom to distribute copies of free software (and charge for
this service if you wish), that you receive source code or can get it if you want it, that you can change the
software or use pieces of it in new free programs; and that you know you can do these things.
To protect your rights, we need to make restrictions that forbid anyone to deny you these rights or to ask
you to surrender the rights. These restrictions translate to certain responsibilities for you if you distribute
copies of the software, or if you modify it.
For example, if you distribute copies of such a program, whether gratis or for a fee, you must give the
recipients all the rights that you have. You must make sure that they, too, receive or can get the source
code. And you must show them these terms so they know their rights.
We protect your rights with two steps: (1) copyright the software, and (2) offer you this license which
gives you legal permission to copy, distribute and/or modify the software.
Also, for each authors protection and ours, we want to make certain that everyone understands that
there is no warranty for this free software. If the software is modified by someone else and passed on,
we want its recipients to know that what they have is not the original, so that any problems introduced
by others will not reflect on the original authors reputations.
Finally, any free program is threatened constantly by software patents. We wish to avoid the danger that
redistributors of a free program will individually obtain patent licenses, in effect making the program
proprietary. To prevent this, we have made it clear that any patent must be licensed for everyones free
use or not licensed at all.
The precise terms and conditions for copying, distribution and modification follow.
GNU GENERAL PUBLIC LICENSE TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND
MODIFICATION
1. This License applies to any program or other work which contains a notice placed by the copyright
holder saying it may be distributed under the terms of this General Public License. The Program,
below, refers to any such program or work, and a work based on the Program means either the
Program or any derivative work under copyright law: that is to say, a work containing the Program
or a portion of it, either verbatim or with modifications and/or translated into another language.
(Hereinafter, translation is included without limitation in the term modification.) Each licensee
is addressed as you.
Activities other than copying, distribution and modification are not covered by this License; they are
outside its scope. The act of running the Program is not restricted, and the output from the Program is
covered only if its contents constitute a work based on the Program (independent of having been made
by running the Program). Whether that is true depends on what the Program does.
1. You may copy and distribute verbatim copies of the Programs source code as you receive it, in
any medium, provided that you conspicuously and appropriately publish on each copy an
appropriate copyright notice and disclaimer of warranty; keep intact all the notices that refer to
this License and to the absence of any warranty; and give any other recipients of the Program a
copy of this License along with the Program.
You may charge a fee for the physical act of transferring a copy, and you may at your option offer warranty

protection in exchange for a fee.

1. You may modify your copy or copies of the Program or any portion of it, thus forming a work
based on the Program, and copy and distribute such modifications or work under the terms of
Section 1 above, provided that you also meet all of these conditions:
a) You must cause the modified files to carry prominent notices stating that you changed the files and
the date of any change.
b) You must cause any work that you distribute or publish, that in whole or in part contains or is derived
from the Program or any part thereof, to be licensed as a whole at no charge to all third parties under
the terms of this License.
c) If the modified program normally reads commands interactively when run, you must cause it, when
started running for such interactive use in the most ordinary way, to print or display an announcement
including an appropriate copyright notice and a notice that there is no warranty (or else, saying that you
provide a warranty) and that users may redistribute the program under these conditions, and telling the
user how to view a copy of this License. (Exception: if the Program itself is interactive but does not
normally print such an announcement, your work based on the Program is not required to print an
announcement.)
These requirements apply to the modified work as a whole. If identifiable sections of that work are not
derived from the Program, and can be reasonably considered independent and separate works in
themselves, then this License, and its terms, do not apply to those sections when you distribute them as
separate works. But when you distribute the same sections as part of a whole which is a work based on
the Program, the distribution of the whole must be on the terms of this License, whose permissions for
other licensees extend to the entire whole, and thus to each and every part regardless of who wrote it.
Thus, it is not the intent of this section to claim rights or contest your rights to work written entirely by
you; rather, the intent is to exercise the right to control the distribution of derivative or collective works
based on the Program.
In addition, mere aggregation of another work not based on the Program with the Program (or with a
work based on the Program) on a volume of a storage or distribution medium does not bring the other
work under the scope of this License.
1. You may copy and distribute the Program (or a work based on it, under Section 2) in object code
or executable form under the terms of Sections 1 and 2 above provided that you also do one of
the following:
a) Accompany it with the complete corresponding machine-readable source code, which must be
distributed under the terms of Sections 1 and 2 above on a medium customarily used for software
interchange; or,
b) Accompany it with a written offer, valid for at least three years, to give any third party, for a charge no
more than your cost of physically performing source distribution, a complete machine-readable copy of
the corresponding source code, to be distributed under the terms of Sections 1 and 2 above on a medium
customarily used for software interchange; or,
c) Accompany it with the information you received as to the offer to distribute corresponding source
code. (This alternative is allowed only for noncommercial distribution and only if you received the
program in object code or executable form with such an offer, in accord with Subsection b above.)

The source code for a work means the preferred form of the work for making modifications to it. For an
executable work, complete source code means all the source code for all modules it contains, plus any
associated interface definition files, plus the scripts used to control compilation and installation of the
executable. However, as a special exception, the source code distributed need not include anything that
is normally distributed (in either source or binary form) with the major components (compiler, kernel,
and so on) of the operating system on which the executable runs, unless that component itself
accompanies the executable.
If distribution of executable or object code is made by offering access to copy from a designated place,
then offering equivalent access to copy the source code from the same place counts as distribution of
the source code, even though third parties are not compelled to copy the source along with the object
code.
1. You may not copy, modify, sublicense, or distribute the Program except as expressly provided
under this License. Any attempt otherwise to copy, modify, sublicense or distribute the Program
is void, and will automatically terminate your rights under this License. However, parties who
have received copies, or rights, from you under this License will not have their licenses terminated
so long as such parties remain in full compliance.
2. You are not required to accept this License, since you have not signed it. However, nothing else
grants you permission to modify or distribute the Program or its derivative works. These actions
are prohibited by law if you do not accept this License. Therefore, by modifying or distributing
the Program (or any work based on the Program), you indicate your acceptance of this License to
do so, and all its terms and conditions for copying, distributing or modifying the Program or works
based on it.
3. Each time you redistribute the Program (or any work based on the Program), the recipient
automatically receives a license from the original licensor to copy, distribute or modify the
Program subject to these terms and conditions. You may not impose any further restrictions on
the recipients exercise of the rights granted herein. You are not responsible for enforcing
compliance by third parties to this License.
4. If, as a consequence of a court judgment or allegation of patent infringement or for any other
reason (not limited to patent issues), conditions are imposed on you (whether by court order,
agreement or otherwise) that contradict the conditions of this License, they do not excuse you
from the conditions of this License. If you cannot distribute so as to satisfy simultaneously your
obligations under this License and any other pertinent obligations, then as a consequence you
may not distribute the Program at all. For example, if a patent license would not permit royaltyfree redistribution of the Program by all those who receive copies directly or indirectly through
you, then the only way you could satisfy both it and this License would be to refrain entirely from
distribution of the Program.
If any portion of this section is held invalid or unenforceable under any particular circumstance, the
balance of the section is intended to apply and the section as a whole is intended to apply in other
circumstances.
It is not the purpose of this section to induce you to infringe any patents or other property right claims
or to contest validity of any such claims; this section has the sole purpose of protecting the integrity of

the free software distribution system, which is implemented by public license practices. Many people
have made generous contributions to the wide range of software distributed through that system in
reliance on consistent application of that system; it is up to the author/donor to decide if he or she is
willing to distribute software through any other system and a licensee cannot impose that choice.
This section is intended to make thoroughly clear what is believed to be a consequence of the rest of this
License.
1. If the distribution and/or use of the Program is restricted in certain countries either by patents or
by copyrighted interfaces, the original copyright holder who places the Program under this
License may add an explicit geographical distribution limitation excluding those countries, so that
distribution is permitted only in or among countries not thus excluded. In such case, this License
incorporates the limitation as if written in the body of this License.
2. The Free Software Foundation may publish revised and/or new versions of the General Public
License from time to time. Such new versions will be similar in spirit to the present version, but
may differ in detail to address new problems or concerns.
Each version is given a distinguishing version number. If the Program specifies a version number of this
License which applies to it and any later version, you have the option of following the terms and
conditions either of that version or of any later version published by the Free Software Foundation. If the
Program does not specify a version number of this License, you may choose any version ever published
by the Free Software Foundation.
1. If you wish to incorporate parts of the Program into other free programs whose distribution
conditions are different, write to the author to ask for permission. For software which is
copyrighted by the Free Software Foundation, write to the Free Software Foundation; we
sometimes make exceptions for this. Our decision will be guided by the two goals of preserving
the free status of all derivatives of our free software and of promoting the sharing and reuse of
software generally.
NO WARRANTY
2. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE
PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED
IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM AS IS
WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH
YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY
SERVICING, REPAIR OR CORRECTION.
3. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY
COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE
PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL,
SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO
USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED
INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM
TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN

ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

END OF TERMS AND CONDITIONS
How to Apply These Terms to Your New Programs
If you develop a new program, and you want it to be of the greatest possible use to the public, the best
way to achieve this is to make it free software which everyone can redistribute and change under these
terms.
To do so, attach the following notices to the program. It is safest to attach them to the start of each
source file to most effectively convey the exclusion of warranty; and each file should have at least the
copyright line and a pointer to where the full notice is found.
, 1 April 1989 Ty Coon, President of Vice
This General Public License does not permit incorporating your program into proprietary programs. If
your program is a subroutine library, you may consider it more useful to permit linking proprietary
applications with the library. If this is what you want to do, use the GNU Lesser General Public License
instead of this License.

Using The Terminal

One of the great powers of Linux is the so-called command-line. This simple text interface for

computing unveils many of the gears and levers that make a computer tick. Many find it easier to
get things done, as it is a focused and terse way to interact with the computer.

When you first use the Terminal Emulator program, you may quickly find that you do not have
permission to do something. That is because many commands are safely reserved for root

access, and you are automatically logged in as the chip user. Dont fear: you can often use

the sudo command and use the default password chip to execute these restricted commands.
Finally, it is probably wise to change the default password on your CHIP. You can do with

with shell passwd or shell sudo passwd root and youll be asked for a new password. Dont
forget it!!

If you are such a fan of the command line, you may want to boot with out the desktop and window
system. Instructions for that are here

Terminal for Beginners Glossary

One of the great things about Linux is the terminal application. While it may look unfriendly and

terse, if you want to really extend the capabilities of CHIP, youll often find yourself in the terminal.
If youre a beginner, heres a quick reference of some really important and common commands.
You can simply add -h to get some hints on how to use a command, such as cp -h or you can
read a manual page usingman cp. Most unix commands have a variety of options that can be

executed in the command with flags, such as ls -l -a. Even better, search the internet! This

primer is simply here to help you understand what a command might be doing, not to help you use
it to its full ability.

cd change directory. open a folder. ex: cd ~/Pictures changes your current directory to

mkdir make directory. create a folder. ex: mkdir Vacation makes a folder

the home Pictures folder, so you can easily access the files within.

named Vacation in the current directory. mkdir ~/Pictures/Vacation makes

a Vacation folder in the home Pictures directory.

ls list files in the current directory so you know what is in it. Some options are ls -l to list
in long format to provide information about permissions, size, and date. ls -a to show
hidden files that start with the . character.

mv move a file from one directory to another, or to give it a new name. Ex: mv this.one

that.one renames a file. mv this.one ~/Pictures/Vacation/ puts the file this.one into
the Vacation directory.

cp copy a file from one place to another. Ex: cp this.one this_01.one will
copy this.one to another file this_01.one. Add directories for more fun: cp
~/Pictures/Vacation/saturn.jpg

/Users/otherone/Pictures/Vacation/saturn.jpg.

rm remove a file. delete it, and beware!. Use the -r to make it recursive to delete a

directory. Ex: rm this.one deletes that file. rm -r ~/Pictures/Vacation to forget the

good times.

sudo super user do. many commands need administrator-like privileges, otherwise they
wont work. apt-get is a command that needs to be run with sudo to allow files to be

written to protected directories. Youll see sudo as the first word in a lot of commands - all it
is doing is giving the command the necessary access. Youll be asked for a password the

first time you use sudo. The default password and user is chip.

apt-get the command used for installing, removing, and finding software for Debian Linux

systems, such as the CHIP Operating System. sudo apt-get install puredata installs
the Pure Data program and any dependencies. sudo apt-get remove puredata will

remove the program. sudo apt-cache search image will search apt repositories for the

keyword search. And so on.

pwd present working directory. In case you forget where you are. Not much to it: pwd will
output the directory name, such as /Users/home/chip/Pictures/Vacation/

grep a tool used for searching through files. Its quite deep and can be complicated, but if
you see the word grep in some command, you know its searching for a match.
| (pipe) a command used to redirect data into an application.
< (redirect) a command use to redirect data into a file.

cat concactenate. used to append data to a file. Ex: cat "Last line of text" >

sometext.txt. Merge files: cat append.txt > main.txt will put all the text in append.txt
into main.txt.

less makes it so you can paginate and read a text tile. Ex: less longtext.txt will fill the
screen with the first part of the longtext.txt file. Use the space bar to view the next page.
Type q to exit.

nano a text editor. Youll often see commands that call nano so you can edit a

configuration. Ex: nano /etc/avahi/services/afpd.service to edit the avahi Apple file

service file.

find look for files in the filesystem. Ex: find ~/Documents -name particular.txt -

type f will look for the file with the name particular.txt in the Documents directory.
chmod change mode. Used for file permissions, which can be important when sharing
things on the network, scripting actions, and many more reasons.

htop display the processes currently alive on the CPU. If things seem slow, or you want to
see how much CPU or memory a program is using, just type htop to see a table of all
running processes, then typeq when you want to exit.

scp secure copy. copy a file from one computer to another over a network. Ex: scp
Pictures/Vacation/motel.jpg Pictures/Vacation/accident.jpg

[email protected]:~/Pictures copies a couple jpegs to another computer on the

network.

ssh secure shell. access another computer on the network and use the terminal commands
to make changes and control it. Ex: ssh [email protected] to access your CHIP on a local
network.

CTRL C if you cant use the terminal because a process is taking too long, type CTRL-C on
your keyboard to cancel the most recent command.

Connecting Accessories
CHIP has a lot of connectors, some for building, some for doing normal computer things. This
section covers the normal computer things, like audio, video, and input.

Recommended Accessories

CHIP is a minimal computer. Many CHIP users may never connect common peripherals, instead
using CHIP as a headless computer. Like desktop computers from Best Buy, you may find that
certain accessories will improve the overal usability of CHIP. We recommend:

Bluetooth Keyboard

Monitor with a composite video input

USB mouse

USB cable: USB-A to microUSB-B

TRRS to RCA connector

Additionally, some of the advanced tutorials require:

Speakers with RCA audio input

USB to UART cable

Jumper wire

Single cell Lithium Polymer battery

Powered USB Hub

Youll find that a simple powered USB hub is pretty essential if you want to use a lot of USB

devices with CHIP. Not only is there only one USB port (keeping CHIP nice and small), but CHIPs
micro USB power port can only provide so much power for the USB port. If you dont have a
powered USB port, youll quickly max out power if you attach too many accessories.

Keyboard and Mouse

Many keyboards have USB hubs built-in, so you can attach a mouse to the keyboard, attach the
keyboard to CHIP, and immediately have control. However, its likely the two will draw too much
current, so youll want to connect to a powered hub before you connect.

Bluetooth Keyboard and Mouse

As you know, CHIP has built-in bluetooth. If you want to use a keyboard and mouse, you can keep
your USB port free for other things (like mass storage or a MIDI controller!) and keep your desk
clean. Seeconnecting to bluetooth section

Monitor

In the spirit of keeping things small, CHIP packs all the audio and video into a small TRRS (TipRing-Ring-Sleeve) connector. Built-in video output is restricted to standard composite video

resolution of 640x480. Higher video resolutions are possible using the VGA and HMDI DIP boards.

Heres what the other end of the cable looks like, attached to a monitor with stereo audio inputs
(red and white) and the composite video plug, moved so you can see the label on the monitor:

About the TRRS Connector

CHIP comes with a 1/8" (3.5mm) Tip-Ring-Ring-Sleeve (TRRS) jack, capable of carrying stereo
audio, and either composite video out, or microphone in.

This is a fairly common port, but there are a few different arrangements of the conductors, so not
all cables are equal. Fortunately, CHIP uses the same conductor arrangement as Pi, Zune, and
iPod audio/video cables, so the most common mini to RCA A/V cables should work just fine.
Some cables will route signals a bit differently, using the Red RCA cable for Video instead of

Yellow. If video out isnt working through the yellow cable, see if red works. If not, your cable may
be a version thats arranged in a way that it just wont work with CHIP:

yellow : video

white : stereo audio left channel

red : stereo audio right channel

The conductors on the TRRS plug are arranged like this:

If you want to learn even more about TRRS connectors and the general lack of standardization
with them, this page has even more details.

NTSC or PAL

The composite video format is NTSC by default. If you need to hook up to a monitor that only uses
a PAL signal, youll need to change that at u-boot time. First, connect to CHIP with a UART cable.
Then power up CHIP, and press a key on the keyboard to boot into u-boot mode to change the
environment variable manually.
printenv video-mode

setenv video-mode (mode data)

saveenv
reset

where mode data can be, for NTSC and PAL respectively:
setenv video-mode sunxi:640x480-24@60,monitor=compositentsc,overscan_x=40,overscan_y=20

setenv video-mode sunxi:720x576-24@50,monitor=compositepal,overscan_x=40,overscan_y=20

Headphones

The audio and video connector on CHIP can be dedicated to audio output suitable for headphones
or connecting to an amplifier for filling a room or public space with glorious sound. Just connect a

standard 3.5 mm (1/8") TRS audio plug into CHIPs a/v jack. Of course, if headphones are plugged
in, there will be no room for a composite video output jack. You can also get audio left, common,
and right output frompins 4, 6 & 8 on header U14.

Microphone and Audio Input

If you want to use audio input, you might find it easiest to use the pins on pins 10 and 12 on

header U14. However, if you want to use the 1/8" TRRS connector, you can modify the CHIP
board to replace the composite video connection with an audio input connection.

If you look at the bottom of CHIP with the audio and USB jacks pointed up, youll see three small
contact pads to the left of the audio jack. The left pad has a small label of mic and the right pad

has a tv label. Between the middle pad and the tv pad is a trace that can be carefully cut with an

Exacto or utility razor blade. Once that is cut (check with a volt or continuity meter), you can put a
solder blob between the micand middle pad. Now the outer ring can be used for audio input.

As another reference, if you had X-ray vision and you were looking from the bottom of CHIP,
youd see a trace like this:

If the composite video connection is needed again, just reverse the process: desolder the

connection between mic and the middle pad, then solder a bridge between tv and the middle pad.

Microphone with Header Pins

If you want to use the pins 10 and 12 on header U14, youll most likely need to add some
additional circuitry to get a good input signal. Here is a schematic of the simple circuit:

Youll need two 4.7 microfarad capacitors, one 100 nanofarad capacitor, and a 3300 picofarad
capacitor. Youll also need one 2 kilo-ohm and one 4.3 kilo-ohm resistors.

USB Storage

If you have files that you want to modify, use, or transfer to CHIPs internal storage, you can attach
a USB thumb drive, card-reader, or hard drive. Open the file manager and access the files.

USB Audio

CHIP can use Class-compliant USB audio devices. A popular, and inexpensive choice for audio
devices are USB dongles based on the C-Media chipset. These have been tested successfully

with CHIP and can often be purchased for less than $10. Some good resources for linux and audio
compatibility are on the linux audio and alsa project websites.

Many of the drivers have not been tested with CHIP - as CHIP matures, more information will be
available. For now, we recommened USB Class-compliant or plug-and-play audio devices.

Battery and Charging

Like any modern laptop, CHIP can run and charge any single-cell LiPo battery. Read more in
the powering CHIP section.

Using The CHIP Operating System

If youve used a desktop or laptop computer before, the CHIP Operating System should be pretty
familiar. There are menus, icons to click, menus with more stuff when you right-click, keyboard

shortcuts, applications to run, and settings to set. CHIP is small, so we keep our operating system

simple. Almost everything can be accessed from the Computer Things menu: settings, launching
apps, and access to files. Theres also a few convenient functions in the top right system tray.

Settings and Configuration

Most of the settings for the computer and for the desktop can be set using the apps in the

Computer Things menu. Select the appropriate app from either the Settings Menu or the Settings
Manager.

WiFi

Connecting to a WiFi network is easy using the WiFi icon the top right system tray. Just select a
network to initiate a connection. If you need a password, youll be prompted for it.

If you need more control and information over your network connection, use the Settings->Network
Connections panel to show your connections. Double click on a connection to bring up the
connection editor:

Bluetooth

Bluetooth device setup can be accessed using the Bluetooth icon in the top right system tray.

When you begin a connection, youll be guided through the necessary steps to connect to your

device. For example, when you pair with a keyboard, youll often be prompted for a code to enter

to ensure a unique connection. Once you have paired a device, future connections will usually be
automatic when the devices are in range and powered up.

You can manage, and also connect to, your devices using the the Bluetooth Devices panel,
accessed from the Bluetooth system tray:

Sound

By default sound output comes from the built-in connector, served by the sunxi codec driver. If
you want to change the volume, you can use the volume control in the top right system tray:

Or, open the Audio Mixer in the Multimedia category:

Here, you can select the Playback category to change the volume:

If you dont see that control, just click on the Select Controls button and enable all controls:

Display

Use the Settings->Display control panel to adjust the monitors resolution and rotation settings:
If you want to customize the desktop image, icons, colors, and fonts, there are two different panels.
The Appearance panel lets you select a theme to make instant changes for several properties.

The Desktop panel lets you customize images and colors, along with the behavior of menus.

If you want to change the theme or the icon sets, you can search for these using the Synaptic

Package Manager. Search for gtk2 themes or icon sets. There are also packages that can

make it easy to find and configure themes, such as gtk-theme-config. Similarly you can use the
command line to search packages with apt-cache search gtk2 theme.

Time and Date

Set the Time with the Orage Globaltime panel. This can be found in Accessories->Orage

Globaltime or in Office->Orage Globaltime. Simply click the time to bring up the preferences panel.
You can quickly view the date from the Orage Calendar in the Office menu.

Mouse Sensitivity

Mouse sensitivity is set for the default 640x480 resolution. If you are using CHIP with a higher

resolution monitor, you may want to adjust the sensitivity of the mouse. You can get to the Mouse
settings panel from Computer Things->Settings->Mouse and Touchpad

Language and Location

CHIPs operating system comes with a default language of English. You can change the language
and the location, but youll need to use the terminal to do so. Use the Computer Things! menu to
launch the Terminal Emulator. Then use the apt-get command to install the language packs and
run a simple program to configure your language and location:

sudo apt-get update && sudo apt-get install locales && sudo dpkg-reconfigure
locales && sudo locale-gen

Youll get a large menu to select locales. Use the arrow keys to scroll down and spacebar to mark
your location with an [*]. Its advised that you choose the location marked UTF8. Others are
somewhat arcane edge cases! Hit return to continue.

You can set the timezone with

sudo dpkg-reconfigure tzdata

Launching Installed Apps

CHIP comes prepackaged with many open-source applications to get you started. Its easy to

launch an application. You can select an application from the Computer Things! menu and select
an app from the categories:

Or, for more control, launch the Application Finder in Accessories, where you can use the search
bar and easily navigate among the categories:

Below are some of the applications that come pre-installed with CHIP:

AbiWord

AbiWord is a fully featured word processor. You can learn more at The AbiWord website

Ice Weasel Browser

Ice Weasel is a Debian Linux version of the Firefox browser. The browser is largely the same as
Firefox, just with a different name. More information is at the Debian website and in this stack
exchange thread.

Video Player

CHIP plays video! Use the built-in Mplayer to open and play videos.

Terminal (commandline)

The life blood of linux. If theres something you cant do on the desktop, or you want to automate

tasks, or access different hardware settings using nothing but a keyboard and text, youll open up
Terminal.

Complete List of Installed Software

These are the applications installed by default on CHIP as accessed through the GUI.

Application Finder

Leafpad

Bulk Rename

Orage Globaltime
Screenshot

Task Manager

Thuner File Manger

Xarchiver

Alex the Allegator 4

Spout

Viewnior

Ice Weasel Web Browser

Audio Mixer

GNOME MPlayer

AbiWord

QjackCtl

Atril Document Viewer

Gnumetric

Orange Calendar

Orage Globaltime
Htop

Package Updater

Synaptic Package Manager

Xfce Terminal
Notifications

Various System Settings

Zip (and UnZip)

Install and Update Software

Synaptic Package Manager

Launch the Synaptic Package Manager to find and install new software. Synaptic is a graphical

interface to the apt-get command and will install software intended for DERP and other debainbased systems. You can learn more about Synaptic here

Theres a simple search bar to make it easy to find packages you are interested in. If you dont find
the package you are looking for, hit the Reload button to refresh Synaptics record of available
packages.

Example: Installing Scratch Programming Environment

Using Synaptic is very easy. For example, if you wanted to install the Scratch Programming

Environment, you can simply search for scratch and youll get a lot of results. Scroll through, and
youll eventually find scratch in the packages window. However, youll probably want to narrow
your results with better search terms, such as scratch programming environments

When search is complete, you can select scratch from the package panel.

Press the top Apply button, and youll get the following dialog:

and youll be notified of the progress:

After a minute or so, youll be notified that its finished:

Now that its installed, you can launch scratch:

Auto Update

CHIP will automatically look for any updates and alert you if updates are available for your existing
software and the operating system.

apt-get

If you are using the commandline, you will use apt-get to install and update new software.
If you are new to apt, some important commands to know:

sudo apt-get update updates the information from repositories, so any installs you make

sudo apt-get upgrade upgrades any installed packages.

with install will be the latest package

sudo apt-get install (name of package) to install a package and any of its
dependencies.

sudo apt-get remove (name of package) will remove a package and any
dependencies not used by other packages

sudo apt-get purge (name of package) will remove a package and any dependencies
not used by other packages along with all settings data

apt-cache search (search terms) will search through the package repositories for
names and descriptions that include your search term.

Uninstall Software

You can use the Synaptic Package manager to uninstall any packages you no longer need. If you
know the name, you can use the Search function to find the package, then Mark it for Removal.
For example, if you want to remove AbiWord, first open Synaptic and search for abiword:

Once found, select AbiWord in the package list, and select Mark for Removal in the Package
menu:

If there are additional, related packages that need to be removed, youll be notified:

Finally, press the top Apply menu to remove the packages:

Youll be notified what changes will be applied:

Finally, you can confirm that AbiWord has been removed by checking the Applications menu:

Boot into Console

If you want want CHIP to boot directly into a console, and not load the Desktop or Window

manager GUIs, there are a couple options. For the temporary case, you can open a terminal
window and use the command

sudo systemctl set-default multi-user.target

Next time you boot CHIP, it will not load the desktop or window environment, leaving you with

command-line operation only. If you wanted to return to booting into the GUI, you can use this
command before you reboot:

sudo systemctl set-default graphical.target

The other option is to run a linux distribution with no GUI installed. You may want to do this if you

want to use commandline only and want to save some storage space. You can follow instructions
to flash CHIPwith buildroot, or Debian (with no GUI).

CHIP Hardware

CHIP is small, but it packs a lot of hardware on the PCB. Heres an overview of the connections
and components.

Parts and Pieces

Wireless

WiFi

CHIP supports 802.11b/g/n using the built-in WiFi.

Bluetooth

CHIP supports the Bluetooth 4.0 LE standard using the built-in Bluetooth.

Physical Connectors

CHIP is loaded with essential connectors for USB, serial, audio, video, and loads of IO on the pin
headers. Oh, and a button too!

Button

There is a tiny tiny button on CHIP next to pin header U13 that is used for turning CHIP on or off. If
CHIP is off and connected to a power source, hold down the button for one second to power it up.
To turn CHIP off (rather brutally), hold the button for 10 seconds. We recommend using the
operating system to power CHIP off, but if you need to, you can use this button.

USB

The single USB port on CHIP is USB 2.0 compatible. It can provide up to 500mA of current, as is
standard for USB ports on computers. If you need to provide more current, we recommend a
powered USB hub.

USB On The Go

The micro USB port is generally used to provide power for CHIP. However, since CHIP can be

powered through the pin headers or a battery, this port can be used for different things. By default,
connecting CHIPs micro USB to a computer will create a USB Serial connection, so you can
access CHIP with a screen or cu session in a terminal. With Linux kernel modifications, it is
possible to enable other modes, such as an Ethernet bridge.

Composite Video and Stereo Audio

The 1/8" TRRS connector provides composite video and stereo audio output. Headphones can be
plugged in for audio only.

Audio Input uses the same connection on the TRRS connector as the composite video signal. If

you want to make audio input active on the TRRS connector, you need to cut a circuit board trace.
This is not as permanent as it sounds, as it is easy to re-enable composite video out with a small
amount of soldering.

Pin Headers

The Pin Headers provide a massive amount of connectivity, making CHIP a suitable platform for
product development for physical computing and internet of things devices. Heres a basic
diagram that labels all the pins:

U13L

U13R

U14L

U14R

GND : ground

CHG-IN : 5V input

GND : ground

VCC-5V : 5V power

UART1-TX : UART

HPL : audio out left

(power and battery

charge)

VCC-5V : 5V
power

GND : ground

serial transmit

U13L

U13R

U14L

U14R

VCC-3V3 : 3V

TS : analog

UART1-RX : UART

HPCOM : audio out

FEL : fel mode:

HPR : audio out right

power

VCC-1V8 : 1.8 V
power

temperature sensor
input

BAT : LiPo battery

serial receive

connect to ground

common ground

to put CHIP in fel

mode for firmware

TWI1-SDA : two-

PWRON : power on

VCC-3V3 : 3 volt

MICM : mic mute

TWI1-SCK : two-

GND : ground

LRADC : low-res

MICIN1 : audio in

wire serial bus 1

wire serial bus 1

X2 : Resistive

(touchscreen)

(touchscreen)

Y1 : Resistive

touchpanel input

LCD-D2 :

RGB666 data

Analog-Digital
Converter

X1 : Resistive

touchpanel input

power

touchpanel input

Y2 : Resistive

touchpanel input
(touchscreen)

PWM0 : pulse width

modulation (also
used for LCD

XIO-P0 : expander

XIO-P1 : expander GPIO

XIO-P2 : expander

XIO-P3 : expander GPIO

XIO-P4 : expander

XIO-P5 : expander GPIO

XIO-P6 : expander

XIO-P7 : expander GPIO

GPIO

GPIO pin 2

GPIO pi

pin 1

pin 3

pin 5

backlight dimming)
LCD-D4 :

RGB666 data

LCD-D3 : RGB666
data

GPIO pin 6

pin 7

U13L

U13R

U14L

U14R

LCD-D6 :

LCD-D5 : RGB666

GND : ground

GND : ground

LCD-D10 :

LCD-D7 : RGB666

AP-EINT1 :

AP-EINT3 : Application

Processor Interrupt

necessary for certain kinds

RGB666 data

RGB666 data

data

data

Application

Processor Interrupt pin,

of hardware-software

interactions (keyboard
expander, etc.)
LCD-D12 :

RGB666 data

LCD-D14 :

RGB666 data

LCD-D11 : RGB666
data

LCD-D13 : RGB666
data

TWI2-SDA : twowire serial bus 2

(I2C)

CSIPCK : CMOS
serial interface

TWI2-SCK(*) : two-wire
serial bus 2 (I2C)

CSICK : CMOS serial

interface, can be used for

attaching a serial camera
sensor

LCD-D18 :

RGB666 data

LCD-D15 : RGB666
data

CSIHSYNC :
CMOS serial

CSIVSYNC : CMOS sync

interface

LCD-D20 :

LCD-D19 : RGB666

CSID0 : CMOS

CSID1 : CMOS serial

LCD-D22 :

LCD-D21 : RGB666

CSID2 : CMOS

CSID3 : CMOS serial

LCD-CLK :

LCD-D23 : RGB666

CSID4 : CMOS

CSID5 : CMOS serial

RGB666 data

RGB666 data

RGB666 clock

data

data

data

serial interface

serial interface

serial interface

interface

interface

interface

U13L

U13R

U14L

U14R

LCD-VSYNC :

LCD-HSYNC :

CSID6 : CMOS

CSID7 : CMOS serial

LCD screen

LCD

GND : ground

GND : ground

vertical sync for

GND : ground

horizontal sync for

LCD-DE : RGB666
data

serial interface

interface

(*)The XIO GPIO pins are provided by an I2C Expander at address 0x38 on the TWI bus 2, as
such, this address is not available on bus 2.

Mechanical Drawing

Our git repo for CHIP hardware has a mechanical drawing

Open Source Hardware: Where To Get It

CHIP is open source hardware. Heres where you can get all the data you need to make, modify,
or learn about your own CHIP. Visit the CHIP Hardware git repository.

Making Stuff
CHIP is more than a cool, small, inexpensive computer. Its a complete system for building projects
that require remote control, network connectivity, and physical interfacing with people and the

environment. CHIPs pin headers have all the connections to make this happen. An annotated
diagram of the pin headers can be found in the hardware section of this manual.

GPIO

GPIO provides basic digital connections to the physical world to create physical products with

CHIP. These pins can act as reads or 'writes, for example, to sense switch positions or turn an
LED on or off.

CHIPs most easily available IO pins are the XIO pins on header U14. This is the GPIO
eXpander that uses an I2C bus to create eight (8) convenient pins for GPIO. These use

address 0x38 on the TWI bus 2. Other pins are available for GPIO if more than eight are needed.

Read and Write From Command Line

CHIP has several General Purpose Input/Output (GPIO) pins available for you to build around. If

you want to access them in a very primitive way, just to confirm their existence, heres some things
to try.

Requirements

CHIP

LED

Jumper Wire
SSH or serial connection to CHIP or
Monitor and keyboard

How You See GPIO

There are eight (8) GPIO pins always available for connecting CHIP to the sense-able world. If you
orient CHIP with the USB connector pointed up, youll find the GPIO pins in the middle of the right
header, U14, Pins 13-20, labeled XIO-P0 to P7:

Kernel 4.3 vs 4.4 GPIO - How To Tell The Difference

For various reasons related to the community nature of Linux development, the GPIO expander pin
numbers are different between CHIP OS kernels 4.3 and 4.4. What follows is a very technical
discussion of the GPIO access. If you just want to start making stuff and dont need low-level
information, you might just want to skip this section and go straight to the python library.

If you are developing applications on CHIP that use GPIO pins and you would like consistent

behavior between the two kernel versions, you need to know how to find out the base value for the
GPIO values. It may be enough for you to know that the GPIO expander pins start at 408 on 4.3

and 1016 on 4.4, however, it would be ideal to calculate this in your application to truly future-proof
for future kernels.

If you look in the directory /sys/class/gpio, youll find two directories starting
with gpio: gpiochip0 and either gpiochip408 (4.3) or gpiochip1016 (4.4).

The 408 and 1016 are the bases for the expander pins. If you want to definitively find out what the
base is using code, you should
cat gpiochip*/label
cat gpiochip*/ngpio
cat gpiochip*/base

The label you are interested in is the value pcf8574a which is the device that provides GPIO

expansion. This provides the number of GPIO as returned by ngpio. The first expander pin starts
with the basevalue. If you parse all these values and apply to your code, you can setup your
application to be kernel-agnostic for GPIO access.

Here is a python script that demonstrates this in a gist

Here is a bash script to compute the base (courtesy of bbs user @fordsfords)
LABEL_FILE=`grep -l pcf8574a /sys/class/gpio/*/*label` BASE_FILE=`dirname
$LABEL_FILE`/base

BASE=`cat $BASE_FILE`

How The System Sees GPIO

There is a sysfs interface available for the GPIO. This just means you can access the GPIO
states in a file-system-like manner. For example, you can reference XIO-P0 using this path:
/sys/class/gpio/gpio408/

The number is somewhat unfortunate, since the sysfs names do not match the labels on our

diagram! But is not too hard to translate. Pins XIO-P0 to P7 linearly map to gpio408 to gpio415 on

kernel 4.3 andgpio1016 to gpio1023 on kernel 4.4. See above to learn more about that
distinction.

Some GPIO Switch Action

These lines of code will let us read values on pin XIO-P7. First, we tell the system we want to listen
to this pin:
#4.3

sudo sh -c 'echo 415 > /sys/class/gpio/export'

#4.4

sudo sh -c 'echo 1023 > /sys/class/gpio/export'

View the mode of the pin. It should return in:

#4.3

cat /sys/class/gpio/gpio415/direction
#4.4

cat /sys/class/gpio/gpio1023/direction

Connect a jumper wire between Pin 20 (XIO-P7) and Pin 39 (GND). Now use this line of code to
read the value:
#4.3

cat /sys/class/gpio/gpio415/value
#4.4

cat /sys/class/gpio/gpio1023/value

Some GPIO Output

You could also change the mode of a pin from in to out

#4.3

sudo sh -c 'echo out > /sys/class/gpio/gpio415/direction'

#4.4

sudo sh -c 'echo out > /sys/class/gpio/gpio1023/direction'

Now that its in output mode, you can write a value to the pin:
#4.3

sudo sh -c 'echo 1 > /sys/class/gpio/gpio415/value'

#4.4

sudo sh -c 'echo 1 > /sys/class/gpio/gpio1023/value'

If you attach an LED to the pin and ground, the LED will illuminate according to your control
messages.

Enough IO

When you are done experimenting, you can tell the system to stop listening to the gpio pin:
#4.3

sudo sh -c 'echo 415 > /sys/class/gpio/unexport'

#4.4

sudo sh -c 'echo 1023 > /sys/class/gpio/unexport'

Learn More

You can learn more about GPIO and Linux here:

Python Library

There is a well-maintained python library that works for 4.3 and 4.4 kernels available here. This is
analogous to the RPi.GPIO library, but is designed for CHIP. Its an excellent place for quickly
working with GPIO and PWM on CHIP.

GPIO Types

There are many types of sensors that can be used with GPIO:

Switches

Switches provide on/off state input from the physical world to your computer. You can use the
commandline interface to listen to switch values. A python library was created for
the ChippyRuxpin project if you need a higher-level example in python.

LEDs

LEDs can be illuminated and turned off using the commandline interface. Refer to

the ChippyRuxpin project on a good example on how to manipulate the commandline using
python.

Relays

Relays are special hardware bridges used to switch higher voltage electronics, protecting CHIP

from the high voltages that would destroy it. Using a relay board is programmatically no different
from using switches.

Expanding GPIO

If you dont need to drive an LCD, you can use those pins for more, faster GPIO if you want to.
These are the pins numbered 18-40 on U13 and 27-40 on U14 to act as GPIO to increase the
number of available GPIO pins. Documentation on this process is forthcoming!

Analog to Digital Conversion

Pin 9 on header U14 provides a link for low resolution analog to digital conversion (ADC). There is
no driver for this link yet. ADC is used to read continuous sensors (temperature, pots, FSR,
photoresistor, etc)

1 Wire

The 1 Wire serial protocol is not available in CHIP OS 4.3. In version 4.4 and above, you can
access one wire data from the sysfs device. Find your one wire devices with
ls /sys/bus/w1/devices/2*/eeprom

The * is there because your eeprom device will register a unique UUID number with C.H.I.P., so
the ls command will show you all available one wire devices.

UART

UART connections can be made using the UART connections on header U14.

PWM

Pulse Width Modulation is used to control motors and other devices. It is possible to use GPIO

pins to drive motors, but they generally are not fast enough for robust and smooth control. PWM
can be accessed through an sysfs protocol.

I2C

I2C can be accessed through a sysfs protocol using the debian i2c-tools. In the terminal, use
sudo apt-get install i2c-tools

Note that the XIO GPIO pins are provided by an I2C expander at address 0x38 on the TWI bus 2,
so that address cannot be used on bus 2.

LCD Monitor Support

Using the numerous LCD header pins, a color touchscreen panel can be directly implemented on
CHIP.

Project Examples
Projects coming soon!

Flash CHIP With an OS

You might want (or need) to completely re-flash your CHIP with a different operating system.
Weve made it really easy to do this by embedding the entire process in a browser-based
application. Just hook CHIP up to your computer, fire up a browser, and flash your CHIP

Things you will need

C.H.I.P.

Thin Paper clip (a jumper wire works too)

Standard-USB to micro-USB connector

Separate computer with Chrome or Chromium browser

Instructions

If you dont have the Google Chrome or the open-source Chromium browser on your other
computer, install it by following the preceding links.

Ok, good. Now that you have installed the browser, you can visit flash.getchip.com in Chrome or
Chromium and follow all the instructions. If you are using a computer with USB3 ports, its

suggested that you attach a USB2-compliant hub and connect your CHIP to the hub, instead of
directly to the USB3 port.

Its possible to run the entire operation online. There are also options for downloading the OS

image to your computers harddrive, then flashing your CHIP with no additional need for internet
access.

For more information on OS-specific issues, see here.

The SDK Way

You may not want to use the browser-based flashing procedure. If this is the case, or you need
additional tools, you can flash using the CHIP SDK

Web Flasher OS-Specific Issues

Before you try anything else, try using a different USB cable. Many cables are charging-only, or do
not support high bandwidth and will cause flashing to fail.

Windows-specific

You must install drivers to be able to talk with C.H.I.P.

Reboot after installing drivers on previous versions (<10) of Windows.

Unfortunately, due to the nature of how Windows manages drivers, the flashing procedure will

likely fail the first time you use it. When that happens, try completely closing and reopening your

browser. Depending on your version of windows, this might happen twice, once when waiting for
FEL, and then again waiting for Fastboot.
Troubleshooting

Try using a USB2 port (USB3 ports have issues).

Try a different USB cable. They often are bad.

Try passing through a USB2 hub if using a USB3 port.

Try turning off antivirus software.

If you get stuck Waiting for Fastboot and the above options dont work, you should be able
to install a headless no fastboot image. However, it will take quite a bit longer, and the
Operating System wont have a GUI.

MacOS specific

There are some times where using USB3 ports will cause the flashing to fail. If you can, try
using a USB2 port, not a USB3. Recent Macs have only USB3 ports. If you find yourself
with a modern Mac, try using a USB2 hub in your USB3 port and plug C.H.I.P. into that.

If you get stuck Waiting for Fastboot and the above options dont work, you should be able
to install a headless no fastboot image. However, it will take quite a bit longer, and the
Operating System wont have a GUI.

Linux-specific

Linux requires permissions to write to C.H.I.P. when its plugged into your computer. Chrome (or

Chromium) does not have these permissions, so you need to explicitly create them before youll be
able to use the web flasher .
On Ubuntu:
You need to paste the following into a terminal:
sudo usermod -a -G dialout $(logname)
sudo usermod -a -G plugdev $(logname)
# Create udev rules

echo -e 'SUBSYSTEM=="usb", ATTRS{idVendor}=="1f3a", ATTRS{idProduct}=="efe8",

GROUP="plugdev", MODE="0660" SYMLINK+="usb-chip"

SUBSYSTEM=="usb", ATTRS{idVendor}=="18d1", ATTRS{idProduct}=="1010",

GROUP="plugdev", MODE="0660" SYMLINK+="usb-chip-fastboot"

SUBSYSTEM=="usb", ATTRS{idVendor}=="1f3a", ATTRS{idProduct}=="1010",

GROUP="plugdev", MODE="0660" SYMLINK+="usb-chip-fastboot"

SUBSYSTEM=="usb", ATTRS{idVendor}=="067b", ATTRS{idProduct}=="2303",

GROUP="plugdev", MODE="0660" SYMLINK+="usb-serial-adapter"
' | sudo tee /etc/udev/rules.d/99-allwinner.rules
sudo udevadm control --reload-rules
Then logout and log back in.
For the curious:

logname: outputs your username

plugdev: allows non-root mounting with pmount

dialout: gives non-root access to serial connections

The udev rules then map the usb device to the groups.
For more information, check the systems group page on debian.org.
USB3 Issues * If you have any issues, try using a USB2 port and not a USB3 one, or try using a
USB2 hub in your USB3 port and plug C.H.I.P. into that. * If you get stuck Waiting for Fastboot

and the above options do not work, you should be able to install a headless no fastboot image.
However, it will take quite a bit longer, and the Operating System wont have a GUI.

Caveat In rare cases, you may have an issue with your computer putting C.H.I.P. into autosuspend mode. Here is an example on how to fix this problem:
apt-get install laptop-mode-tools

#### edit /etc/laptop-mode/conf.d/runtime-pm.conf, uncomment/change

AUTOSUSPEND_RUNTIME_DEVID_BLACKLIST

#### add all fel devices to the blacklist:

AUTOSUSPEND_RUNTIME_DEVID_BLACKLIST="1f3a:efe8"
reboot

Advanced
For those interested in building with a stripped-down version of an operating system, or looking to
customize CHIP from the command line, we have several tutorials that describe how to setup
CHIP with more depth.

Installing C.H.I.P. SDK

CHIP-SDK has everything needed to develop software for C.H.I.P. Most importantly, if you want to
load an operating system onto CHIP, the only supported way is to do this from a virtual machine.
Given that the virtual machine runs Ubuntu, its pretty safe to say that Ubuntu users can flash
without the virtual machine.

Requirements

Computer running OS X 10.10+, Ubuntu 14.04+, or Windows 7+

Software: VirtualBox, Vagrant, git, terminal

At least 1 GB free RAM, up to 40 GB of disk space may be used

Software Setup

There are several required software pieces to get the CHIP SDK virtual machine running.
Install VirtualBox and Extensions

Get the installer for Virtual Box

If you are using Windows, you need to add the VirtualBox installation directory to your

Install the Oracle VM VirtualBox Extension Pack.

PATH.

In case of an Ubuntu host: add your user to the vboxusers group!

Install Vagrant
Install Vagrant from the Vagrant site. Alternatively, if OS X, you can use the homebrew package
manager: brew install caskroom/cask/brew-cask brew cask install vagrant

Install Git
Installation of Git depends on your operating system:

Windows: direct to download

OS X homebrew: brew install git

Debian Linux: sudo apt-get install git

Clone the CHIP-SDK repository and boot the Virtual Machine

Assuming you have git in your PATH, open up a terminal and type:
git clone https://github.com/NextThingCo/CHIP-SDK
and start up the virtual machine:
cd CHIP-SDK
vagrant up

Login To Virtual Machine

In the same shell on the host type the following:

vagrant ssh

If everything went well you should see the following prompt:

vagrant@vagrant-ubuntu-trusty-32:~$
All The Commands At Once
Heres all the commands in one place:
git clone https://github.com/NextThingCo/CHIP-SDK
cd CHIP-SDK
vagrant up

vagrant ssh

Congratulations! Now youre ready to Flash a C.H.I.P. from your SDK!

Troubleshooting

Here are a few possible problems.

Shared Folder Out of Sync
In case you run into trouble because the kernel in the VM was updated and the shared vagrant

folder can no longer be mounted, update the guest additions by typing the following in the CHIPSDK directory on the host:

vagrant plugin install vagrant-vbguest

This blog post has some more tips on keeping additions in sync.
Invalid State
If you get an error like:
error: The guest machine entered an invalid state while waiting for it to boot.
This probably means your version of VirtualBox needs updating and/or needs the Extension Pack.
Update as necessary and try vagrant up again.
Couldnt Find File
If you get the error:
error: Couldn't open file /Volumes/Satellite/gitbins/CHIP-SDK/base

that means you didnt cd CHIP-SDK. Very basic, perhaps, but late nights sometimes need that
bump!

Updating the CHIP-SDK Virtual Machine

You may have been working with CHIP for a while now, and you want to updated your SDK. Its

only slightly more involved than sync'ing with the git repo; you have to update the virtual machine,
too.

Requirements

Computer running OS X 10.10+, Ubuntu 14.04+, or Windows 7+

Existing installation of CHIP-SDK

How To Update
Just follow these steps:
On your host operating system, pull the latest changes from our Git repository:
cd ~/CHIP-SDK
git pull

Make sure the virtual machine is shut down and update it:
vagrant halt

vagrant provision

Now you can boot the virtual machine and ssh into it:
vagrant up

vagrant ssh

Once you see the trusty prompt, your CHIP SDK virtual machine is ready to use:
vagrant@vagrant-ubuntu-trusty-32:~$
All The Commands At Once
Heres all the commands in one place:
cd ~/CHIP-SDK
git pull

vagrant halt

vagrant provision
vagrant up

vagrant ssh

Flash CHIP Firmware

Now that the virtual machine and SDK are running and configured, you can connect CHIP to your
computer and give it an operating system. If you want to flash using a native Ubuntu installation,
read how toprepare Ubuntu to flash
Have you repaired your CHIP?
The original batch of CHIPs shipped with a software bug in the NAND flash storage. Weve built a
repair tool.

Prepare CHIP for Flashing

Prepare CHIP with a jumper wire connecting Pin 7 and Pin 39 on header U14 (FEL pin and GND).
Heres a reference image that labels the headers and pins:

Note: this jumper needs to be present only when you connect CHIP to power. If for some reason
the wire becomes disconnected after you have powered CHIP, there is no problem or need to
panic.

Now connect CHIP to your computer with a micro-USB->USB-A cable. The power LED will
illuminate.

Option 1: Flash With NTC Buildroot OS

Buildroot is a lean operating system, and does not have a package manager to install software.

You can add additional software before you flash CHIP by customizing buildroot. To flash CHIP
with the buildroot OS:
cd ~/CHIP-tools

./chip-update-firmware.sh -f

The -f option means fastboot. If you have problems flashing, particularly on Windows or OS X,
you can run ./chip-update-firmware.sh to disable fastboot flashing.

During flashing, the terminal will fill with messages. If successful, youll see C.H.I.P. run through a
hardware test, with the answers being OK. If C.H.I.P. is 'OK, you can remove the jumper wire.
Here is asample successful output.
Option 2: Flash With Debian
If you want to flash CHIP with the debian OS with no window manager or GUI

cd ~/CHIP-tools

./chip-update-firmware.sh -d -f

The -f option means fastboot. If you have problems flashing, particularly on Windows or OS X,
you can disable fastboot by leaving off the -f option: ./chip-update-firmware.sh -d. Here is
a sample successful output.

Option 3: Flash With CHIP Operating System

If you want to flash CHIP with the complete CHIP Operating System
cd ~/CHIP-tools

./chip-update-firmware.sh -d -b stable-gui -f

During flashing, the terminal will fill with messages. If successful, youll see C.H.I.P. run through a
hardware test, with the answers being 'OK. If C.H.I.P. is 'OK, you can remove the jumper wire.
Here is asample successful output. Because of filesize, the gui option must also include the f fastboot option. Windows and OS X are not yet supported as flashing hosts.
Connect to CHIP and Do Something
If everything went OK, you can now power up your CHIP again and connect via serial as a USB
gadget:

screen /dev/ttyACM0 115200

You can login to CHIP as chip or root using the password chip.
and even test the hardware:
hwtest
Customize Buildroot
If you want to customize buildroot, use these commands before you run the ./chip-updatefirmware.sh script to flash CHIP with firmware:
cd ~/CHIP-buildroot
make chip_defconfig
make nconfig

The nconfig command will display a text interface in your terminal. Use your arrow keys to
browse and select additional software for the buildroot OS. When youre finished with your

selections, exit by hitting the F9 key, which will automatically save your custom buildroot to:
/home/vagrant/CHIP-buildroot/.config

Now lets build your buildroot with your custom additions: shell make This will take a while,
maybe an hour. When finished, flash CHIP with the script:

cd ~/CHIP-tools

BUILDROOT_OUTPUT_DIR=../CHIP-buildroot/output ./chip-fel-flash.sh

Unless you changed the users or passwords, you can login to CHIP as chip or root using the
password chip.

Appendix

Sample outputs are provided in this appendix so you can more easily troubleshoot or proceed with
confidence when flashing CHIP with firmware.
Buildroot Output
Sample output from flashing Buildroot to CHIP looks like:
ROOTFS_URL=http://opensource.nextthing.co.s3.amazonaws.com/chip/buildroot/stabl
e/71/images
BUILD=71

BR_URL=http://opensource.nextthing.co.s3.amazonaws.com/chip/buildroot/stable/71
/images

BR_BUILD=71

/home/doge/gits/CHIP-tools/.firmware/images/rootfs.ubi exists... comparing to

http://opensource.nextthing.co.s3.amazonaws.com/chip/buildroot/stable/71/images
/rootfs.ubi

MD5: 90315ca1fb8ff95fc6878ce8126bdf02

S3_MD5: 6d59af4a0f673e1d61147e4a06dd7ba8
md5sum differs

--2015-10-21 15:59:16--

http://opensource.nextthing.co.s3.amazonaws.com/chip/buildroot/stable/71/images
/rootfs.ubi

Resolving opensource.nextthing.co.s3.amazonaws.com

(opensource.nextthing.co.s3.amazonaws.com)... 54.231.176.13
Connecting to opensource.nextthing.co.s3.amazonaws.com

(opensource.nextthing.co.s3.amazonaws.com)|54.231.176.13|:80... connected.
HTTP request sent, awaiting response... 200 OK
Length: 54525952 (52M) [binary/octet-stream]

Saving to: /home/doge/gits/CHIP-tools/.firmware/images/rootfs.ubi

100%[======================================>] 54,525,952
2015-10-21 15:59:45 (1.82 MB/s) - /home/doge/gits/CHIP-

1.83MB/s

tools/.firmware/images/rootfs.ubi saved [54525952/54525952]

in 29s

/home/doge/gits/CHIP-tools/.firmware/images/sun5i-r8-chip.dtb exists...
comparing to

http://opensource.nextthing.co.s3.amazonaws.com/chip/buildroot/stable/71/images
/sun5i-r8-chip.dtb

MD5: de0beb674eeb382901251febfbf1cf9b

S3_MD5: de0beb674eeb382901251febfbf1cf9b
file already downloaded

/home/doge/gits/CHIP-tools/.firmware/images/sunxi-spl.bin exists... comparing

to

http://opensource.nextthing.co.s3.amazonaws.com/chip/buildroot/stable/71/images
/sunxi-spl.bin

MD5: dd3f9c9c0984a6c1d7cdca2921f6f448

S3_MD5: dd3f9c9c0984a6c1d7cdca2921f6f448
file already downloaded

/home/doge/gits/CHIP-tools/.firmware/images/uboot-env.bin exists... comparing

to

http://opensource.nextthing.co.s3.amazonaws.com/chip/buildroot/stable/71/images
/uboot-env.bin

MD5: 6f2b79a781f9f490911012ec3aa653e9

S3_MD5: 6f2b79a781f9f490911012ec3aa653e9
file already downloaded

/home/doge/gits/CHIP-tools/.firmware/images/zImage exists... comparing to

http://opensource.nextthing.co.s3.amazonaws.com/chip/buildroot/stable/71/images
/zImage

MD5: 0d35ad764564a2cee9281715823597a2

S3_MD5: 0d35ad764564a2cee9281715823597a2
file already downloaded

/home/doge/gits/CHIP-tools/.firmware/images/u-boot-dtb.bin exists... comparing

to

http://opensource.nextthing.co.s3.amazonaws.com/chip/buildroot/stable/71/images
/u-boot-dtb.bin

MD5: 97340d221bcbcc8f0bf27e26adc26f0a

S3_MD5: 97340d221bcbcc8f0bf27e26adc26f0a
file already downloaded

BUILDROOT_OUTPUT_DIR = /home/doge/gits/CHIP-tools/.firmware
== preparing images ==

/home/doge/gits/CHIP-tools/spl-image-builder -d -r 3 -u 4096 -o 1664 -p 16384 c 1024 -s 64 /home/doge/gits/CHIP-tools/.firmware/images/sunxi-spl.bin

/tmp/chipflashqVYEIs/sunxi-padded-spl
filesize= 3573504

PADDED_SPL_SIZE=0x000000c6

35+1 records in

36+0 records out

589824 bytes (590 kB) copied, 0.00082507 s, 715 MB/s

12+0 records in

12+0 records out

196608 bytes (197 kB) copied, 0.0176519 s, 11.1 MB/s

Image Name:

flash CHIP

Image Type:

ARM Linux Script (uncompressed)

Created:

Data Size:

Wed Oct 21 15:59:46 2015

736 Bytes = 0.72 kB = 0.00 MB

Load Address: 00000000

Entry Point:
Contents:

00000000

Image 0: 728 Bytes = 0.71 kB = 0.00 MB

== upload the SPL to SRAM and execute it ==

waiting for fel...OK
== upload spl ==

== upload u-boot ==

== upload u-boot script ==

== upload ubi ==

100% [============================================================]
== execute the main u-boot binary ==
== write ubi ==

flashing................OK
login... OK

password... OK
poweroff... OK
Debian Output
Sample output from a successful Debian output:
debian selected

ROOTFS_URL=http://opensource.nextthing.co.s3.amazonaws.com/chip/debian/stable/3
7

BUILD=37

BR_URL=http://opensource.nextthing.co/chip/buildroot/stable/71/images
BR_BUILD=71

/home/doge/gits/CHIP-tools/.firmware/images/rootfs.ubi exists... comparing to

http://opensource.nextthing.co.s3.amazonaws.com/chip/debian/stable/37/rootfs.ub
i

MD5: 6d59af4a0f673e1d61147e4a06dd7ba8

S3_MD5: 90315ca1fb8ff95fc6878ce8126bdf02
md5sum differs

--2015-10-21 16:06:36--

http://opensource.nextthing.co.s3.amazonaws.com/chip/debian/stable/37/rootfs.ub
i

Resolving opensource.nextthing.co.s3.amazonaws.com

(opensource.nextthing.co.s3.amazonaws.com)... 54.231.160.10
Connecting to opensource.nextthing.co.s3.amazonaws.com

(opensource.nextthing.co.s3.amazonaws.com)|54.231.160.10|:80... connected.
HTTP request sent, awaiting response... 200 OK
Length: 245366784 (234M) [binary/octet-stream]

Saving to: /home/doge/gits/CHIP-tools/.firmware/images/rootfs.ubi

100%[======================================>] 245,366,784 1.27MB/s

in 2m 11s

2015-10-21 16:08:48 (1.78 MB/s) - /home/doge/gits/CHIP-

tools/.firmware/images/rootfs.ubi saved [245366784/245366784]

/home/doge/gits/CHIP-tools/.firmware/images/sun5i-r8-chip.dtb exists...
comparing to

http://opensource.nextthing.co/chip/buildroot/stable/71/images/sun5i-r8chip.dtb

MD5: de0beb674eeb382901251febfbf1cf9b

S3_MD5: de0beb674eeb382901251febfbf1cf9b
file already downloaded

/home/doge/gits/CHIP-tools/.firmware/images/sunxi-spl.bin exists... comparing

to http://opensource.nextthing.co/chip/buildroot/stable/71/images/sunxi-spl.bin
MD5: dd3f9c9c0984a6c1d7cdca2921f6f448

S3_MD5: dd3f9c9c0984a6c1d7cdca2921f6f448
file already downloaded

/home/doge/gits/CHIP-tools/.firmware/images/uboot-env.bin exists... comparing

to http://opensource.nextthing.co/chip/buildroot/stable/71/images/uboot-env.bin
MD5: 6f2b79a781f9f490911012ec3aa653e9

S3_MD5: 6f2b79a781f9f490911012ec3aa653e9
file already downloaded

/home/doge/gits/CHIP-tools/.firmware/images/zImage exists... comparing to

http://opensource.nextthing.co/chip/buildroot/stable/71/images/zImage
MD5: 0d35ad764564a2cee9281715823597a2

S3_MD5: 0d35ad764564a2cee9281715823597a2
file already downloaded

/home/doge/gits/CHIP-tools/.firmware/images/u-boot-dtb.bin exists... comparing

to http://opensource.nextthing.co/chip/buildroot/stable/71/images/u-bootdtb.bin

MD5: 97340d221bcbcc8f0bf27e26adc26f0a

S3_MD5: 97340d221bcbcc8f0bf27e26adc26f0a
file already downloaded

BUILDROOT_OUTPUT_DIR = /home/doge/gits/CHIP-tools/.firmware
== preparing images ==

/home/doge/gits/CHIP-tools/spl-image-builder -d -r 3 -u 4096 -o 1664 -p 16384 c 1024 -s 64 /home/doge/gits/CHIP-tools/.firmware/images/sunxi-spl.bin

/tmp/chipflashUooSfo/sunxi-padded-spl
filesize= 3573504

PADDED_SPL_SIZE=0x000000c6
35+1 records in

36+0 records out

589824 bytes (590 kB) copied, 0.00181383 s, 325 MB/s

12+0 records in

12+0 records out

196608 bytes (197 kB) copied, 0.0164913 s, 11.9 MB/s

Image Name:

flash CHIP

Image Type:

ARM Linux Script (uncompressed)

Created:

Data Size:

Wed Oct 21 16:08:49 2015

736 Bytes = 0.72 kB = 0.00 MB

Load Address: 00000000

Entry Point:
Contents:

00000000

Image 0: 728 Bytes = 0.71 kB = 0.00 MB

== upload the SPL to SRAM and execute it ==

waiting for fel...OK
== upload spl ==

== upload u-boot ==

== upload u-boot script ==

== upload ubi ==

100% [============================================================]
== execute the main u-boot binary ==
== write ubi ==

flashing...........................OK
login... OK

password... OK
poweroff... OK

Failure
There are a couple common errors that occur when flashing.
The first is a that CHIP is not in fel mode, ready to receive firmware. There are three possible
reasons for this:

You already successfully flashed CHIP, and havent disconnected the USB cable from your

The jumper wire between Pins 7 & 39 is either not present, loose, or the jumper is in the

computer.

wrong holes.

There is a problem with the USB cable.

Youll know this is the problem when you see this error in the terminal window:
== upload the SPL to SRAM and execute it ==
ERROR: Allwinner USB FEL device not found!
== upload images ==

ERROR: Allwinner USB FEL device not found!

ERROR: Allwinner USB FEL device not found!
ERROR: Allwinner USB FEL device not found!
ERROR: Allwinner USB FEL device not found!
== execute the main u-boot binary ==

ERROR: Allwinner USB FEL device not found!

The other common error is that you need to run the chip-update-firmware.sh script with sudo (or
you need to add a rules file as described in the next section). This error looks like this in your
terminal window:

Image 0: 848 Bytes = 0.83 kB = 0.00 MB

== upload the SPL to SRAM and execute it ==

ERROR: You don't have permission to access Allwinner USB FEL device
== upload images ==

ERROR: You don't have permission to access Allwinner USB FEL device
ERROR: You don't have permission to access Allwinner USB FEL device
ERROR: You don't have permission to access Allwinner USB FEL device
ERROR: You don't have permission to access Allwinner USB FEL device
== execute the main u-boot binary ==

ERROR: You don't have permission to access Allwinner USB FEL device
Option: Flash Without sudo

As a developer, theres a good chance youll flash CHIP more than once in your life. Youll

probably want to follow these steps. In order to be able to run the chip-update-firmware.sh script
without sudo, make a rules file:

sudo touch /etc/udev/rules.d/99-allwinner.rules

and add the content with the tee command:

echo 'SUBSYSTEM=="usb", ATTRS{idVendor}=="1f3a", ATTRS{idProduct}=="efe8",

GROUP="plugdev", MODE="0660" SYMLINK+="usb-chip"' | sudo tee
/etc/udev/rules.d/99-allwinner.rules

then, to make this rules file work: shell sudo udevadm control --reload-rules

Setup Ubuntu For Flashing

If you are running Ubuntu OS on your computer, and dont want to bother with a virtual machine,
you can flash CHIP from your real computer. A generous member of our forums created a script

that duplicates the below steps in a convenient package. You can get it from github. Please note
that this is not supported or maintained by Next Thing - we only link to it here for your potential
convenience.

Requirements

Computer running Ubuntu 14.04+

CHIP

Jumper wire

Install Dependencies
Install some tools:

sudo apt-get update

sudo apt-get install u-boot-tools android-tools-fastboot git build-essential

curl android-tools-fsutils libusb-1.0-0-dev pkg-config

If you get an error that the repository android-tools-fastboot cant be found, you are probably

booting from an Ubuntu Live CD (or USB stick). Youll need to add a repository so you can install
the android-tools-fastboot:

sudo add-apt-repository universe && sudo apt-get update

sudo apt-get install u-boot-tools android-tools-fastboot git build-essential

curl android-tools-fsutils libusb-1.0-0-dev pkg-config

If you intend to customize buildroot with additional software, install these packages:
sudo apt-get install libncurses5-dev libc6-i386 lib32stdc++6 lib32z1

Get and make the fel tools:

git clone http://github.com/NextThingCo/sunxi-tools
cd sunxi-tools
make

sudo rm -f /usr/local/bin/fel

sudo ln -s $PWD/fel /usr/local/bin/fel

Clone the CHIP-tools repository
cd ..

git clone http://github.com/NextThingCo/CHIP-tools

cd CHIP-tools

If you have already cloned the CHIP-tools from a previous CHIP flashing, you can, of course, just
update your existing repository
cd CHIP-tools

git pull http://github.com/NextThingCo/CHIP-tools

Youll also need to add your user to some groups and add a udev rule shell sudo usermod -a
-G dialout $(logname) && sudo usermod -a -G plugdev $(logname) &&

'SUBSYSTEM=="usb", ATTRS{idVendor}=="1f3a", ATTRS{idProduct}=="efe8",

GROUP="plugdev", MODE="0660" SYMLINK+="usb-chip" SUBSYSTEM=="usb",

ATTRS{idVendor}=="18d1", ATTRS{idProduct}=="1010", GROUP="plugdev", MODE="0660"

SYMLINK+="usb-chip-fastboot" SUBSYSTEM=="usb", ATTRS{idVendor}=="1f3a",

ATTRS{idProduct}=="1010", GROUP="plugdev", MODE="0660" SYMLINK+="usb-chip-

fastboot" SUBSYSTEM=="usb", ATTRS{idVendor}=="067b", ATTRS{idProduct}=="2303",

GROUP="plugdev", MODE="0660" SYMLINK+="usb-serial-adapter"' | sudo tee

/etc/udev/rules.d/99-allwinner.rules && sudo udevadm control --reload-rules

Now you are ready to flash CHIP with firmware.
All The Commands At Once
Heres all the commands in one place:
sudo apt-get update

sudo apt-get install u-boot-tools android-tools-fastboot git build-essential

libusb-1.0-0-dev libncurses5-dev libc6-i386 lib32stdc++6 lib32z1 android-toolsfsutils

git clone http://github.com/NextThingCo/sunxi-tools

cd sunxi-tools
make

sudo rm -f /usr/local/bin/fel

sudo ln -s $PWD/fel /usr/local/bin/fel

cd ..

git clone http://github.com/NextThingCo/CHIP-tools

cd CHIP-tools

WiFi Connection

Below are detailed instructions for connecting to Wi-Fi networks using two different command line

protocols: nmcli and connman. If you are using the CHIP OS that comes installed on CHIP, or you
have flashed with our Debian distribution, youll want to use the first section about connecting
with nmcli. If you have flashed CHIP with our buildroot OS, youll need to use connman.

Connecting C.H.I.P. to Wi-Fi with nmcli

There are several tools in Linux for connecting and configuring networks. We will be using the
command nmcli (Network Manager Client). You may see other tutorials that reference iw or

iwconfig, however, these tools are not recommended for C.H.I.P. You can read more about nmcli
on the internet.

Requirements
You will need one of these scenarios:

CHIP with monitor and keyboard attached

Wireless access to internet

SSH or serial connection

CHIP loaded with CHIP OS or Debian

Step 1: List available Wi-Fi networks

In the terminal, type
nmcli device wifi list

The output will list available access points

*
*

SSID

MODE

CHAN

RATE

SIGNAL

BARS

SECURITY

11

54 Mbit/s

100

--

Infra

54 Mbit/s

30

___

WPA1 WPA2

Infra

10

54 Mbit/s

44

__

WPA1 WPA2

NextThing HQ

Infra

NextThing Shop
2WIRE533

Step 2: Connect to a network

You can connect to password -protected or open access points.

A: No Password
To connect to an open network with no password, use this command:
sudo nmcli device wifi connect '(your wifi network name/SSID)' ifname wlan0
These commands will respond with information about the connection.
B: Password Protected
To connect to a password protected network, use this command, inserting your own network name
and password:

sudo nmcli device wifi connect '(your wifi network name/SSID)' password '(your
wifi password)' ifname wlan0

C: Hidden SSID and Password Protected

To connect to a hidden, WPA2-password protected network, use these set of commands, inserting
your own network name and password:

sudo nmcli con add con-name 'mywifi' ifname wlan0 type wifi ssid '(your wifi
network name/SSID)'

sudo nmcli con modify 'mywifi' wifi-sec.key-mgmt wpa-psk

sudo nmcli con modify 'mywifi' wifi-sec.psk '(your wifi password)'

sudo nmcli con up id 'mywifi'
Step 3: Test your Connection
You can verify and test your wireless network connection.
Verify
You can verify your connection using the command
nmcli device status

which outputs a list of the various network devices and their connections. For example, a
successful connection would look like this:
DEVICE

TYPE

STATE

CONNECTION

wlan1

wifi

disconnected

--

wlan0

ip6tnl0
lo

sit0

wifi
ip6tnl

loopback
sit

connected
unmanaged
unmanaged
unmanaged

NextThing HQ
----

Because it is worth knowing that Linux offers many ways of doing things, another command that
shows your current active connection is
nmcli connection show --active
which outputs like so:
NAME
NTC

UUID

59962bac-3441-437b-94ea-bf31dee66e8f

TYPE

802-11-wireless

DEVICE
wlan0

After you have connected once, your C.H.I.P. will automatically connect to this network next time
you reboot (or start NetworkManager services).
Test
Finally, you can test your connection to the internet with ping. Googles DNS server at the IP
address 8.8.8.8 is probably the most reliable computer on the internet, so:
ping -c 4 8.8.8.8
results in output like:

64 bytes from 8.8.8.8: icmp_seq=1 ttl=55 time=297 ms

64 bytes from 8.8.8.8: icmp_seq=2 ttl=55 time=26.3 ms

64 bytes from 8.8.8.8: icmp_seq=3 ttl=55 time=24.8 ms
64 bytes from 8.8.8.8: icmp_seq=4 ttl=55 time=55.7 ms

You can stop this command by pressing CTRL-C on your keyboard. The -c 4 option means it will
happen only 4 times.

Congratulations! You are now network with CHIP!

Step 4: Disconnecting and Forgetting Networks
The command to disconnect from a wireless device needs a few parameters:
sudo nmcli dev disconnect wlan0

You may want to prevent auto-connection to a network, so you can use this command to forget a
network:

sudo nmcli connection delete id

(your wifi network name/SSID)

Troubleshooting
Here are a few possible problems with connections.
No network found
Not much to say about that. If theres no network, you cant connect. Go find a network!

Incorrect password
If you type in the wrong password, youll get some errors like this:
[32258.690000] RTL871X: rtw_set_802_11_connect(wlan0) fw_state=0x00000008
[32258.800000] RTL871X: start auth

[32263.720000] RTL871X: rtw_set_802_11_connect(wlan0) fw_state=0x00000008

[32263.820000] RTL871X: start auth

[32264.430000] RTL871X: auth success, start assoc

[32269.850000] RTL871X: rtw_set_802_11_connect(wlan0) fw_state=0x00000008

[32269.970000] RTL871X: start auth
Error: Timeout 90 sec expired.

Try connecting again with the correct password.

Failed ping
If you dont have access to the internet, your ping to an outside IP will fail. It is possible that you

can connect to a wireless network, but have no access to the internet, so youd see a connection

when you request device status, but have a failed ping. This indicates a problem or restriction with
the router or the access point, not a problem with the CHIP.
A failed ping looks something like:
From 192.168.2.56 icmp_seq=14 Destination Host Unreachable
From 192.168.2.56 icmp_seq=15 Destination Host Unreachable
From 192.168.2.56 icmp_seq=16 Destination Host Unreachable

18 packets transmitted, 0 received, +9 errors, 100% packet loss, time 17013ms

pipe 4

Loss of wireless network

A sudden, unplanned disconnection will post an error in the terminal window, for example:
[30863.880000] RTL871X: linked_status_chk(wlan0) disconnect or roaming

The Network Manager will periodically try to reconnect. If the access point is restored, youll get
something like this in your terminal window:

[31798.970000] RTL871X: rtw_set_802_11_connect(wlan0)

[31799.030000] RTL871X: start auth

[31799.040000] RTL871X: auth success, start assoc

[31799.050000] RTL871X: rtw_cfg80211_indicate_connect(wlan0) BSS not found !!

[31799.060000] RTL871X: assoc success
nmcli not installed error

If you try to use nmcli and you get an error that it is not found or is not a command, chances are
that you are using the CHIP buildroot image. The nmcli commands only apply to CHIPs running
CHIP OS or Debian linux.

Connecting C.H.I.P. to a Wireless Network With connman

The buildroot operating system uses the connman command-line network manager to connect and
manage your network connections. If you are using CHIP OS (or Debian), you will find
that connman is not installed - youll need to use nmcli.

If you want all the details of connman visit the ArchLinux wiki.
Requirements

CHIP running buildroot OS

One of the following:
o
o

Keyboard and monitor for CHIP

Serial connection to CHIP

Step 1: Enable WiFi and Find a Network

These three commands will, in turn, enable wifi, scan for access points, and see what networks are
available:

connmanctl enable wifi

connmanctl scan wifi
connmanctl services

The services command has output similar to:

*AO

NTC

wifi_7cc70905cd77_4e5443_managed_psk

NTC Guest

wifi_7cc70905cd77_4e5443204775657374_managed_psk

ATT312

wifi_7cc70905cd77_hidden_managed_psk

wifi_7cc70905cd77_hidden_managed_none

wifi_7cc70905cd77_415454333132_managed_psk

HP-Print-99-LaserJet 1102

wifi_7cc70905cd77_48502d5072696e742d39392d4c617365724a65742031313032_managed_no
ne

ATT344

CBCI-1B57-2.4

wifi_7cc70905cd77_415454333434_managed_psk

wifi_7cc70905cd77_434243492d314235372d322e34_managed_psk
mi-fi

0024A5D8CF33

wifi_7cc70905cd77_6d692d6669_managed_none

wifi_7cc70905cd77_303032344135443843463333_managed_psk

Twirl-Eco-Events-2.4

wifi_7cc70905cd77_547769726c2d45636f2d4576656e74732d322e34_managed_psk
xfinitywifi

wifi_7cc70905cd77_7866696e69747977696669_managed_none

Step 2: Connect To An Access Point

Unfortunately, connman doesnt use the nice name on the left of the services list. It wants the
unfriendly string on the right, so youll want to get copy and paste ready.
A: No Password
For example, to connect to NTC Guest, which has no password, services shows two choices. We
want the one without hidden in the string. Use the connect command to connect:

connmanctl connect wifi_7cc70905cd77_4e5443204775657374_managed_psk

If your network is not password protected, youll get some output that will indicate a successful
connection, such as:
[

961.780000] RTL871X: rtw_set_802_11_connect(wlan0)

962.080000] RTL871X: auth success, start assoc

[
[
[
[
[
[

962.070000] RTL871X: start auth

fw_state=0x00000008

962.090000] RTL871X: rtw_cfg80211_indicate_connect(wlan0) BSS not found !!

962.100000] RTL871X: assoc success

962.110000] RTL871X: send eapol packet

962.290000] RTL871X: send eapol packet

962.300000] RTL871X: set pairwise key camid:4, addr:0a:18:d6:97:2d:26,

kid:0, type:AES
[

962.320000] RTL871X: set group key camid:5, addr:0a:18:d6:97:2d:26, kid:1,

type:AES

If your network is password protected, youll get an error.

B: Password-Protected
To deal with passwords, youll need to put connman into interactive mode:
connmanctl

which gives a connmanctl prompt:

connmanctl>

In the shell, turn the 'agent on so it can process password requests:

agent on

and now use the connect command (your network name will be different than whats below of
course)

connect wifi_7cc70905cd77_4e5443_managed_psk

and enter your password when prompted:

Agent RequestInput wifi_7cc70905cd77_4e5443_managed_psk

Passphrase = [ Type=psk, Requirement=mandatory ]
Passphrase?

Now that you are connected to a wireless network, you can exit connmanctl interactive mode by
typing

quit
All The Commands In One Place
Heres all the commands in one place:
connmanctl
agent on

connect wifi_7cc70905cd77_4e5443_managed_psk
quit

Step 3: Test Connection

In CHIPs command line, you can ping Google four times:
ping -c 4 8.8.8.8

and expect ping to output some timing messages like:

PING 8.8.8.8 (8.8.8.8): 56 data bytes

64 bytes from 8.8.8.8: seq=0 ttl=55 time=209.147 ms

64 bytes from 8.8.8.8: seq=1 ttl=55 time=111.125 ms
64 bytes from 8.8.8.8: seq=2 ttl=55 time=183.627 ms
64 bytes from 8.8.8.8: seq=3 ttl=55 time=147.398 ms
--- 8.8.8.8 ping statistics ---

4 packets transmitted, 4 packets received, 0% packet loss

round-trip min/avg/max = 111.125/162.824/209.147 ms

If your connection is not successful, then ping will tell you your network is down:
PING 8.8.8.8 (8.8.8.8): 56 data bytes
ping: sendto: Network is unreachable
Troubleshooting Connection Problems

Youll need to make sure you used the right network when you used the connect
commnand.

Review any messages that the connect commnand gave you. Did they look like the

If everything checked out until you got to ping, theres a good chance the problem is with

examples of a successful connection?

your router or connection to the internet.

connman not installed error

If you try to use connman and you get an error that it is not found or is not a command, chances
are that you are using the CHIP OS or Debian image. The connman commands only apply to
CHIPs running the simple buildroot OS.

Step 4: Disconnecting And Forgetting Networks

To disconnect from your network, you might first want a reminder of what unfriendly string is used
to describe your access point, so type:
connmanctl services

which will output information about your current link:

*AO NTC

Use the ID to disconnect:

wifi_7cc70905cd77_4e5443_managed_psk

connmanctl disconnect wifi_7cc70905cd77_4e5443_managed_psk

and youll get some status like this:

[

301.890000] RTL871X: clear key for addr:0a:18:d6:97:2d:26, camid:4

301.920000] IPv6: ADDRCONF(NETDEV_UP): wlan0: link is not ready

301.900000] RTL871X: clear key for addr:0a:18:d6:97:2d:26, camid:5

Disconnected wifi_7cc70905cd77_4e5443_managed_psk

Generally, conman will remember and cache setup information - if you reboot in the vicinity of a

known network, it will attempt to connect. However, if you need to forget a network setup, these
setups can be found by navigating:
cd /var/lib/connman/

You can delete a single connection by seeing what connections are stored
ls /var/lib/connman/

and then delete a setup that you find, for example

rm -r wifi_7cc70905cd77_4e5443_managed_psk

You can delete all the wifi directories with

rm -r wifi*

(the -r is needed because these are directories you are deleting, and the star at the end
of wifi* assumes your configurations all start with the string wifi)
For Advanced Users
Its worth noting that youll see two wireless networking interfaces if you list them with
ifconfig

connman is configured to see only the physical interface wlan0 which simplifies setup. We do this
with a blacklist, which can be modified at /etc/connman/main.conf

Configure Sound Output on Debian

Getting simple audio playback working on CHIP is pretty easy, once you install the correct

packages and enable audio output. In the code examples below, weve inserted the && characters
at the end of lines so you can copy and paste the entire block into a terminal window and execute
each line in series. If you are using CHIP OS, sound output is already configured and working.

However, you may be running a simple version of Debian or buildroot, so these instructions will
help you get sound working on CHIP.

Requirements

CHIP

Monitor and keyboard

SSH or serial connection to CHIP or

Headphones or powered speakers connected to CHIP a/v jack
Connection to a network

Setup CHIP

Update your apt repository list if you havent done so recently:

sudo apt-get update

Then install ALSA:

sudo apt-get install libasound2 alsa-utils

This will install alsa and some utilities for playing sound from the command line. Once those have
installed, youll need to make the outputs active for sound
alsamixer

will open up a simple interface. Use the left and right arrow keys on your keyboard to select among
the items, and use the up/down keys to change the options:

DAC Output - set to Direct

PA - set to desired volume

Left Mixer - set to Left

Right Mixer - set to Right

Play a Sound

Change to the root media directory:

cd /media

Alternatively, you could download a sound into chips home directory:

mkdir /home/chip/Media && cd /home/chip/Media

Use wget to download a sound of piano chords to the file test.wav:

wget -O test.wav

https://upload.wikimedia.org/wikipedia/commons/d/db/Descending_thirds.wav
If wget returns command not found you can install it:
sudo apt-get install wget

We can finally play the sound and hear it over CHIPs headphone jack:
aplay test.wav

If you want to play mp3 or ogg files, you can install mplayer:
sudo apt-get install mplayer

Then try an ogg file:

wget -O test.ogg

https://upload.wikimedia.org/wikipedia/commons/e/e7/Agogo.ogg &&
mplayer test.ogg

And mp3 file:

wget -O test.mp3 http://www.freesound.org/data/previews/315/315618_2050105-

lq.mp3 &&

mplayer test.mp3

Record A Sound

If you want to try the audio input, you need to connect audio input to header U14, pins 06 &

12 or modify CHIP to use audio in on the TRRS connector. Once you have an audio signal going
into CHIP, you can test it out by recording a three second (-d 3) WAV file with arecord:
arecord -f cd -d 3 -D hw:0,0 chipaudioin.wav

More Packages

Developers that want to use sound will probably want to download these packages:
sudo apt-get install portaudio19-dev &&
sudo apt-get install swig &&

sudo apt-get install python-setup-tools &&

sudo apt-get install python-dev

USB Storage Devices

In this tutorial, well describe how you can use the USB port to add more storage with a thumb

drive, hard drive, card reader, or whatever else. You can then copy, store, and edit files on the
storage device, extending the capability of CHIP.

This tutorial is suitable for the buildroot image. If you are following this for other Linux distributions,
there are some adjustments that youll need to make for paths, permissions, and enabling 'sudo.
With buildroot, you work as the root user, so this tutorial is appropriately terse.

Requirements

USB thumb drive or hard drive

Computer running OS X 10.10+, Ubuntu 14.04+, or Windows 7+ (to format USB device, if
needed)

Step 1: Format the Drive

First, youll want to format the drive as an MS-DOS (FAT), NTFS, or ext3 volume. You can do this
on another computer.

Once formatted, insert the drive into CHIPs USB port. Enter the command
dmesg

Youll get output like:

[ 4953.430000] usb 1-1: new high-speed USB device number 2 using ehci-platform
[ 4953.580000] usb-storage 1-1:1.0: USB Mass Storage device detected
[ 4953.590000] scsi host0: usb-storage 1-1:1.0

[ 4954.590000] scsi 0:0:0:0: Direct-Access USB Flash Memory 1.00 PQ: 0 ANSI: 2

[ 4954.600000] sd 0:0:0:0: [sda] 3911616 512-byte logical blocks: (2.00 GB/1.86

GiB)

[ 4954.610000] sd 0:0:0:0: [sda] Write Protect is off

[ 4954.620000] sd 0:0:0:0: [sda] Mode Sense: 65 44 09 30

[ 4954.630000] sd 0:0:0:0: [sda] No Caching mode page found

[ 4954.630000] sd 0:0:0:0: [sda] Assuming drive cache: write through

[ 4954.650000] sda: sda1

[ 4954.650000] sd 0:0:0:0: [sda] Attached SCSI removable disk

Notice the second to last line. This tells you the device location for the drive. Storage devices
generally have device names that start with sd. If you want to see all the storage devices
attached to CHIP, you can use a wildcard to display all devices that start with sd:
ls /dev/sd*

and youll get something like:

/dev/sda /dev/sda1

With one thumb drive attached, it appears as two devices: the device itself (sda), and the storage
partitions (sda1). There is only one partition on this drive.
Another way to find storage devices is the command
blkid

which lists them, along with the names you might have initialized them with:
/dev/sda1: LABEL="TEST" UUID="6668-11E9"

Step 2: Mount the Drive Device to Your Filesystem

Now that you know where your partition is, its time to mount the partition so you can access the
files.

First, make a directory where your drive can mount:

sudo mkdir /drives

Mount the drive device to your /drives directory:

sudo mount /dev/sda1 /drives

Now you can navigate to the drives directory and see all the files in the drive:
cd /drives
ls

Step 3: Unmount the Drive From Filesystem

If you want to remove the drive from the USB port on CHIP, its best to unmount it:
sudo umount /dev/sda1

Step 4: Automatic Mounting on Boot

Youll probably want to mount this drive automatically next time you use it, though. We can set that
up with a quick modification to the fstab (file system table) document:
vi /etc/fstab

Getting around vi is not very intuitive. If you are new to it, heres a quick guide on getting this text
into the fstab document:

'arrow key to the end of the file,

type (or copy-paste) this:

press the 'i key to insert text

/dev/sda1 /drives vfat defaults 0 0

To exit vi,

press the 'esc key,

type 'wq to write and quit vi.

type : (colon),

You can test your work with:

mount -a

If theres an error, double check the fstab file and make sure it has the line /dev/sda1 /drives
vfat defaults 0 0 at the end. If its successful, youll be able to view, modify and copy the files
on the disk:

ls /drives

Now, if you reboot , the drive will mount automatically. If you remove the drive, then insert it again,
youll need the command

mount -a

Connecting Bluetooth Devices

CHIP has built-in Bluetooth and uses the bluez 5 stack for implementing connections and devices.
This tutorial instructs how to use a Bluetooth keyboard, since it is a simple and obvious example.
There are, of course, several types of Bluetooth devices, such as earpieces, audio connectors,
vacuum cleaners, and more. Future tutorials (search our bbs will cover those devices, but the
keyboard is a good introduction to the commands and an easy way to test your system.

Requirements

CHIP

Monitor and keyboard

SSH or serial connection to CHIP or

Bluetooth device, preferably keyboard

Important!

Start with a CHIP completely unplugged and powered down. Add power and boot up. A known
limitation is that after reboot, CHIPs Bluetooth controller may not work until you power and
physically disconnect from a power source.

About bluetoothctl

Well be using the command bluetoothctl to find, pair with, and connect to devices.
In the terminal, type
bluetoothctl

This starts up bluetoothctl in interactive mode. You should see output like
[NEW] Controller 7C:C7:08:05:CD:77 BlueZ 5.27 [default]
[NEW] Device 60:33:4B:13:A7:45 nyb

[NEW] Device 15:03:26:A0:26:26 SK032B02-2626

which is a list of MAC addresses of CHIPs Bluetooth controller chip (the first line) and any other

devices that have been paired with CHIP in the past. Use the help command - it lists all the very
useful commands in the bluetoothctl interactive mode.
In Bluetooth interactive mode, use the command
power on

which outputs

Changing power on succeeded

[CHG] Controller 7C:C7:08:05:CD:77 Powered: yes

Find A Bluetooth Device

If you need to discover a device, start the scan process:

scan on

which will start printing MAC addresses and names (if available) of Bluetooth devices in your
vicinity.

[NEW] Device 15:03:26:A0:26:26 SK032B02-2626

[NEW] Device 1C:1A:C0:85:5E:2C 1C-1A-C0-85-5E-2C

[NEW] Device 60:33:4B:13:A7:45 nyb

Pair With A Bluetooth Device

Pair to a device with the MAC address and the pair command:
pair 1C:1A:C0:85:5E:2C

This may fail if the device is powered off, goes out of range, or your toddler spills water on it.
Heres what failure looks like:

Attempting to pair with 1C:1A:C0:85:5E:2C

[CHG] Device 1C:1A:C0:85:5E:2C Connected: yes

[CHG] Device 1C:1A:C0:85:5E:2C Connected: no

Failed to pair: org.bluez.Error.AuthenticationCanceled

As the scan continues, youll eventually see the device you are interested in, so copy that MAC
address and type:

pair 15:03:26:A0:26:26

with output like:

[CHG] Device 15:03:26:A0:26:26 Connected: yes

[CHG] Device 15:03:26:A0:26:26 Modalias: usb:v05ACp3232d0001

[CHG] Device 15:03:26:A0:26:26 UUIDs:
00001124-0000-1000-8000-00805f9b34fb
00001200-0000-1000-8000-00805f9b34fb

[CHG] Device 15:03:26:A0:26:26 Paired: yes

Pairing successful

[CHG] Device 15:03:26:A0:26:26 Connected: no

Pair with a Bluetooth Device with Password (keyboard)

Some Bluetooth devices need user input to pair. In that case, youll need to turn the agent 'on so
the device can post a password, and you can enter it:

agent on

will output

Agent registered

now you can pair it:

pair DC:2C:26:D7:B6:8F

will output

Attempting to pair with DC:2C:26:D7:B6:8F

[CHG] Device DC:2C:26:D7:B6:8F Connected: yes

[agent] PIN code: 245261

Now you can use the Bluetooth device to enter the PIN code, then hit enter. The terminal will give
some status about the pairing:

[CHG] Device DC:2C:26:D7:B6:8F Modalias: usb:v05ACp022Cd011B

[CHG] Device DC:2C:26:D7:B6:8F UUIDs:

00001000-0000-1000-8000-00805f9b34fb
00001124-0000-1000-8000-00805f9b34fb
00001200-0000-1000-8000-00805f9b34fb

[CHG] Device DC:2C:26:D7:B6:8F Paired: yes

Pairing successful

[CHG] Device DC:2C:26:D7:B6:8F Connected: no

Now that you are paired, you will have to connect.

Connect With A Bluetooth Device

Now that you have paired the Bluetooth device, you wont have to do that again. However, the
device still needs to be connected:
connect 15:03:26:A0:26:26

will output, when successful:

Attempting to connect to 15:03:26:A0:26:26

[CHG] Device 15:03:26:A0:26:26 Connected: yes

Connection successful

[bluetooth]## [ 1405.340000] hid-generic 0005:05AC:3232.0001: unknown main item

tag 0x0

[ 1405.360000] input: SK032B02-2626 as

/devices/platform/soc@01c00000/1c28c00.serial/tty/ttyS1/hci0/hci0:4/0005:05AC:3
232.0001/input/input1

[ 1405.380000] hid-generic 0005:05AC:3232.0001: input: BLUETOOTH HID v0.01

Mouse [SK032B02-2626] on 7c:c7:08:05:cd:77

or, if the device is not available, it will fail:

Attempting to connect to 15:03:26:A0:26:26

[bluetooth]## [ 1304.470000] Bluetooth: HIDP (Human Interface Emulation) ver

1.2

[ 1304.480000] Bluetooth: HIDP socket layer initialized

Failed to connect: org.bluez.Error.Failed

Trusting a Bluetooth Device

Trust between people leads to understanding and perhaps even harmonious living. Trust between

bluetooth devices means that you wont have to connect the device every time its near. Which is a
sort of harmony, I suppose. Once you have connected a bluetooth device to CHIP, if you intend to
use it again, you can trust it:

trust 15:03:26:A0:26:26

Remove a Bluetooth device

You may want CHIP to not pair or connect to a device - perhaps the conveniently trusted device
needs to be freed for another connection. Whatever the reason, if you want to remove your
Bluetooth device,

remove 15:03:26:A0:26:26

Troubleshooting

If your Bluetooth controller module on CHIP is not functioning, you can easily find the problem.
Type

bluetoothctl

to get into the interactive mode, then type

power on

If you get the response

No default controller available

Then theres a problem with CHIP recognizing the Bluetooth module. Read the very first
instructions at the top of this tutorial.

Install X-windows

If you want a windowed desktop on C.H.I.P., you can install X-Windows.

Requirements

CHIP connected to WiFi

Keyboard or Serial or SSH Connection to CHIP

Monitor attached to CHIP

Installation (xfce4)

CHIP is a lightweight computer, so well install the lightweight xfce4:

sudo apt-get install xfce4

It might take some time to download and install all the packages, since there are a lot of

dependencies and libraries involved. Once installed, start the windowing system with the command
startx&

(the & runs Xwindows in the background, so you can still use your terminal). After a minute or so,
youll get an image on the monitor:

Now you can use a mouse and keyboard to explore CHIP and launch programs.

Troubleshooting

If you get errors from apt that report unmet dependencies, you can run the command
sudo apt-get install -f

which will force installation of any alternate or missing dependencies of any installed packages.

Building and Installing PureData (PD) on CHIP

PureData is a graphical programming environment, primarily for making audio and multimedia
applications. This tutorial describes how to build the vanilla version of PD. This is a very

rudimentary version of PD - it does not compile or build the extras objects, such as bob~ or
expr~.

Get Source

First, download and un-archive the source from Miller Puckettes website:
wget http://msp.ucsd.edu/Software/pd-0.46-7.src.tar.gz
gzip -d pd-0.46-7.src.tar.gz
tar -xvf pd-0.46-7.src.tar

Install Dependencies

Now, youll need to install all the dependencies and make a symbolic link to wish:
sudo apt-get update

sudo apt-get install libasound2 alsa-utils mplayer software-properties-common

git autoconf libtool make

build-essential gettext portaudio19-dev

libasound-dev qjackctl jackd2 tcl8.6 tk8.6 unzip

jack

sudo apt-get build-dep puredata

sudo ln -s /usr/bin/wish8.6 /usr/bin/wish

Navigate to the pd directory the archive created:
cd pd-0.46-7

Build It

Youre ready to go ahead and build, running some scripts, then making the install:
cd ~/pd-0.46-7/
./autogen.sh

./configure --disable-portaudio --disable-portmidi --no-recursion

make

sudo make install

Youll probably also want the extra objects such as expr, expr~, clone, fiddle~, bonk~, bob~,

sigmund~, et al. These require an extra build step. The extra folder is in pd-0.46-7/extra, so if
you are still insrc/ you can

cd ../extra

make install

Youll probably also want to install the deken plugin so you can add more externals to your bag of
tricks: https://github.com/pure-data/deken

Ive also found this kiosk plugin to be very handy for making a pure data widow take up the entire
screen: https://puredata.info/downloads/kiosk-plugin

Set Up Priority

Now set up pd so it can run in real-time priority mode for low latency (launching with pd -rt). This
is mostly about giving audio the necessary thread priority and giving the chip user access:
sudo nano /etc/security/limits.conf

Navigate to the end of the file (CTL-V) and add the lines
@audio - rtprio 99

@audio - memlock unlimited

and save (CTL-X to exit, youll be prompted to save) Youll want to double check that
the chip user is in the audio group:
sudo adduser username audio
Then reboot CHIP:
sudo reboot

Test PD

Now test pd with a test patch. Open a terminal and use this command, which should result in a
sine wave:

wget http://log.liminastudio.com/wp-content/uploads/2012/06/testPatch.pd_.zip
unzip testPatch.pd_.zip

pd -rt -nogui -noadc -alsa testPatch.pd

Test MIDI Controller

If you need to test out a midi controller to make sure data is coming into CHIP, you can do this

from the terminal. Youll want to list the connected devices, if not just to get the port name as ALSA
sees it.

amidi -l

Example output might look like shell Dir Device Name IO hw:1,0,0 DS1 MIDI 1
You can then use the command to display MIDI data bytes (in hex) in the terminal window:

amidi -p hw:1,0,0 -d

Moving a fader might provide output like:

B0 29 1D
B0 29 20
B0 29 24
B0 29 29
B0 29 2E
B0 29 32
B0 29 37
B0 29 3A
B0 29 3C

Uninstall

If you need to remove pd, it takes a few steps:

sudo apt-get remove puredata-core

sudo apt-get remove puredata-dev puredata-import puredata-utils

sudo apt-get purge puredata-core

sudo apt-get install aptitude wget unzip

sudo apt-get autoremove

Run PD

Start PD from the terminal with the command

pd -rt &

You can then use the mouse and keyboard to go through the Browser and learn more about PD.

References

Here are some reference links

real time priority mode

pure data on sourceforge

low latency alsa

pd extended on RPi

Headless CHIP

One of the most amazing features of CHIP is that its insanely simple to use it as small, wireless

computer. Low power requirements, battery powered with charge management, and both WiFi and

Bluetooth connectivity makes CHIP easy to run as a headless, autonomous machine. Of course,

youll still want to access it and control it without a monitor or keyboard. You can control CHIP with
another computer and a serial or network connection. Heres how you do this.

Begin

If you want to use CHIP without a monitor or keyboard attached, theres a few ways to do this:

Serial connection with USB to UART cable

Secure Shell (SSH) over wireless or wired ethernet

Serial connection with USB cable

Requirements

Computer running OS X 10.10+, Ubuntu 14.04+, or Windows 7+

Monitor and keyboard (somewhat optional, though handy)

CHIP

Connection to the network

SSH

SSH (or Secure Shell) is a common way to control a computer remotely over a network. Youll
need to first get your computers network name or IP address before you can connect.
How to get your IP address.
The easiest way to get CHIPs IP address is to hook up a monitor and keyboard. Bootup, log
in, connect to the network if you need to, and use the command
hostname -i

which results in your IP address, which might look like this:

10.1.1.99

If the hostname -i command doesnt work you can use

ip addr show dev wlan0

which will output a lot of data. Look for the line wlan0 and the entry inet, something like:
inet 10.1.1.99
Connect to CHIP over a network
Now that you know your IP address, use the command:
ssh [email protected]

Youll be asked for CHIPs password. The default password is chip. This process is the same if
CHIP is connected to the network using built-in wireless or a USB-Ethernet adapter.
Make Connections To CHIP Easy
You may want to setup your network so it will always provide the same (static) IP address to CHIP.
You can then rely on CHIP always having the same IP address.

Alternatively, you can setup zero configuration networking to give your CHIP an easily
remembered name.

You are now free to do whatever it is you do with Linux command line on CHIP.

USB to UART Serial Connection

There are a few reasons youd want to use a serial connection:

No wireless network

Dont know the IP or network name of CHIP

No USB-ethernet cable

Youre old-school and like it

Connect a USB to UART cable to the Ground (GND), Transmit (TX), and Recieve (RX) pins on
CHIP

Well find those on header U14, pin outs 1,3 and 5. See the following diagram, which assumes
CHIPs USB ports are pointed up

About the Cable

If you need a connector, search your favorite shop for USB to UART cable - any will do.
Heres the one we bought. Most of them will have a USB A plug for your computer on one end and
four wires (red, green, black, and white) with female header pins on the other.

You may find other USB-UART cables that have more wires. There will be some labels that will

help you connect to the correct pins (GND, TX, RX) on terminal U14. Just be sure to check your
datasheets to make sure youre using the correct pins.
Install the driver
For this tutorial, we are using a PL2303 USB to Serial cable. If you are using this one too, youll
probably need to install the PL2303 driver for your computer.
Connect the Cable
You only need to worry about three of the wires:

Black = Ground (GND)

White = Transmit (TX)

Green = Receive (RX)

The red wire carries voltage (+5 V). DO NOT USE THE RED ONE. Plugging in a +5 V pin could
damage your CHIP

Again, there is a chance your USB to UART cable may be different. Please check your data
sheets!

This is what our cable looks like plugged in:

USB On The Go Serial Connection

Simpler than the UART cable, you can connect to CHIP with a USB cable to your computer. Your

computer will see CHIP as a serial device as well as provide power to the CHIP. Either way, youll
be able to continue with the directions below.

Control CHIP Using a Serial Terminal

Once youve connected CHIP to your computer with the UART or USB cable, open up a terminal.
Theres lots out there. Heres a few:

OS X: Zterm, screen (built-in to OS X terminal)

Linux: screen, cu

Windows: PuTTy or cygwin

No matter the software, youll need to set some settings for the port (aka connection). Youll
probably only need to set the baud rate, as the others will be defaults:

Baud Rate (Data Rate): 115200

Parity: none

Data Bits: 8
Stop bits: 1

Flow control: none

Using screen
If you are using screen, the command will look something like this:
screen /dev/tty.usbserial 115200
or

screen /dev/ttyUSB0 115200

What comes after the /dev/ may vary among different systems and connections. You can narrow
down the choices by using the command
ls /dev/tty*

to list the serial devices.

Now power up CHIP. You could do this at anytime, but youll have the most reliable experience
powering CHIP after connecting the USB-UART wires. If you make the serial connection after

booting chip, youll probably need to hit 'return on your keyboard a few times to get CHIP to send
some data to you and print in your terminal.

Youll then be prompted for login. Defaults are username root and password chip.
You are now free to do whatever it is you do with Linux command line on CHIP.
Using PuTTy
If you are on Windows using PuTTy, youll probably want to open the windows Device Manager to
get the COM name for the serial port. The device wont show up in the Ports list until after the
kernel loads and presents the device, so it may take a minute or so before Windows actually
detects it.

In the PuTTy configuration panel, you can now use the COM name to set it up. In this case, its
COM4:

Press Open to open a terminal window ,where you can log in to CHIP with username and
password chip.

You are now free to do whatever it is you do with Linux command line on CHIP.

Zero Configuration Networking

You can make working with CHIP on a local network much more convenient by installing zero-conf
networking. OS X users may know this as Bonjour.

With zero-conf properly configured, your CHIP can be contacted using a name, such

as chip.local, rather than an IP. This is especially convenient, if you are moving CHIP to

different networks that might assign different IP addresses. The key technology for this in Linux is

the avahi set of tools. There are a few related packages, but this tutorial is a minimal installation to
get it up and running.

Requirements

CHIP

Monitor and keyboard

SSH or serial connection to CHIP or

Connection to a network

Install avahi

Getting avahi running is extremely simple. First, install the avahi-daemon:

sudo apt-get install avahi-daemon

to install the necessary libraries. You may want to configure the daemon with this service file so
you can find Apple Bonjour devices from CHIP :

sudo nano /etc/avahi/services/afpd.service

Then just copy and paste this XML into it:

<?xml version="1.0" standalone='no'?><!--*-nxml-*-->

<!DOCTYPE service-group SYSTEM "avahi-service.dtd">
<service-group>

<name replace-wildcards="yes">%h</name>
<service>

<type>_afpovertcp._tcp</type>
<port>548</port>
</service>

</service-group>

Then restart avahi-daemon:

sudo /etc/init.d/avahi-daemon restart

You can now find the hostname that you can use to reach CHIP:
hostname

which will probably return chip as the hostname.

Use Zero-Conf

From a terminal on another computer you can try accessing CHIP with the network
name chip.local

ssh [email protected]

and enter the password (default is chip). Thats it. You can now reach CHIP without knowing the
IP.

Change the hostname

If you have more than one CHIP on the network, or you just want to change the name from chip

to fit into your network name scheme, you can modify the hostnames file. Open the file in an editor:
sudo nano /etc/hostname

where youll see a single word chip. Just modify that line (for example, change it to

bobofettywap) and save the file. Youll also need to modify the hosts file where youll need to
change the first line127.0.0.1 chip where you replace chip with your new username.
sudo nano /etc/hosts

Finally, to get this new name to broadcast over the network restart avahi-daemon:
sudo /etc/init.d/avahi-daemon restart

You can now access chip with the new name:

ssh [email protected]

Other packages

You may want to explore some of the other features of avahi, such as browsing a network for other
zero-configure enabled computers. Theres a package you can install:
sudo apt-get update &

sudo apt-get install avahi-utils

which gives you a set of tools for browsing the network, such as the command
avahi-browse -d local _ssh._tcp --resolve -t

which will list other zero-configure-enabled devices on the local network. You could ssh to your
Macintosh named bananna, for example with
ssh username@bananna

An alternative to just installing the avahi-daemon, you can

sudo apt-get install libnss-mdns

which installs some other tools for network name propagation.

Troubleshooting

If your computer returns the error

ssh: Could not resolve hostname chip.local: nodename nor servname provided,

or not known

then you either need to wait a minute or try installing avahi-daemon again, but pay closer attention
to any errors that apt-get returns.

If you cant connect to CHIP even though you are sure avahi is properly configured, confirm that

your CHIP and the computer you are trying to connect are on the same local network (and on the
same subnet).

FAQs
Frequently Asked Questions

Do I need to install something for CHIP to be a computer?

No. CHIP comes preinstalled with the CHIP Operating System and several applications. Just
power on, and get started.

Why composite video?

Several reasons:

Televisions are the most commonly available screen in the world and the vast majority of

Composite video can be integrated without adding licensing fees to the cost of C.H.I.P.

them have a composite input.

Composite is a very low profile connector, allowing us to keep the footprint of the board
small for people wanting to build C.H.I.P. into projects.

Is CHIP an exposed circuit board?

Yes! Not having a case for C.H.I.P. is one of the ways we are able to keep our costs down. As
makers, were excited to introduce people to the physical components of computers and show

them that electronics arent scary, theyre fun! We hope to spark curiosity and encourage people to
begin tinkering themselves.

What resolution can CHIP function at?

With the VGA and HDMI adapters, C.H.I.P. is designed to work at 720p resolution, though the Mali
400 GPU is technically capable of up to 1080p outputs. The composite video connector operates
at the SD resolution of 640x480.

How is CHIP so cheap?

QUANTITY. Our partners at Allwinner worked hard to help us find how to reduce costs, so we
could introduce C.H.I.P. to EVERYBODY. To sell C.H.I.P. for $9, we need to order tens of

thousands of chips. By using common, available, and volume-produced processor, memory, and
wifi chips, we are able to leverage the scales at which tablet manufacturers operate to get
everyone the best price.

What does CHIP stand for?

Were curious to hear what you think ;)

Is CHIP open source? Where are the docs?

YES! Very open source! We are still in the process of testing and refining the whole C.H.I.P. family.
As we hit design completion, well release our design files. Weve already released quite a bit!
Check them out at our GitHub repo!

Can I upgrade CHIPs RAM/Storage/Processor?

Technically, yes, but the components are soldered on and not intended to be swapped out. If you
really like reworking small BGA and fine pitch components, though, we wont stop you. :)
If you want additional storage, you can attach a USB drive!

How many accessible pins does CHIP have?

Eight digital GPIOs, one PWM pin, SPI, TWI (I2C), UART, USB, CSI, Parallel LCD output,

touchpanel input, stereo audio out, mono audio in, composite video out, and a whole bunch of
power rails in and out.

The most up-to-date information is on our GitHub repo.

Can I make my own adapter board?

Absolutely! The schematics and layout for the boards, both of C.H.I.P. and C.H.I.P.s adapters will

be released as they are finalized for production. From that, you can build whatever sort of adapters
or add-ons you want!

Does the HDMI adapter have HDMI audio output?

Not at this time. Because there is no onboard digital audio support from our processor, C.H.I.P.s

current design only has analog audio output via the headphone/composite jack. Adding a USB
sound card is the easiest way to beef up your CHIPs digital audio output options.

Does Linux come pre-installed?

YES! C.H.I.P. comes with Linux installed, and a selection of our favorite programs and games. Like
any real computer, you can download more software and customize C.H.I.P.s applications and
operating system to suit your needs!

Can I plug in a Keyboard, Mouse, AND Power?

The easiest way to accomplish this is to power C.H.I.P. as usual via the microUSB port. Attach a
USB keyboard with an accessory USB port on it, then connect your wired mouse to that port.
Alternatively, a bluetooth keyboard or mouse can be used to free up the need for USB
connections.

For more advanced use cases, C.H.I.P. can be powered via its interconnects, leaving both the full
size USB and microUSB ports available to attach devices to.

Can I stream Netflix?

Due to a lack of support for Silverlight (the back-end software that allows Netflix to be streamed) in

Linux, it is unlikely that Netflix will work on C.H.I.P. using entirely open-source software. This would
require someone to come up with an alternate back-end. That said, some very astute backers
have reported that Netflix should be possible by installing the Google Chrome browser, which
allows Netflix streaming via HTML5.

Does CHIP have a power switch?

Yes! C.H.I.P. has a tiny power on-off button and a status LED on the board itself.

Can I make a supercomputer by linking 100 CHIPs

together?

Were focused on individual uses of C.H.I.P. but what youre talking about is called clustering, and

may be possible A good place to start, if youre interested in clustering, is reading up on DebianBeowulf

What about a camera?

C.H.I.P. has exposed CSI pins on its headers for integrating a camera directly to the processor, or
if drivers and sensor tuning sound like a bit much, you can always add a USB camera too.

How do I connect a display?

You can connect a display through the 3.5mm () TRRS composite video port on C.H.I.P. If youd

like to connect to a vga or hdmi monitor, we have adapters available for that! You can also connect
any parallel LCD to the exposed display pins on C.H.I.P.s headers.

Does CHIP have an SD card slot?

No. But by integrating reliable storage onto the device, were able to both save you a getting

started cost and allow Linux to come preinstalled on C.H.I.P. meaning its ready to go when it

arrives at your door. One of the big goals of this project is making C.H.I.P. easy to use, and this
goes a long way towards that end. If you need additional storage, its easy to add an SD card
reader or other USB storage with the built-in USB port.

Can I connect to composite video AND audio out at the

same time?

YES! The 1/8" mini (TRRS) jack can be used either with a video-only cable, audio only cable,

headphones, headphones with mic, OR a combined Audio/Video composite cable. Pretty versatile
little port, isnt it!?

What software does CHIP ship with? What programs can it

run?

C.H.I.P. comes pre-loaded with some of our favorite open-source applications, and the ability to
install hundreds more. Whats even more exciting, though, is that if any given program isnt

supported out of the box, the community can work together to make it happen. Thats what we <3
about Open Source Software.

What programming languages does CHIP support?

C.H.I.P. is a real computer, and can run software written in all kinds of programming languages,
so long as theres a compiler for them. Python, Java (via JDK8), Ruby, PHP, Squeak, C++, JS,
Assembly, BF.. even our favorite, ArnoldC, and lots lots more.

Does CHIP have Real Time Clock?

No, but adding an RTC is a great (and easy) hardware hack, for the folks that need it. For most

people, though, an RTC isnt necessary since it is easy to get C.H.I.P. to pull time from a remote
NTP server over wifi.

What voltage are GPIOs?

CHIP uses 3V3 digital logic on GPIOs.

What connector is used on the battery?

We are using a JST-2.0 PH 2-pin shrouded male connector to connect LiPo cells to C.H.I.P. In the
current design there are also BATT pins available on the interconnect headers, which allow
alternate battery connectors/placements when attaching C.H.I.P. to a custom PCBA.

I want to know more about the Allwinner R8 processor!

You can find out more from the Allwinner R8 User Manual and the R8 Datasheet

What kind of battery can I use with CHIP?

Any single-cell (3.7V) LiPo battery will work with C.H.I.P. You can go bigger or smaller than
3000mAH as needed for your project!

Does CHIPs WiFi support AP mode?

YES!

Does C.H.I.P. have an ethernet port?

No. But it does have built-in 802.11b/g/n wifi. But if you like wires, you can use a USB-Ethernet
connector.

Does C.H.I.P. come with a banana?

C.H.I.P. is strictly B.Y.O.B. ;)

Is there a command that lets me know more about the CPU

and Memory?

Its a computer! It will tell you anything. If you want to find out more details about CHIPs processor,
use the command:

cat /proc/cpuinfo

This will give output similar to:

processor

: 0

BogoMIPS

: 1001.88

model name
Features

: ARMv7 Processor rev 2 (v7l)

: half thumb fastmult vfp edsp neon vfpv3 tls vfpd32

CPU implementer : 0x41

CPU architecture: 7
CPU variant : 0x3
CPU part

: 0xc08

CPU revision

: 2

Hardware

: Allwinner sun4i/sun5i Families

Serial

: 162542c10c427777

Revision

: 0000

If you want know more about the memory:

cat /proc/meminfo

with output something like:

MemTotal:

507108 kB

MemAvailable:

382592 kB

MemFree:
Buffers:

298600 kB
0 kB

Cached:

92216 kB

Active:

98752 kB

Active(anon):

73180 kB

SwapCached:
Inactive:

Inactive(anon):
Active(file):

Inactive(file):
Unevictable:
Mlocked:

HighTotal:
HighFree:
LowTotal:
LowFree:

SwapTotal:
SwapFree:
Dirty:

Writeback:
AnonPages:
Mapped:
Shmem:

0 kB

64096 kB
5812 kB

25572 kB
58284 kB
0 kB
0 kB
0 kB
0 kB

507108 kB
298600 kB
0 kB
0 kB
0 kB
0 kB

70660 kB
37768 kB
8360 kB

Slab:

22784 kB

SUnreclaim:

11224 kB

SReclaimable:
KernelStack:
PageTables:

NFS_Unstable:

11560 kB
1176 kB
2240 kB
0 kB

Bounce:

WritebackTmp:

0 kB
0 kB

CommitLimit:

253552 kB

VmallocTotal:

507904 kB

Committed_AS:
VmallocUsed:

VmallocChunk:

615216 kB
14560 kB

482532 kB

Troubleshooting
CHIP Wont Boot or Startup

Problem: I attached a keyboard, monitor, and powered CHIP, but it does not do anything. The
LEDs are on, but I cant do anything with CHIP!

Fixes: Dont worry, your CHIP is probably fine. This can be fixed by reflashing CHIP from our web
flasher.

Follow the instructions for flashing your CHIP.

Sudden Shutdown (Brown-out)

Problem: I attached a mouse and keyboard, and my CHIP suddenly turned off.
Fixes: Like most tiny computers, the USB port on CHIP provides a limited amount of power. When
you plug in a keyboard and an optical mouse, for example, they will draw too much current from

CHIP, not leaving enough for the processor. As a result, CHIP will immediately shut down. There
are a few ways to avoid this.

Use a powered USB hub

Use a bluetooth keyboard and mouse. Yes, this is a very specific solution, but a good one
when you are only using the USB port for keyboard and mouse. Keeps your desk cleaner
too!

Execute the command sudo axp209 --no-limit in the terminal before you attach your
USB peripherals.

Provide power from a supply connecting ground and 5V the pins headers 1 and 2 on U13.

Problem: My CHIP booted fine until it got to loading the desktop GUI, then it shut down.

Fixes: This is usually the result of an underpowered power supply. We recommend a 5V power
supply with a minimum 1A current rating.

You can find the current rating on your power supplys Output - it should read 1000

mA or 1A (or a higher number). You may need a magnifying glass to read it, but they all
should have this info on the label!

Instead of powering CHIP using the microUSB port, try using the header pins CHG-IN
(U13-2) and GND (U13-1).

Add a LiPo battery. This provides enough extra current and power buffer to prevent this
problem.

No Video Output

Problem: Monitor is attached, but there is no video on my monitor

Fixes: There are a few possible problems here

wrong TRRS arrangement: try different ends of your cable. Make sure is subscribes to this

PAL monitor: CHIP outputs NTSC format video by default. You can change this, however,

use of the tip, rings, and sleeve

by following this guide.

Video trace cut for mic in: This is pretty unlikely, but if you are working with a used CHIP,
it may be that the tip connector has been switched to work as a microphone input. Before

you do fix this with a bit of solder, take a close look at your board to see if there is evidence
of a score mark indicating the cut trace.

How to Contact Us

If you need more support, try our forums or email us.

Compliance Statement
FCC ID: 2AF9F-HELLA1337
IC: 20863-HELLA1337

FCC

This device complies with part 15 of the FCC Rules. Operation is subject to the following two

conditions: (1) This device may not cause harmful interference, and (2) this device must accept
any interference received, including interference that may cause undesired operation.

Industry Canada

This device complies with Industry Canada license-exempt RSS standard(s). Operation is subject
to the following two conditions:

1. This device may not cause harmful interference;

2. This device must accept any interference received, including interference that may cause
undesired operation of the device.

Cet appareil est conforme Industrie Canada une licence standard RSS exonrs (s). Son

fonctionnement est soumis aux deux conditions suivantes: 1. Cet appareil ne doit pas provoquer

d'interfrences 2. Cet appareil doit accepter toute interfrence reue, y compris les interfrences
pouvant provoquer un fonctionnement indsirable de l'appareil.

Information to User

CAUTION: Changes or modifications not expressly approved for compliance could void your
authority to operate this equipment.

Introduction
Welcome to Next Thing Co documentation.

Welcome to The CHIP Operating System

We made a computer. A $9 computer. And every computer needs an operating system.
Ours is The CHIP Operating System. Grab an old TV (or any screen with a composite video input),
a keyboard and mouse, and stick some electricity in the micro USB port. In a few seconds, youll
have CHIPs operating system on your screen, ready to do computer things.

CHIP is built for making - weve packed a powerful processor, 4 GB of storage, stereo audio, video
out, and lots of connections for playing and making your projects and products.

The CHIP Operating System is built for doing: browse the net, send email, play video games,

listen to music, write a novel, watch a video, or learn programming. And because its based on the
popular Linux Debian, if theres something you need, you can probably install it.

So how do use this thing? Lets get started.

Start CHIP. Boot CHIP.

First things first. Lets boot CHIP into the CHIP Operating System and do some computer things!

Add some power, turn on the wireless network, and even connect a bluetooth keyboard to get rid
of those annoying cables.

Power Up

The single most important thing to using any electronic device is getting electricity to the right

places. Were going to cover how to turn CHIP on. This might seem so straightforward that it

doesnt deserve several paragraphs, but CHIP is pretty clever, so theres actually a few things
worth knowing.

Whats It Need?

In general, CHIP is powered by a 5-volt source like a USB port or phone charger, and draws about
500mA peak (at boot time), runs on around 100mA, and rests with around 80mA with the

processor totally unloaded. To make sure you have enough headroom, we recommend that you

use a 5v power supply with at least 900mA current available. This may be more than you need to
know if you just want to plug it in to the wall, but, as you build projects with CHIP, youll be happy
to know theres a lot of ways to get the electricity flowing.

How Do I Know CHIP Is On?

CHIP is silent. It doesnt take much energy, so its not very hot. It has no discernible smell. As a

result, many of your senses are not great indicators that it is working. There are two LEDs next to

the USB micro connector. When CHIP is on, you should see the PWR LED light up nice and bright.

Power From The Wall

The CHIPs microUSB connector is used to provide power from most any USB power source. USB

wall-wart adapters are probably littered all over your house. If for some reason you dont have one,

you can buy one at any electronics retailer. We recommend a 5V powersupply with at least 900mA
current available. Just plug a USB-A-to-microUSB-B cable (thats the same cable most phones,

tablets, and whatnot use to charge) into the wall-wart and CHIP, and youll see the PWR LED light
up. This CHIP is using the power from a computers USB port:

Power From A Battery

CHIP can also be battery powered. Specifically, any single cell (1S) 3.7V Lithium Polymer (LiPo)
battery with a 2-pin JST-PH 2.0mm end can be connected to the JST-PH socket.

The JST can only plug it in one way: if you are having a hard time lining things up, turn it around!

Needless to say, do not force the battery connector into the socket if something doesnt feel right!
Whats really great is that if you plug in to a charger and plug in a battery, the battery will charge all the power management is on CHIP itself. Roughly, it takes about four to six hours to charge a

3000 mAh LiPo battery from a 5V 1A power source. Also, our delightful little Power Management
IC, the AXP209, handles pass-through power, so while on and charging a battery, CHIP is

basically running on a un-interruped power supply If charge power fails, CHIP seamlessly
switches onto battery power without shutting off.

Connect To WiFi

Connecting to a WiFi network is easy using the WiFi icon the top right system tray. Just select a
network to initiate a connection. If the network requires a password youll be prompted for it.

If you need more control and information over your network connection, use the Settings->Network
Connections panel to show your connections. Double click on a connection to bring up the
connection editor:

Connect Bluetooth

Bluetooth device setup can be accessed using the Bluetooth icon in the top right system tray.

When you begin a connection, youll be guided through the necessary steps to connect to your

device. For example, when you pair with a keyboard, youll often be prompted for a code to enter

to ensure a unique connection. Once you have paired a device, future connections will usually be
automatic when the devices are in range and powered up.

You can manage, and also connect to, your devices using the the Bluetooth Devices panel,
accessed from the Bluetooth system tray:

Using The Terminal

One of the great powers of Linux is the so-called command-line. This simple text interface for

computing unveils many of the gears and levers that make a computer tick. Many find it easier to
get things done, as it is a focused and terse way to interact with the computer.

When you first use the Terminal Emulator program, you may quickly find that you do not have
permission to do something. That is because many commands are safely reserved for root

access, and you are automatically logged in as the chip user. Dont fear: you can often use

the sudo command and use the default password chip to execute these restricted commands.
Finally, it is probably wise to change the default password on your CHIP. You can do with

with shell passwd or shell sudo passwd root and youll be asked for a new password. Dont
forget it!!

If you are such a fan of the command line, you may want to boot with out the desktop and window
system. Instructions for that are here

Terminal for Beginners Glossary

One of the great things about Linux is the terminal application. While it may look unfriendly and

terse, if you want to really extend the capabilities of CHIP, youll often find yourself in the terminal.
If youre a beginner, heres a quick reference of some really important and common commands.
You can simply add -h to get some hints on how to use a command, such as cp -h or you can
read a manual page usingman cp. Most unix commands have a variety of options that can be

executed in the command with flags, such as ls -l -a. Even better, search the internet! This

primer is simply here to help you understand what a command might be doing, not to help you use
it to its full ability.

cd change directory. open a folder. ex: cd ~/Pictures changes your current directory to

mkdir make directory. create a folder. ex: mkdir Vacation makes a folder

the home Pictures folder, so you can easily access the files within.

named Vacation in the current directory. mkdir ~/Pictures/Vacation makes

a Vacation folder in the home Pictures directory.

ls list files in the current directory so you know what is in it. Some options are ls -l to list
in long format to provide information about permissions, size, and date. ls -a to show
hidden files that start with the . character.

mv move a file from one directory to another, or to give it a new name. Ex: mv this.one

that.one renames a file. mv this.one ~/Pictures/Vacation/ puts the file this.one into
the Vacation directory.

cp copy a file from one place to another. Ex: cp this.one this_01.one will
copy this.one to another file this_01.one. Add directories for more fun: cp
~/Pictures/Vacation/saturn.jpg

/Users/otherone/Pictures/Vacation/saturn.jpg.

rm remove a file. delete it, and beware!. Use the -r to make it recursive to delete a

directory. Ex: rm this.one deletes that file. rm -r ~/Pictures/Vacation to forget the

good times.

sudo super user do. many commands need administrator-like privileges, otherwise they
wont work. apt-get is a command that needs to be run with sudo to allow files to be

written to protected directories. Youll see sudo as the first word in a lot of commands - all it
is doing is giving the command the necessary access. Youll be asked for a password the

first time you use sudo. The default password and user is chip.

apt-get the command used for installing, removing, and finding software for Debian Linux

systems, such as the CHIP Operating System. sudo apt-get install puredata installs
the Pure Data program and any dependencies. sudo apt-get remove puredata will

remove the program. sudo apt-cache search image will search apt repositories for the

keyword search. And so on.

pwd present working directory. In case you forget where you are. Not much to it: pwd will
output the directory name, such as /Users/home/chip/Pictures/Vacation/

grep a tool used for searching through files. Its quite deep and can be complicated, but if
you see the word grep in some command, you know its searching for a match.
| (pipe) a command used to redirect data into an application.
< (redirect) a command use to redirect data into a file.

cat concactenate. used to append data to a file. Ex: cat "Last line of text" >

sometext.txt. Merge files: cat append.txt > main.txt will put all the text in append.txt
into main.txt.

less makes it so you can paginate and read a text tile. Ex: less longtext.txt will fill the
screen with the first part of the longtext.txt file. Use the space bar to view the next page.
Type q to exit.

nano a text editor. Youll often see commands that call nano so you can edit a

configuration. Ex: nano /etc/avahi/services/afpd.service to edit the avahi Apple file

service file.

find look for files in the filesystem. Ex: find ~/Documents -name particular.txt -

type f will look for the file with the name particular.txt in the Documents directory.
chmod change mode. Used for file permissions, which can be important when sharing
things on the network, scripting actions, and many more reasons.

htop display the processes currently alive on the CPU. If things seem slow, or you want to
see how much CPU or memory a program is using, just type htop to see a table of all
running processes, then typeq when you want to exit.

scp secure copy. copy a file from one computer to another over a network. Ex: scp
Pictures/Vacation/motel.jpg Pictures/Vacation/accident.jpg

[email protected]:~/Pictures copies a couple jpegs to another computer on the

network.

ssh secure shell. access another computer on the network and use the terminal commands
to make changes and control it. Ex: ssh [email protected] to access your CHIP on a local
network.

CTRL C if you cant use the terminal because a process is taking too long, type CTRL-C on
your keyboard to cancel the most recent command.

Connecting Accessories
CHIP has a lot of connectors, some for building, some for doing normal computer things. This
section covers the normal computer things, like audio, video, and input.

Recommended Accessories

CHIP is a minimal computer. Many CHIP users may never connect common peripherals, instead
using CHIP as a headless computer. Like desktop computers from Best Buy, you may find that
certain accessories will improve the overal usability of CHIP. We recommend:

Bluetooth Keyboard

Monitor with a composite video input

USB mouse

USB cable: USB-A to microUSB-B

TRRS to RCA connector

Additionally, some of the advanced tutorials require:

Speakers with RCA audio input

USB to UART cable

Jumper wire

Single cell Lithium Polymer battery

Powered USB Hub

Youll find that a simple powered USB hub is pretty essential if you want to use a lot of USB

devices with CHIP. Not only is there only one USB port (keeping CHIP nice and small), but CHIPs
micro USB power port can only provide so much power for the USB port. If you dont have a
powered USB port, youll quickly max out power if you attach too many accessories.

Keyboard and Mouse

Many keyboards have USB hubs built-in, so you can attach a mouse to the keyboard, attach the
keyboard to CHIP, and immediately have control. However, its likely the two will draw too much
current, so youll want to connect to a powered hub before you connect.

Bluetooth Keyboard and Mouse

As you know, CHIP has built-in bluetooth. If you want to use a keyboard and mouse, you can keep
your USB port free for other things (like mass storage or a MIDI controller!) and keep your desk
clean. Seeconnecting to bluetooth section

Monitor

In the spirit of keeping things small, CHIP packs all the audio and video into a small TRRS (TipRing-Ring-Sleeve) connector. Built-in video output is restricted to standard composite video

resolution of 640x480. Higher video resolutions are possible using the VGA and HMDI DIP boards.

Heres what the other end of the cable looks like, attached to a monitor with stereo audio inputs
(red and white) and the composite video plug, moved so you can see the label on the monitor:

About the TRRS Connector

CHIP comes with a 1/8" (3.5mm) Tip-Ring-Ring-Sleeve (TRRS) jack, capable of carrying stereo
audio, and either composite video out, or microphone in.

This is a fairly common port, but there are a few different arrangements of the conductors, so not
all cables are equal. Fortunately, CHIP uses the same conductor arrangement as Pi, Zune, and
iPod audio/video cables, so the most common mini to RCA A/V cables should work just fine.
Some cables will route signals a bit differently, using the Red RCA cable for Video instead of

Yellow. If video out isnt working through the yellow cable, see if red works. If not, your cable may
be a version thats arranged in a way that it just wont work with CHIP:

yellow : video

white : stereo audio left channel

red : stereo audio right channel

The conductors on the TRRS plug are arranged like this:

If you want to learn even more about TRRS connectors and the general lack of standardization
with them, this page has even more details.

NTSC or PAL

The composite video format is NTSC by default. If you need to hook up to a monitor that only uses
a PAL signal, youll need to change that at u-boot time. First, connect to CHIP with a UART cable.
Then power up CHIP, and press a key on the keyboard to boot into u-boot mode to change the
environment variable manually.
printenv video-mode

setenv video-mode (mode data)

saveenv
reset

where mode data can be, for NTSC and PAL respectively:
setenv video-mode sunxi:640x480-24@60,monitor=compositentsc,overscan_x=40,overscan_y=20

setenv video-mode sunxi:720x576-24@50,monitor=compositepal,overscan_x=40,overscan_y=20

Headphones

The audio and video connector on CHIP can be dedicated to audio output suitable for headphones
or connecting to an amplifier for filling a room or public space with glorious sound. Just connect a

standard 3.5 mm (1/8") TRS audio plug into CHIPs a/v jack. Of course, if headphones are plugged
in, there will be no room for a composite video output jack. You can also get audio left, common,
and right output frompins 4, 6 & 8 on header U14.

Microphone and Audio Input

If you want to use audio input, you might find it easiest to use the pins on pins 10 and 12 on

header U14. However, if you want to use the 1/8" TRRS connector, you can modify the CHIP
board to replace the composite video connection with an audio input connection.

If you look at the bottom of CHIP with the audio and USB jacks pointed up, youll see three small
contact pads to the left of the audio jack. The left pad has a small label of mic and the right pad

has a tv label. Between the middle pad and the tv pad is a trace that can be carefully cut with an

Exacto or utility razor blade. Once that is cut (check with a volt or continuity meter), you can put a
solder blob between the micand middle pad. Now the outer ring can be used for audio input.

As another reference, if you had X-ray vision and you were looking from the bottom of CHIP,
youd see a trace like this:

If the composite video connection is needed again, just reverse the process: desolder the

connection between mic and the middle pad, then solder a bridge between tv and the middle pad.

Microphone with Header Pins

If you want to use the pins 10 and 12 on header U14, youll most likely need to add some
additional circuitry to get a good input signal. Here is a schematic of the simple circuit:

Youll need two 4.7 microfarad capacitors, one 100 nanofarad capacitor, and a 3300 picofarad
capacitor. Youll also need one 2 kilo-ohm and one 4.3 kilo-ohm resistors.

USB Storage

If you have files that you want to modify, use, or transfer to CHIPs internal storage, you can attach
a USB thumb drive, card-reader, or hard drive. Open the file manager and access the files.

USB Audio

CHIP can use Class-compliant USB audio devices. A popular, and inexpensive choice for audio
devices are USB dongles based on the C-Media chipset. These have been tested successfully

with CHIP and can often be purchased for less than $10. Some good resources for linux and audio
compatibility are on the linux audio and alsa project websites.

Many of the drivers have not been tested with CHIP - as CHIP matures, more information will be
available. For now, we recommened USB Class-compliant or plug-and-play audio devices.

Battery and Charging

Like any modern laptop, CHIP can run and charge any single-cell LiPo battery. Read more in
the powering CHIP section.

Using The CHIP Operating System

If youve used a desktop or laptop computer before, the CHIP Operating System should be pretty
familiar. There are menus, icons to click, menus with more stuff when you right-click, keyboard

shortcuts, applications to run, and settings to set. CHIP is small, so we keep our operating system

simple. Almost everything can be accessed from the Computer Things menu: settings, launching
apps, and access to files. Theres also a few convenient functions in the top right system tray.

Settings and Configuration

Most of the settings for the computer and for the desktop can be set using the apps in the

Computer Things menu. Select the appropriate app from either the Settings Menu or the Settings
Manager.

WiFi

Connecting to a WiFi network is easy using the WiFi icon the top right system tray. Just select a
network to initiate a connection. If you need a password, youll be prompted for it.

If you need more control and information over your network connection, use the Settings->Network
Connections panel to show your connections. Double click on a connection to bring up the
connection editor:

Bluetooth

Bluetooth device setup can be accessed using the Bluetooth icon in the top right system tray.

When you begin a connection, youll be guided through the necessary steps to connect to your

device. For example, when you pair with a keyboard, youll often be prompted for a code to enter

to ensure a unique connection. Once you have paired a device, future connections will usually be
automatic when the devices are in range and powered up.

You can manage, and also connect to, your devices using the the Bluetooth Devices panel,
accessed from the Bluetooth system tray:

Sound

By default sound output comes from the built-in connector, served by the sunxi codec driver. If
you want to change the volume, you can use the volume control in the top right system tray:

Or, open the Audio Mixer in the Multimedia category:

Here, you can select the Playback category to change the volume:

If you dont see that control, just click on the Select Controls button and enable all controls:

Display

Use the Settings->Display control panel to adjust the monitors resolution and rotation settings:
If you want to customize the desktop image, icons, colors, and fonts, there are two different panels.
The Appearance panel lets you select a theme to make instant changes for several properties.

The Desktop panel lets you customize images and colors, along with the behavior of menus.

If you want to change the theme or the icon sets, you can search for these using the Synaptic

Package Manager. Search for gtk2 themes or icon sets. There are also packages that can

make it easy to find and configure themes, such as gtk-theme-config. Similarly you can use the
command line to search packages with apt-cache search gtk2 theme.

Time and Date

Set the Time with the Orage Globaltime panel. This can be found in Accessories->Orage

Globaltime or in Office->Orage Globaltime. Simply click the time to bring up the preferences panel.
You can quickly view the date from the Orage Calendar in the Office menu.

Mouse Sensitivity

Mouse sensitivity is set for the default 640x480 resolution. If you are using CHIP with a higher

resolution monitor, you may want to adjust the sensitivity of the mouse. You can get to the Mouse
settings panel from Computer Things->Settings->Mouse and Touchpad

Language and Location

CHIPs operating system comes with a default language of English. You can change the language
and the location, but youll need to use the terminal to do so. Use the Computer Things! menu to
launch the Terminal Emulator. Then use the apt-get command to install the language packs and
run a simple program to configure your language and location:

sudo apt-get update && sudo apt-get install locales && sudo dpkg-reconfigure
locales && sudo locale-gen

Youll get a large menu to select locales. Use the arrow keys to scroll down and spacebar to mark
your location with an [*]. Its advised that you choose the location marked UTF8. Others are
somewhat arcane edge cases! Hit return to continue.

You can set the timezone with

sudo dpkg-reconfigure tzdata

Launching Installed Apps

CHIP comes prepackaged with many open-source applications to get you started. Its easy to

launch an application. You can select an application from the Computer Things! menu and select
an app from the categories:

Or, for more control, launch the Application Finder in Accessories, where you can use the search
bar and easily navigate among the categories:

Below are some of the applications that come pre-installed with CHIP:

AbiWord

AbiWord is a fully featured word processor. You can learn more at The AbiWord website

Ice Weasel Browser

Ice Weasel is a Debian Linux version of the Firefox browser. The browser is largely the same as
Firefox, just with a different name. More information is at the Debian website and in this stack
exchange thread.

Video Player

CHIP plays video! Use the built-in Mplayer to open and play videos.

Terminal (commandline)

The life blood of linux. If theres something you cant do on the desktop, or you want to automate

tasks, or access different hardware settings using nothing but a keyboard and text, youll open up
Terminal.

Complete List of Installed Software

These are the applications installed by default on CHIP as accessed through the GUI.

Application Finder

Leafpad

Bulk Rename

Orage Globaltime
Screenshot

Task Manager

Thuner File Manger

Xarchiver

Alex the Allegator 4

Spout

Viewnior

Ice Weasel Web Browser

Audio Mixer

GNOME MPlayer

AbiWord

QjackCtl

Atril Document Viewer

Gnumetric

Orange Calendar

Orage Globaltime
Htop

Package Updater

Synaptic Package Manager

Xfce Terminal
Notifications

Various System Settings

Zip (and UnZip)

Install and Update Software

Synaptic Package Manager

Launch the Synaptic Package Manager to find and install new software. Synaptic is a graphical

interface to the apt-get command and will install software intended for DERP and other debainbased systems. You can learn more about Synaptic here

Theres a simple search bar to make it easy to find packages you are interested in. If you dont find
the package you are looking for, hit the Reload button to refresh Synaptics record of available
packages.

Example: Installing Scratch Programming Environment

Using Synaptic is very easy. For example, if you wanted to install the Scratch Programming

Environment, you can simply search for scratch and youll get a lot of results. Scroll through, and
youll eventually find scratch in the packages window. However, youll probably want to narrow
your results with better search terms, such as scratch programming environments

When search is complete, you can select scratch from the package panel.

Press the top Apply button, and youll get the following dialog:

and youll be notified of the progress:

After a minute or so, youll be notified that its finished:

Now that its installed, you can launch scratch:

Auto Update

CHIP will automatically look for any updates and alert you if updates are available for your existing
software and the operating system.

apt-get

If you are using the commandline, you will use apt-get to install and update new software.
If you are new to apt, some important commands to know:

sudo apt-get update updates the information from repositories, so any installs you make

sudo apt-get upgrade upgrades any installed packages.

with install will be the latest package

sudo apt-get install (name of package) to install a package and any of its
dependencies.

sudo apt-get remove (name of package) will remove a package and any
dependencies not used by other packages

sudo apt-get purge (name of package) will remove a package and any dependencies
not used by other packages along with all settings data

apt-cache search (search terms) will search through the package repositories for
names and descriptions that include your search term.

Uninstall Software

You can use the Synaptic Package manager to uninstall any packages you no longer need. If you
know the name, you can use the Search function to find the package, then Mark it for Removal.
For example, if you want to remove AbiWord, first open Synaptic and search for abiword:

Once found, select AbiWord in the package list, and select Mark for Removal in the Package
menu:

If there are additional, related packages that need to be removed, youll be notified:

Finally, press the top Apply menu to remove the packages:

Youll be notified what changes will be applied:

Finally, you can confirm that AbiWord has been removed by checking the Applications menu:

Boot into Console

If you want want CHIP to boot directly into a console, and not load the Desktop or Window

manager GUIs, there are a couple options. For the temporary case, you can open a terminal
window and use the command

sudo systemctl set-default multi-user.target

Next time you boot CHIP, it will not load the desktop or window environment, leaving you with

command-line operation only. If you wanted to return to booting into the GUI, you can use this
command before you reboot:

sudo systemctl set-default graphical.target

The other option is to run a linux distribution with no GUI installed. You may want to do this if you

want to use commandline only and want to save some storage space. You can follow instructions
to flash CHIPwith buildroot, or Debian (with no GUI).

CHIP Hardware

CHIP is small, but it packs a lot of hardware on the PCB. Heres an overview of the connections
and components.

Parts and Pieces

Wireless

WiFi

CHIP supports 802.11b/g/n using the built-in WiFi.

Bluetooth

CHIP supports the Bluetooth 4.0 LE standard using the built-in Bluetooth.

Physical Connectors

CHIP is loaded with essential connectors for USB, serial, audio, video, and loads of IO on the pin
headers. Oh, and a button too!

Button

There is a tiny tiny button on CHIP next to pin header U13 that is used for turning CHIP on or off. If
CHIP is off and connected to a power source, hold down the button for one second to power it up.
To turn CHIP off (rather brutally), hold the button for 10 seconds. We recommend using the
operating system to power CHIP off, but if you need to, you can use this button.

USB

The single USB port on CHIP is USB 2.0 compatible. It can provide up to 500mA of current, as is
standard for USB ports on computers. If you need to provide more current, we recommend a
powered USB hub.

USB On The Go

The micro USB port is generally used to provide power for CHIP. However, since CHIP can be

powered through the pin headers or a battery, this port can be used for different things. By default,
connecting CHIPs micro USB to a computer will create a USB Serial connection, so you can
access CHIP with a screen or cu session in a terminal. With Linux kernel modifications, it is
possible to enable other modes, such as an Ethernet bridge.

Composite Video and Stereo Audio

The 1/8" TRRS connector provides composite video and stereo audio output. Headphones can be
plugged in for audio only.

Audio Input uses the same connection on the TRRS connector as the composite video signal. If

you want to make audio input active on the TRRS connector, you need to cut a circuit board trace.
This is not as permanent as it sounds, as it is easy to re-enable composite video out with a small
amount of soldering.

Pin Headers

The Pin Headers provide a massive amount of connectivity, making CHIP a suitable platform for
product development for physical computing and internet of things devices. Heres a basic
diagram that labels all the pins:

U13L

U13R

U14L

U14R

GND : ground

CHG-IN : 5V input

GND : ground

VCC-5V : 5V power

UART1-TX : UART

HPL : audio out left

(power and battery

charge)

VCC-5V : 5V
power

GND : ground

serial transmit

U13L

U13R

U14L

U14R

VCC-3V3 : 3V

TS : analog

UART1-RX : UART

HPCOM : audio out

FEL : fel mode:

HPR : audio out right

power

VCC-1V8 : 1.8 V
power

temperature sensor
input

BAT : LiPo battery

serial receive

connect to ground

common ground

to put CHIP in fel

mode for firmware

TWI1-SDA : two-

PWRON : power on

VCC-3V3 : 3 volt

MICM : mic mute

TWI1-SCK : two-

GND : ground

LRADC : low-res

MICIN1 : audio in

wire serial bus 1

wire serial bus 1

X2 : Resistive

(touchscreen)

(touchscreen)

Y1 : Resistive

touchpanel input

LCD-D2 :

RGB666 data

Analog-Digital
Converter

X1 : Resistive

touchpanel input

power

touchpanel input

Y2 : Resistive

touchpanel input
(touchscreen)

PWM0 : pulse width

modulation (also
used for LCD

XIO-P0 : expander

XIO-P1 : expander GPIO

XIO-P2 : expander

XIO-P3 : expander GPIO

XIO-P4 : expander

XIO-P5 : expander GPIO

XIO-P6 : expander

XIO-P7 : expander GPIO

GPIO

GPIO pin 2

GPIO pi

pin 1

pin 3

pin 5

backlight dimming)
LCD-D4 :

RGB666 data

LCD-D3 : RGB666
data

GPIO pin 6

pin 7

U13L

U13R

U14L

U14R

LCD-D6 :

LCD-D5 : RGB666

GND : ground

GND : ground

LCD-D10 :

LCD-D7 : RGB666

AP-EINT1 :

AP-EINT3 : Application

Processor Interrupt

necessary for certain kinds

RGB666 data

RGB666 data

data

data

Application

Processor Interrupt pin,

of hardware-software

interactions (keyboard
expander, etc.)
LCD-D12 :

RGB666 data

LCD-D14 :

RGB666 data

LCD-D11 : RGB666
data

LCD-D13 : RGB666
data

TWI2-SDA : twowire serial bus 2

(I2C)

CSIPCK : CMOS
serial interface

TWI2-SCK(*) : two-wire
serial bus 2 (I2C)

CSICK : CMOS serial

interface, can be used for

attaching a serial camera
sensor

LCD-D18 :

RGB666 data

LCD-D15 : RGB666
data

CSIHSYNC :
CMOS serial

CSIVSYNC : CMOS sync

interface

LCD-D20 :

LCD-D19 : RGB666

CSID0 : CMOS

CSID1 : CMOS serial

LCD-D22 :

LCD-D21 : RGB666

CSID2 : CMOS

CSID3 : CMOS serial

LCD-CLK :

LCD-D23 : RGB666

CSID4 : CMOS

CSID5 : CMOS serial

RGB666 data

RGB666 data

RGB666 clock

data

data

data

serial interface

serial interface

serial interface

interface

interface

interface

U13L

U13R

U14L

U14R

LCD-VSYNC :

LCD-HSYNC :

CSID6 : CMOS

CSID7 : CMOS serial

LCD screen

LCD

GND : ground

GND : ground

vertical sync for

GND : ground

horizontal sync for

LCD-DE : RGB666
data

serial interface

interface

(*)The XIO GPIO pins are provided by an I2C Expander at address 0x38 on the TWI bus 2, as
such, this address is not available on bus 2.

Mechanical Drawing

Our git repo for CHIP hardware has a mechanical drawing

Open Source Hardware: Where To Get It

CHIP is open source hardware. Heres where you can get all the data you need to make, modify,
or learn about your own CHIP. Visit the CHIP Hardware git repository.

Making Stuff
CHIP is more than a cool, small, inexpensive computer. Its a complete system for building projects
that require remote control, network connectivity, and physical interfacing with people and the

environment. CHIPs pin headers have all the connections to make this happen. An annotated
diagram of the pin headers can be found in the hardware section of this manual.

GPIO

GPIO provides basic digital connections to the physical world to create physical products with

CHIP. These pins can act as reads or 'writes, for example, to sense switch positions or turn an
LED on or off.

CHIPs most easily available IO pins are the XIO pins on header U14. This is the GPIO
eXpander that uses an I2C bus to create eight (8) convenient pins for GPIO. These use

address 0x38 on the TWI bus 2. Other pins are available for GPIO if more than eight are needed.

Read and Write From Command Line

CHIP has several General Purpose Input/Output (GPIO) pins available for you to build around. If

you want to access them in a very primitive way, just to confirm their existence, heres some things
to try.

Requirements

CHIP

LED

Jumper Wire
SSH or serial connection to CHIP or
Monitor and keyboard

How You See GPIO

There are eight (8) GPIO pins always available for connecting CHIP to the sense-able world. If you
orient CHIP with the USB connector pointed up, youll find the GPIO pins in the middle of the right
header, U14, Pins 13-20, labeled XIO-P0 to P7:

Kernel 4.3 vs 4.4 GPIO - How To Tell The Difference

For various reasons related to the community nature of Linux development, the GPIO expander pin
numbers are different between CHIP OS kernels 4.3 and 4.4. What follows is a very technical
discussion of the GPIO access. If you just want to start making stuff and dont need low-level
information, you might just want to skip this section and go straight to the python library.

If you are developing applications on CHIP that use GPIO pins and you would like consistent

behavior between the two kernel versions, you need to know how to find out the base value for the
GPIO values. It may be enough for you to know that the GPIO expander pins start at 408 on 4.3

and 1016 on 4.4, however, it would be ideal to calculate this in your application to truly future-proof
for future kernels.

If you look in the directory /sys/class/gpio, youll find two directories starting
with gpio: gpiochip0 and either gpiochip408 (4.3) or gpiochip1016 (4.4).

The 408 and 1016 are the bases for the expander pins. If you want to definitively find out what the
base is using code, you should
cat gpiochip*/label
cat gpiochip*/ngpio
cat gpiochip*/base

The label you are interested in is the value pcf8574a which is the device that provides GPIO

expansion. This provides the number of GPIO as returned by ngpio. The first expander pin starts
with the basevalue. If you parse all these values and apply to your code, you can setup your
application to be kernel-agnostic for GPIO access.

Here is a python script that demonstrates this in a gist

Here is a bash script to compute the base (courtesy of bbs user @fordsfords)
LABEL_FILE=`grep -l pcf8574a /sys/class/gpio/*/*label` BASE_FILE=`dirname
$LABEL_FILE`/base

BASE=`cat $BASE_FILE`

How The System Sees GPIO

There is a sysfs interface available for the GPIO. This just means you can access the GPIO
states in a file-system-like manner. For example, you can reference XIO-P0 using this path:
/sys/class/gpio/gpio408/

The number is somewhat unfortunate, since the sysfs names do not match the labels on our

diagram! But is not too hard to translate. Pins XIO-P0 to P7 linearly map to gpio408 to gpio415 on

kernel 4.3 andgpio1016 to gpio1023 on kernel 4.4. See above to learn more about that
distinction.

Some GPIO Switch Action

These lines of code will let us read values on pin XIO-P7. First, we tell the system we want to listen
to this pin:
#4.3

sudo sh -c 'echo 415 > /sys/class/gpio/export'

#4.4

sudo sh -c 'echo 1023 > /sys/class/gpio/export'

View the mode of the pin. It should return in:

#4.3

cat /sys/class/gpio/gpio415/direction
#4.4

cat /sys/class/gpio/gpio1023/direction

Connect a jumper wire between Pin 20 (XIO-P7) and Pin 39 (GND). Now use this line of code to
read the value:
#4.3

cat /sys/class/gpio/gpio415/value
#4.4

cat /sys/class/gpio/gpio1023/value

Some GPIO Output

You could also change the mode of a pin from in to out

#4.3

sudo sh -c 'echo out > /sys/class/gpio/gpio415/direction'

#4.4

sudo sh -c 'echo out > /sys/class/gpio/gpio1023/direction'

Now that its in output mode, you can write a value to the pin:
#4.3

sudo sh -c 'echo 1 > /sys/class/gpio/gpio415/value'

#4.4

sudo sh -c 'echo 1 > /sys/class/gpio/gpio1023/value'

If you attach an LED to the pin and ground, the LED will illuminate according to your control
messages.

Enough IO

When you are done experimenting, you can tell the system to stop listening to the gpio pin:
#4.3

sudo sh -c 'echo 415 > /sys/class/gpio/unexport'

#4.4

sudo sh -c 'echo 1023 > /sys/class/gpio/unexport'

Learn More

You can learn more about GPIO and Linux here:

Python Library

There is a well-maintained python library that works for 4.3 and 4.4 kernels available here. This is
analogous to the RPi.GPIO library, but is designed for CHIP. Its an excellent place for quickly
working with GPIO and PWM on CHIP.

GPIO Types

There are many types of sensors that can be used with GPIO:

Switches

Switches provide on/off state input from the physical world to your computer. You can use the
commandline interface to listen to switch values. A python library was created for
the ChippyRuxpin project if you need a higher-level example in python.

LEDs

LEDs can be illuminated and turned off using the commandline interface. Refer to

the ChippyRuxpin project on a good example on how to manipulate the commandline using
python.

Relays

Relays are special hardware bridges used to switch higher voltage electronics, protecting CHIP

from the high voltages that would destroy it. Using a relay board is programmatically no different
from using switches.

Expanding GPIO

If you dont need to drive an LCD, you can use those pins for more, faster GPIO if you want to.
These are the pins numbered 18-40 on U13 and 27-40 on U14 to act as GPIO to increase the
number of available GPIO pins. Documentation on this process is forthcoming!

Analog to Digital Conversion

Pin 9 on header U14 provides a link for low resolution analog to digital conversion (ADC). There is
no driver for this link yet. ADC is used to read continuous sensors (temperature, pots, FSR,
photoresistor, etc)

1 Wire

The 1 Wire serial protocol is not available in CHIP OS 4.3. In version 4.4 and above, you can
access one wire data from the sysfs device. Find your one wire devices with
ls /sys/bus/w1/devices/2*/eeprom

The * is there because your eeprom device will register a unique UUID number with C.H.I.P., so
the ls command will show you all available one wire devices.

UART

UART connections can be made using the UART connections on header U14.

PWM

Pulse Width Modulation is used to control motors and other devices. It is possible to use GPIO

pins to drive motors, but they generally are not fast enough for robust and smooth control. PWM
can be accessed through an sysfs protocol.

I2C

I2C can be accessed through a sysfs protocol using the debian i2c-tools. In the terminal, use
sudo apt-get install i2c-tools

Note that the XIO GPIO pins are provided by an I2C expander at address 0x38 on the TWI bus 2,
so that address cannot be used on bus 2.

LCD Monitor Support

Using the numerous LCD header pins, a color touchscreen panel can be directly implemented on
CHIP.

Project Examples
Projects coming soon!

Flash CHIP With an OS

You might want (or need) to completely re-flash your CHIP with a different operating system.
Weve made it really easy to do this by embedding the entire process in a browser-based
application. Just hook CHIP up to your computer, fire up a browser, and flash your CHIP

Things you will need

C.H.I.P.

Thin Paper clip (a jumper wire works too)

Standard-USB to micro-USB connector

Separate computer with Chrome or Chromium browser

Instructions

If you dont have the Google Chrome or the open-source Chromium browser on your other
computer, install it by following the preceding links.

Ok, good. Now that you have installed the browser, you can visit flash.getchip.com in Chrome or
Chromium and follow all the instructions. If you are using a computer with USB3 ports, its

suggested that you attach a USB2-compliant hub and connect your CHIP to the hub, instead of
directly to the USB3 port.

Its possible to run the entire operation online. There are also options for downloading the OS

image to your computers harddrive, then flashing your CHIP with no additional need for internet
access.

For more information on OS-specific issues, see here.

The SDK Way

You may not want to use the browser-based flashing procedure. If this is the case, or you need
additional tools, you can flash using the CHIP SDK

Web Flasher OS-Specific Issues

Before you try anything else, try using a different USB cable. Many cables are charging-only, or do
not support high bandwidth and will cause flashing to fail.

Windows-specific

You must install drivers to be able to talk with C.H.I.P.

Reboot after installing drivers on previous versions (<10) of Windows.

Unfortunately, due to the nature of how Windows manages drivers, the flashing procedure will

likely fail the first time you use it. When that happens, try completely closing and reopening your

browser. Depending on your version of windows, this might happen twice, once when waiting for
FEL, and then again waiting for Fastboot.
Troubleshooting

Try using a USB2 port (USB3 ports have issues).

Try a different USB cable. They often are bad.

Try passing through a USB2 hub if using a USB3 port.

Try turning off antivirus software.

If you get stuck Waiting for Fastboot and the above options dont work, you should be able
to install a headless no fastboot image. However, it will take quite a bit longer, and the
Operating System wont have a GUI.

MacOS specific

There are some times where using USB3 ports will cause the flashing to fail. If you can, try
using a USB2 port, not a USB3. Recent Macs have only USB3 ports. If you find yourself
with a modern Mac, try using a USB2 hub in your USB3 port and plug C.H.I.P. into that.

If you get stuck Waiting for Fastboot and the above options dont work, you should be able
to install a headless no fastboot image. However, it will take quite a bit longer, and the
Operating System wont have a GUI.

Linux-specific

Linux requires permissions to write to C.H.I.P. when its plugged into your computer. Chrome (or

Chromium) does not have these permissions, so you need to explicitly create them before youll be
able to use the web flasher .
On Ubuntu:
You need to paste the following into a terminal:
sudo usermod -a -G dialout $(logname)
sudo usermod -a -G plugdev $(logname)
# Create udev rules

echo -e 'SUBSYSTEM=="usb", ATTRS{idVendor}=="1f3a", ATTRS{idProduct}=="efe8",

GROUP="plugdev", MODE="0660" SYMLINK+="usb-chip"

SUBSYSTEM=="usb", ATTRS{idVendor}=="18d1", ATTRS{idProduct}=="1010",

GROUP="plugdev", MODE="0660" SYMLINK+="usb-chip-fastboot"

SUBSYSTEM=="usb", ATTRS{idVendor}=="1f3a", ATTRS{idProduct}=="1010",

GROUP="plugdev", MODE="0660" SYMLINK+="usb-chip-fastboot"

SUBSYSTEM=="usb", ATTRS{idVendor}=="067b", ATTRS{idProduct}=="2303",

GROUP="plugdev", MODE="0660" SYMLINK+="usb-serial-adapter"
' | sudo tee /etc/udev/rules.d/99-allwinner.rules
sudo udevadm control --reload-rules
Then logout and log back in.
For the curious:

logname: outputs your username

plugdev: allows non-root mounting with pmount

dialout: gives non-root access to serial connections

The udev rules then map the usb device to the groups.
For more information, check the systems group page on debian.org.
USB3 Issues * If you have any issues, try using a USB2 port and not a USB3 one, or try using a
USB2 hub in your USB3 port and plug C.H.I.P. into that. * If you get stuck Waiting for Fastboot

and the above options do not work, you should be able to install a headless no fastboot image.
However, it will take quite a bit longer, and the Operating System wont have a GUI.

Caveat In rare cases, you may have an issue with your computer putting C.H.I.P. into autosuspend mode. Here is an example on how to fix this problem:
apt-get install laptop-mode-tools

#### edit /etc/laptop-mode/conf.d/runtime-pm.conf, uncomment/change

AUTOSUSPEND_RUNTIME_DEVID_BLACKLIST

#### add all fel devices to the blacklist:

AUTOSUSPEND_RUNTIME_DEVID_BLACKLIST="1f3a:efe8"
reboot

Advanced
For those interested in building with a stripped-down version of an operating system, or looking to
customize CHIP from the command line, we have several tutorials that describe how to setup
CHIP with more depth.

Installing C.H.I.P. SDK

CHIP-SDK has everything needed to develop software for C.H.I.P. Most importantly, if you want to
load an operating system onto CHIP, the only supported way is to do this from a virtual machine.
Given that the virtual machine runs Ubuntu, its pretty safe to say that Ubuntu users can flash
without the virtual machine.

Requirements

Computer running OS X 10.10+, Ubuntu 14.04+, or Windows 7+

Software: VirtualBox, Vagrant, git, terminal

At least 1 GB free RAM, up to 40 GB of disk space may be used

Software Setup

There are several required software pieces to get the CHIP SDK virtual machine running.
Install VirtualBox and Extensions

Get the installer for Virtual Box

If you are using Windows, you need to add the VirtualBox installation directory to your

Install the Oracle VM VirtualBox Extension Pack.

PATH.

In case of an Ubuntu host: add your user to the vboxusers group!

Install Vagrant
Install Vagrant from the Vagrant site. Alternatively, if OS X, you can use the homebrew package
manager: brew install caskroom/cask/brew-cask brew cask install vagrant

Install Git
Installation of Git depends on your operating system:

Windows: direct to download

OS X homebrew: brew install git

Debian Linux: sudo apt-get install git

Clone the CHIP-SDK repository and boot the Virtual Machine

Assuming you have git in your PATH, open up a terminal and type:
git clone https://github.com/NextThingCo/CHIP-SDK
and start up the virtual machine:
cd CHIP-SDK
vagrant up

Login To Virtual Machine

In the same shell on the host type the following:

vagrant ssh

If everything went well you should see the following prompt:

vagrant@vagrant-ubuntu-trusty-32:~$
All The Commands At Once
Heres all the commands in one place:
git clone https://github.com/NextThingCo/CHIP-SDK
cd CHIP-SDK
vagrant up

vagrant ssh

Congratulations! Now youre ready to Flash a C.H.I.P. from your SDK!

Troubleshooting

Here are a few possible problems.

Shared Folder Out of Sync
In case you run into trouble because the kernel in the VM was updated and the shared vagrant

folder can no longer be mounted, update the guest additions by typing the following in the CHIPSDK directory on the host:

vagrant plugin install vagrant-vbguest

This blog post has some more tips on keeping additions in sync.
Invalid State
If you get an error like:
error: The guest machine entered an invalid state while waiting for it to boot.
This probably means your version of VirtualBox needs updating and/or needs the Extension Pack.
Update as necessary and try vagrant up again.
Couldnt Find File
If you get the error:
error: Couldn't open file /Volumes/Satellite/gitbins/CHIP-SDK/base

that means you didnt cd CHIP-SDK. Very basic, perhaps, but late nights sometimes need that
bump!

Updating the CHIP-SDK Virtual Machine

You may have been working with CHIP for a while now, and you want to updated your SDK. Its

only slightly more involved than sync'ing with the git repo; you have to update the virtual machine,
too.

Requirements

Computer running OS X 10.10+, Ubuntu 14.04+, or Windows 7+

Existing installation of CHIP-SDK

How To Update
Just follow these steps:
On your host operating system, pull the latest changes from our Git repository:
cd ~/CHIP-SDK
git pull

Make sure the virtual machine is shut down and update it:
vagrant halt

vagrant provision

Now you can boot the virtual machine and ssh into it:
vagrant up

vagrant ssh

Once you see the trusty prompt, your CHIP SDK virtual machine is ready to use:
vagrant@vagrant-ubuntu-trusty-32:~$
All The Commands At Once
Heres all the commands in one place:
cd ~/CHIP-SDK
git pull

vagrant halt

vagrant provision
vagrant up

vagrant ssh

Flash CHIP Firmware

Now that the virtual machine and SDK are running and configured, you can connect CHIP to your
computer and give it an operating system. If you want to flash using a native Ubuntu installation,
read how toprepare Ubuntu to flash
Have you repaired your CHIP?
The original batch of CHIPs shipped with a software bug in the NAND flash storage. Weve built a
repair tool.

Prepare CHIP for Flashing

Prepare CHIP with a jumper wire connecting Pin 7 and Pin 39 on header U14 (FEL pin and GND).
Heres a reference image that labels the headers and pins:

Note: this jumper needs to be present only when you connect CHIP to power. If for some reason
the wire becomes disconnected after you have powered CHIP, there is no problem or need to
panic.

Now connect CHIP to your computer with a micro-USB->USB-A cable. The power LED will
illuminate.

Option 1: Flash With NTC Buildroot OS

Buildroot is a lean operating system, and does not have a package manager to install software.

You can add additional software before you flash CHIP by customizing buildroot. To flash CHIP
with the buildroot OS:
cd ~/CHIP-tools

./chip-update-firmware.sh -f

The -f option means fastboot. If you have problems flashing, particularly on Windows or OS X,
you can run ./chip-update-firmware.sh to disable fastboot flashing.

During flashing, the terminal will fill with messages. If successful, youll see C.H.I.P. run through a
hardware test, with the answers being OK. If C.H.I.P. is 'OK, you can remove the jumper wire.
Here is asample successful output.
Option 2: Flash With Debian
If you want to flash CHIP with the debian OS with no window manager or GUI

cd ~/CHIP-tools

./chip-update-firmware.sh -d -f

The -f option means fastboot. If you have problems flashing, particularly on Windows or OS X,
you can disable fastboot by leaving off the -f option: ./chip-update-firmware.sh -d. Here is
a sample successful output.

Option 3: Flash With CHIP Operating System

If you want to flash CHIP with the complete CHIP Operating System
cd ~/CHIP-tools

./chip-update-firmware.sh -d -b stable-gui -f

During flashing, the terminal will fill with messages. If successful, youll see C.H.I.P. run through a
hardware test, with the answers being 'OK. If C.H.I.P. is 'OK, you can remove the jumper wire.
Here is asample successful output. Because of filesize, the gui option must also include the f fastboot option. Windows and OS X are not yet supported as flashing hosts.
Connect to CHIP and Do Something
If everything went OK, you can now power up your CHIP again and connect via serial as a USB
gadget:

screen /dev/ttyACM0 115200

You can login to CHIP as chip or root using the password chip.
and even test the hardware:
hwtest
Customize Buildroot
If you want to customize buildroot, use these commands before you run the ./chip-updatefirmware.sh script to flash CHIP with firmware:
cd ~/CHIP-buildroot
make chip_defconfig
make nconfig

The nconfig command will display a text interface in your terminal. Use your arrow keys to
browse and select additional software for the buildroot OS. When youre finished with your

selections, exit by hitting the F9 key, which will automatically save your custom buildroot to:
/home/vagrant/CHIP-buildroot/.config

Now lets build your buildroot with your custom additions: shell make This will take a while,
maybe an hour. When finished, flash CHIP with the script:

cd ~/CHIP-tools

BUILDROOT_OUTPUT_DIR=../CHIP-buildroot/output ./chip-fel-flash.sh

Unless you changed the users or passwords, you can login to CHIP as chip or root using the
password chip.

Appendix

Sample outputs are provided in this appendix so you can more easily troubleshoot or proceed with
confidence when flashing CHIP with firmware.
Buildroot Output
Sample output from flashing Buildroot to CHIP looks like:
ROOTFS_URL=http://opensource.nextthing.co.s3.amazonaws.com/chip/buildroot/stabl
e/71/images
BUILD=71

BR_URL=http://opensource.nextthing.co.s3.amazonaws.com/chip/buildroot/stable/71
/images

BR_BUILD=71

/home/doge/gits/CHIP-tools/.firmware/images/rootfs.ubi exists... comparing to

http://opensource.nextthing.co.s3.amazonaws.com/chip/buildroot/stable/71/images
/rootfs.ubi

MD5: 90315ca1fb8ff95fc6878ce8126bdf02

S3_MD5: 6d59af4a0f673e1d61147e4a06dd7ba8
md5sum differs

--2015-10-21 15:59:16--

http://opensource.nextthing.co.s3.amazonaws.com/chip/buildroot/stable/71/images
/rootfs.ubi

Resolving opensource.nextthing.co.s3.amazonaws.com

(opensource.nextthing.co.s3.amazonaws.com)... 54.231.176.13
Connecting to opensource.nextthing.co.s3.amazonaws.com

(opensource.nextthing.co.s3.amazonaws.com)|54.231.176.13|:80... connected.
HTTP request sent, awaiting response... 200 OK
Length: 54525952 (52M) [binary/octet-stream]

Saving to: /home/doge/gits/CHIP-tools/.firmware/images/rootfs.ubi

100%[======================================>] 54,525,952
2015-10-21 15:59:45 (1.82 MB/s) - /home/doge/gits/CHIP-

1.83MB/s

tools/.firmware/images/rootfs.ubi saved [54525952/54525952]

in 29s

/home/doge/gits/CHIP-tools/.firmware/images/sun5i-r8-chip.dtb exists...
comparing to

http://opensource.nextthing.co.s3.amazonaws.com/chip/buildroot/stable/71/images
/sun5i-r8-chip.dtb

MD5: de0beb674eeb382901251febfbf1cf9b

S3_MD5: de0beb674eeb382901251febfbf1cf9b
file already downloaded

/home/doge/gits/CHIP-tools/.firmware/images/sunxi-spl.bin exists... comparing

to

http://opensource.nextthing.co.s3.amazonaws.com/chip/buildroot/stable/71/images
/sunxi-spl.bin

MD5: dd3f9c9c0984a6c1d7cdca2921f6f448

S3_MD5: dd3f9c9c0984a6c1d7cdca2921f6f448
file already downloaded

/home/doge/gits/CHIP-tools/.firmware/images/uboot-env.bin exists... comparing

to

http://opensource.nextthing.co.s3.amazonaws.com/chip/buildroot/stable/71/images
/uboot-env.bin

MD5: 6f2b79a781f9f490911012ec3aa653e9

S3_MD5: 6f2b79a781f9f490911012ec3aa653e9
file already downloaded

/home/doge/gits/CHIP-tools/.firmware/images/zImage exists... comparing to

http://opensource.nextthing.co.s3.amazonaws.com/chip/buildroot/stable/71/images
/zImage

MD5: 0d35ad764564a2cee9281715823597a2

S3_MD5: 0d35ad764564a2cee9281715823597a2
file already downloaded

/home/doge/gits/CHIP-tools/.firmware/images/u-boot-dtb.bin exists... comparing

to

http://opensource.nextthing.co.s3.amazonaws.com/chip/buildroot/stable/71/images
/u-boot-dtb.bin

MD5: 97340d221bcbcc8f0bf27e26adc26f0a

S3_MD5: 97340d221bcbcc8f0bf27e26adc26f0a
file already downloaded

BUILDROOT_OUTPUT_DIR = /home/doge/gits/CHIP-tools/.firmware
== preparing images ==

/home/doge/gits/CHIP-tools/spl-image-builder -d -r 3 -u 4096 -o 1664 -p 16384 c 1024 -s 64 /home/doge/gits/CHIP-tools/.firmware/images/sunxi-spl.bin

/tmp/chipflashqVYEIs/sunxi-padded-spl
filesize= 3573504

PADDED_SPL_SIZE=0x000000c6

35+1 records in

36+0 records out

589824 bytes (590 kB) copied, 0.00082507 s, 715 MB/s

12+0 records in

12+0 records out

196608 bytes (197 kB) copied, 0.0176519 s, 11.1 MB/s

Image Name:

flash CHIP

Image Type:

ARM Linux Script (uncompressed)

Created:

Data Size:

Wed Oct 21 15:59:46 2015

736 Bytes = 0.72 kB = 0.00 MB

Load Address: 00000000

Entry Point:
Contents:

00000000

Image 0: 728 Bytes = 0.71 kB = 0.00 MB

== upload the SPL to SRAM and execute it ==

waiting for fel...OK
== upload spl ==

== upload u-boot ==

== upload u-boot script ==

== upload ubi ==

100% [============================================================]
== execute the main u-boot binary ==
== write ubi ==

flashing................OK
login... OK

password... OK
poweroff... OK
Debian Output
Sample output from a successful Debian output:
debian selected

ROOTFS_URL=http://opensource.nextthing.co.s3.amazonaws.com/chip/debian/stable/3
7

BUILD=37

BR_URL=http://opensource.nextthing.co/chip/buildroot/stable/71/images
BR_BUILD=71

/home/doge/gits/CHIP-tools/.firmware/images/rootfs.ubi exists... comparing to

http://opensource.nextthing.co.s3.amazonaws.com/chip/debian/stable/37/rootfs.ub
i

MD5: 6d59af4a0f673e1d61147e4a06dd7ba8

S3_MD5: 90315ca1fb8ff95fc6878ce8126bdf02
md5sum differs

--2015-10-21 16:06:36--

http://opensource.nextthing.co.s3.amazonaws.com/chip/debian/stable/37/rootfs.ub
i

Resolving opensource.nextthing.co.s3.amazonaws.com

(opensource.nextthing.co.s3.amazonaws.com)... 54.231.160.10
Connecting to opensource.nextthing.co.s3.amazonaws.com

(opensource.nextthing.co.s3.amazonaws.com)|54.231.160.10|:80... connected.
HTTP request sent, awaiting response... 200 OK
Length: 245366784 (234M) [binary/octet-stream]

Saving to: /home/doge/gits/CHIP-tools/.firmware/images/rootfs.ubi

100%[======================================>] 245,366,784 1.27MB/s

in 2m 11s

2015-10-21 16:08:48 (1.78 MB/s) - /home/doge/gits/CHIP-

tools/.firmware/images/rootfs.ubi saved [245366784/245366784]

/home/doge/gits/CHIP-tools/.firmware/images/sun5i-r8-chip.dtb exists...
comparing to

http://opensource.nextthing.co/chip/buildroot/stable/71/images/sun5i-r8chip.dtb

MD5: de0beb674eeb382901251febfbf1cf9b

S3_MD5: de0beb674eeb382901251febfbf1cf9b
file already downloaded

/home/doge/gits/CHIP-tools/.firmware/images/sunxi-spl.bin exists... comparing

to http://opensource.nextthing.co/chip/buildroot/stable/71/images/sunxi-spl.bin
MD5: dd3f9c9c0984a6c1d7cdca2921f6f448

S3_MD5: dd3f9c9c0984a6c1d7cdca2921f6f448
file already downloaded

/home/doge/gits/CHIP-tools/.firmware/images/uboot-env.bin exists... comparing

to http://opensource.nextthing.co/chip/buildroot/stable/71/images/uboot-env.bin
MD5: 6f2b79a781f9f490911012ec3aa653e9

S3_MD5: 6f2b79a781f9f490911012ec3aa653e9
file already downloaded

/home/doge/gits/CHIP-tools/.firmware/images/zImage exists... comparing to

http://opensource.nextthing.co/chip/buildroot/stable/71/images/zImage
MD5: 0d35ad764564a2cee9281715823597a2

S3_MD5: 0d35ad764564a2cee9281715823597a2
file already downloaded

/home/doge/gits/CHIP-tools/.firmware/images/u-boot-dtb.bin exists... comparing

to http://opensource.nextthing.co/chip/buildroot/stable/71/images/u-bootdtb.bin

MD5: 97340d221bcbcc8f0bf27e26adc26f0a

S3_MD5: 97340d221bcbcc8f0bf27e26adc26f0a
file already downloaded

BUILDROOT_OUTPUT_DIR = /home/doge/gits/CHIP-tools/.firmware
== preparing images ==

/home/doge/gits/CHIP-tools/spl-image-builder -d -r 3 -u 4096 -o 1664 -p 16384 c 1024 -s 64 /home/doge/gits/CHIP-tools/.firmware/images/sunxi-spl.bin

/tmp/chipflashUooSfo/sunxi-padded-spl
filesize= 3573504

PADDED_SPL_SIZE=0x000000c6
35+1 records in

36+0 records out

589824 bytes (590 kB) copied, 0.00181383 s, 325 MB/s

12+0 records in

12+0 records out

196608 bytes (197 kB) copied, 0.0164913 s, 11.9 MB/s

Image Name:

flash CHIP

Image Type:

ARM Linux Script (uncompressed)

Created:

Data Size:

Wed Oct 21 16:08:49 2015

736 Bytes = 0.72 kB = 0.00 MB

Load Address: 00000000

Entry Point:
Contents:

00000000

Image 0: 728 Bytes = 0.71 kB = 0.00 MB

== upload the SPL to SRAM and execute it ==

waiting for fel...OK
== upload spl ==

== upload u-boot ==

== upload u-boot script ==

== upload ubi ==

100% [============================================================]
== execute the main u-boot binary ==
== write ubi ==

flashing...........................OK
login... OK

password... OK
poweroff... OK

Failure
There are a couple common errors that occur when flashing.
The first is a that CHIP is not in fel mode, ready to receive firmware. There are three possible
reasons for this:

You already successfully flashed CHIP, and havent disconnected the USB cable from your

The jumper wire between Pins 7 & 39 is either not present, loose, or the jumper is in the

computer.

wrong holes.

There is a problem with the USB cable.

Youll know this is the problem when you see this error in the terminal window:
== upload the SPL to SRAM and execute it ==
ERROR: Allwinner USB FEL device not found!
== upload images ==

ERROR: Allwinner USB FEL device not found!

ERROR: Allwinner USB FEL device not found!
ERROR: Allwinner USB FEL device not found!
ERROR: Allwinner USB FEL device not found!
== execute the main u-boot binary ==

ERROR: Allwinner USB FEL device not found!

The other common error is that you need to run the chip-update-firmware.sh script with sudo (or
you need to add a rules file as described in the next section). This error looks like this in your
terminal window:

Image 0: 848 Bytes = 0.83 kB = 0.00 MB

== upload the SPL to SRAM and execute it ==

ERROR: You don't have permission to access Allwinner USB FEL device
== upload images ==

ERROR: You don't have permission to access Allwinner USB FEL device
ERROR: You don't have permission to access Allwinner USB FEL device
ERROR: You don't have permission to access Allwinner USB FEL device
ERROR: You don't have permission to access Allwinner USB FEL device
== execute the main u-boot binary ==

ERROR: You don't have permission to access Allwinner USB FEL device
Option: Flash Without sudo

As a developer, theres a good chance youll flash CHIP more than once in your life. Youll

probably want to follow these steps. In order to be able to run the chip-update-firmware.sh script
without sudo, make a rules file:

sudo touch /etc/udev/rules.d/99-allwinner.rules

and add the content with the tee command:

echo 'SUBSYSTEM=="usb", ATTRS{idVendor}=="1f3a", ATTRS{idProduct}=="efe8",

GROUP="plugdev", MODE="0660" SYMLINK+="usb-chip"' | sudo tee
/etc/udev/rules.d/99-allwinner.rules

then, to make this rules file work: shell sudo udevadm control --reload-rules

Setup Ubuntu For Flashing

If you are running Ubuntu OS on your computer, and dont want to bother with a virtual machine,
you can flash CHIP from your real computer. A generous member of our forums created a script

that duplicates the below steps in a convenient package. You can get it from github. Please note
that this is not supported or maintained by Next Thing - we only link to it here for your potential
convenience.

Requirements

Computer running Ubuntu 14.04+

CHIP

Jumper wire

Install Dependencies
Install some tools:

sudo apt-get update

sudo apt-get install u-boot-tools android-tools-fastboot git build-essential

curl android-tools-fsutils libusb-1.0-0-dev pkg-config

If you get an error that the repository android-tools-fastboot cant be found, you are probably

booting from an Ubuntu Live CD (or USB stick). Youll need to add a repository so you can install
the android-tools-fastboot:

sudo add-apt-repository universe && sudo apt-get update

sudo apt-get install u-boot-tools android-tools-fastboot git build-essential

curl android-tools-fsutils libusb-1.0-0-dev pkg-config

If you intend to customize buildroot with additional software, install these packages:
sudo apt-get install libncurses5-dev libc6-i386 lib32stdc++6 lib32z1

Get and make the fel tools:

git clone http://github.com/NextThingCo/sunxi-tools
cd sunxi-tools
make

sudo rm -f /usr/local/bin/fel

sudo ln -s $PWD/fel /usr/local/bin/fel

Clone the CHIP-tools repository
cd ..

git clone http://github.com/NextThingCo/CHIP-tools

cd CHIP-tools

If you have already cloned the CHIP-tools from a previous CHIP flashing, you can, of course, just
update your existing repository
cd CHIP-tools

git pull http://github.com/NextThingCo/CHIP-tools

Youll also need to add your user to some groups and add a udev rule shell sudo usermod -a
-G dialout $(logname) && sudo usermod -a -G plugdev $(logname) &&

'SUBSYSTEM=="usb", ATTRS{idVendor}=="1f3a", ATTRS{idProduct}=="efe8",

GROUP="plugdev", MODE="0660" SYMLINK+="usb-chip" SUBSYSTEM=="usb",

ATTRS{idVendor}=="18d1", ATTRS{idProduct}=="1010", GROUP="plugdev", MODE="0660"

SYMLINK+="usb-chip-fastboot" SUBSYSTEM=="usb", ATTRS{idVendor}=="1f3a",

ATTRS{idProduct}=="1010", GROUP="plugdev", MODE="0660" SYMLINK+="usb-chip-

fastboot" SUBSYSTEM=="usb", ATTRS{idVendor}=="067b", ATTRS{idProduct}=="2303",

GROUP="plugdev", MODE="0660" SYMLINK+="usb-serial-adapter"' | sudo tee

/etc/udev/rules.d/99-allwinner.rules && sudo udevadm control --reload-rules

Now you are ready to flash CHIP with firmware.
All The Commands At Once
Heres all the commands in one place:
sudo apt-get update

sudo apt-get install u-boot-tools android-tools-fastboot git build-essential

libusb-1.0-0-dev libncurses5-dev libc6-i386 lib32stdc++6 lib32z1 android-toolsfsutils

git clone http://github.com/NextThingCo/sunxi-tools

cd sunxi-tools
make

sudo rm -f /usr/local/bin/fel

sudo ln -s $PWD/fel /usr/local/bin/fel

cd ..

git clone http://github.com/NextThingCo/CHIP-tools

cd CHIP-tools

WiFi Connection

Below are detailed instructions for connecting to Wi-Fi networks using two different command line

protocols: nmcli and connman. If you are using the CHIP OS that comes installed on CHIP, or you
have flashed with our Debian distribution, youll want to use the first section about connecting
with nmcli. If you have flashed CHIP with our buildroot OS, youll need to use connman.

Connecting C.H.I.P. to Wi-Fi with nmcli

There are several tools in Linux for connecting and configuring networks. We will be using the
command nmcli (Network Manager Client). You may see other tutorials that reference iw or

iwconfig, however, these tools are not recommended for C.H.I.P. You can read more about nmcli
on the internet.

Requirements
You will need one of these scenarios:

CHIP with monitor and keyboard attached

Wireless access to internet

SSH or serial connection

CHIP loaded with CHIP OS or Debian

Step 1: List available Wi-Fi networks

In the terminal, type
nmcli device wifi list

The output will list available access points

*
*

SSID

MODE

CHAN

RATE

SIGNAL

BARS

SECURITY

11

54 Mbit/s

100

--

Infra

54 Mbit/s

30

___

WPA1 WPA2

Infra

10

54 Mbit/s

44

__

WPA1 WPA2

NextThing HQ

Infra

NextThing Shop
2WIRE533

Step 2: Connect to a network

You can connect to password -protected or open access points.

A: No Password
To connect to an open network with no password, use this command:
sudo nmcli device wifi connect '(your wifi network name/SSID)' ifname wlan0
These commands will respond with information about the connection.
B: Password Protected
To connect to a password protected network, use this command, inserting your own network name
and password:

sudo nmcli device wifi connect '(your wifi network name/SSID)' password '(your
wifi password)' ifname wlan0

C: Hidden SSID and Password Protected

To connect to a hidden, WPA2-password protected network, use these set of commands, inserting
your own network name and password:

sudo nmcli con add con-name 'mywifi' ifname wlan0 type wifi ssid '(your wifi
network name/SSID)'

sudo nmcli con modify 'mywifi' wifi-sec.key-mgmt wpa-psk

sudo nmcli con modify 'mywifi' wifi-sec.psk '(your wifi password)'

sudo nmcli con up id 'mywifi'
Step 3: Test your Connection
You can verify and test your wireless network connection.
Verify
You can verify your connection using the command
nmcli device status

which outputs a list of the various network devices and their connections. For example, a
successful connection would look like this:
DEVICE

TYPE

STATE

CONNECTION

wlan1

wifi

disconnected

--

wlan0

ip6tnl0
lo

sit0

wifi
ip6tnl

loopback
sit

connected
unmanaged
unmanaged
unmanaged

NextThing HQ
----

Because it is worth knowing that Linux offers many ways of doing things, another command that
shows your current active connection is
nmcli connection show --active
which outputs like so:
NAME
NTC

UUID

59962bac-3441-437b-94ea-bf31dee66e8f

TYPE

802-11-wireless

DEVICE
wlan0

After you have connected once, your C.H.I.P. will automatically connect to this network next time
you reboot (or start NetworkManager services).
Test
Finally, you can test your connection to the internet with ping. Googles DNS server at the IP
address 8.8.8.8 is probably the most reliable computer on the internet, so:
ping -c 4 8.8.8.8
results in output like:

64 bytes from 8.8.8.8: icmp_seq=1 ttl=55 time=297 ms

64 bytes from 8.8.8.8: icmp_seq=2 ttl=55 time=26.3 ms

64 bytes from 8.8.8.8: icmp_seq=3 ttl=55 time=24.8 ms
64 bytes from 8.8.8.8: icmp_seq=4 ttl=55 time=55.7 ms

You can stop this command by pressing CTRL-C on your keyboard. The -c 4 option means it will
happen only 4 times.

Congratulations! You are now network with CHIP!

Step 4: Disconnecting and Forgetting Networks
The command to disconnect from a wireless device needs a few parameters:
sudo nmcli dev disconnect wlan0

You may want to prevent auto-connection to a network, so you can use this command to forget a
network:

sudo nmcli connection delete id

(your wifi network name/SSID)

Troubleshooting
Here are a few possible problems with connections.
No network found
Not much to say about that. If theres no network, you cant connect. Go find a network!

Incorrect password
If you type in the wrong password, youll get some errors like this:
[32258.690000] RTL871X: rtw_set_802_11_connect(wlan0) fw_state=0x00000008
[32258.800000] RTL871X: start auth

[32263.720000] RTL871X: rtw_set_802_11_connect(wlan0) fw_state=0x00000008

[32263.820000] RTL871X: start auth

[32264.430000] RTL871X: auth success, start assoc

[32269.850000] RTL871X: rtw_set_802_11_connect(wlan0) fw_state=0x00000008

[32269.970000] RTL871X: start auth
Error: Timeout 90 sec expired.

Try connecting again with the correct password.

Failed ping
If you dont have access to the internet, your ping to an outside IP will fail. It is possible that you

can connect to a wireless network, but have no access to the internet, so youd see a connection

when you request device status, but have a failed ping. This indicates a problem or restriction with
the router or the access point, not a problem with the CHIP.
A failed ping looks something like:
From 192.168.2.56 icmp_seq=14 Destination Host Unreachable
From 192.168.2.56 icmp_seq=15 Destination Host Unreachable
From 192.168.2.56 icmp_seq=16 Destination Host Unreachable

18 packets transmitted, 0 received, +9 errors, 100% packet loss, time 17013ms

pipe 4

Loss of wireless network

A sudden, unplanned disconnection will post an error in the terminal window, for example:
[30863.880000] RTL871X: linked_status_chk(wlan0) disconnect or roaming

The Network Manager will periodically try to reconnect. If the access point is restored, youll get
something like this in your terminal window:

[31798.970000] RTL871X: rtw_set_802_11_connect(wlan0)

[31799.030000] RTL871X: start auth

[31799.040000] RTL871X: auth success, start assoc

[31799.050000] RTL871X: rtw_cfg80211_indicate_connect(wlan0) BSS not found !!

[31799.060000] RTL871X: assoc success
nmcli not installed error

If you try to use nmcli and you get an error that it is not found or is not a command, chances are
that you are using the CHIP buildroot image. The nmcli commands only apply to CHIPs running
CHIP OS or Debian linux.

Connecting C.H.I.P. to a Wireless Network With connman

The buildroot operating system uses the connman command-line network manager to connect and
manage your network connections. If you are using CHIP OS (or Debian), you will find
that connman is not installed - youll need to use nmcli.

If you want all the details of connman visit the ArchLinux wiki.
Requirements

CHIP running buildroot OS

One of the following:
o
o

Keyboard and monitor for CHIP

Serial connection to CHIP

Step 1: Enable WiFi and Find a Network

These three commands will, in turn, enable wifi, scan for access points, and see what networks are
available:

connmanctl enable wifi

connmanctl scan wifi
connmanctl services

The services command has output similar to:

*AO

NTC

wifi_7cc70905cd77_4e5443_managed_psk

NTC Guest

wifi_7cc70905cd77_4e5443204775657374_managed_psk

ATT312

wifi_7cc70905cd77_hidden_managed_psk

wifi_7cc70905cd77_hidden_managed_none

wifi_7cc70905cd77_415454333132_managed_psk

HP-Print-99-LaserJet 1102

wifi_7cc70905cd77_48502d5072696e742d39392d4c617365724a65742031313032_managed_no
ne

ATT344

CBCI-1B57-2.4

wifi_7cc70905cd77_415454333434_managed_psk

wifi_7cc70905cd77_434243492d314235372d322e34_managed_psk
mi-fi

0024A5D8CF33

wifi_7cc70905cd77_6d692d6669_managed_none

wifi_7cc70905cd77_303032344135443843463333_managed_psk

Twirl-Eco-Events-2.4

wifi_7cc70905cd77_547769726c2d45636f2d4576656e74732d322e34_managed_psk
xfinitywifi

wifi_7cc70905cd77_7866696e69747977696669_managed_none

Step 2: Connect To An Access Point

Unfortunately, connman doesnt use the nice name on the left of the services list. It wants the
unfriendly string on the right, so youll want to get copy and paste ready.
A: No Password
For example, to connect to NTC Guest, which has no password, services shows two choices. We
want the one without hidden in the string. Use the connect command to connect:

connmanctl connect wifi_7cc70905cd77_4e5443204775657374_managed_psk

If your network is not password protected, youll get some output that will indicate a successful
connection, such as:
[

961.780000] RTL871X: rtw_set_802_11_connect(wlan0)

962.080000] RTL871X: auth success, start assoc

[
[
[
[
[
[

962.070000] RTL871X: start auth

fw_state=0x00000008

962.090000] RTL871X: rtw_cfg80211_indicate_connect(wlan0) BSS not found !!

962.100000] RTL871X: assoc success

962.110000] RTL871X: send eapol packet

962.290000] RTL871X: send eapol packet

962.300000] RTL871X: set pairwise key camid:4, addr:0a:18:d6:97:2d:26,

kid:0, type:AES
[

962.320000] RTL871X: set group key camid:5, addr:0a:18:d6:97:2d:26, kid:1,

type:AES

If your network is password protected, youll get an error.

B: Password-Protected
To deal with passwords, youll need to put connman into interactive mode:
connmanctl

which gives a connmanctl prompt:

connmanctl>

In the shell, turn the 'agent on so it can process password requests:

agent on

and now use the connect command (your network name will be different than whats below of
course)

connect wifi_7cc70905cd77_4e5443_managed_psk

and enter your password when prompted:

Agent RequestInput wifi_7cc70905cd77_4e5443_managed_psk

Passphrase = [ Type=psk, Requirement=mandatory ]
Passphrase?

Now that you are connected to a wireless network, you can exit connmanctl interactive mode by
typing

quit
All The Commands In One Place
Heres all the commands in one place:
connmanctl
agent on

connect wifi_7cc70905cd77_4e5443_managed_psk
quit

Step 3: Test Connection

In CHIPs command line, you can ping Google four times:
ping -c 4 8.8.8.8

and expect ping to output some timing messages like:

PING 8.8.8.8 (8.8.8.8): 56 data bytes

64 bytes from 8.8.8.8: seq=0 ttl=55 time=209.147 ms

64 bytes from 8.8.8.8: seq=1 ttl=55 time=111.125 ms
64 bytes from 8.8.8.8: seq=2 ttl=55 time=183.627 ms
64 bytes from 8.8.8.8: seq=3 ttl=55 time=147.398 ms
--- 8.8.8.8 ping statistics ---

4 packets transmitted, 4 packets received, 0% packet loss

round-trip min/avg/max = 111.125/162.824/209.147 ms

If your connection is not successful, then ping will tell you your network is down:
PING 8.8.8.8 (8.8.8.8): 56 data bytes
ping: sendto: Network is unreachable
Troubleshooting Connection Problems

Youll need to make sure you used the right network when you used the connect
commnand.

Review any messages that the connect commnand gave you. Did they look like the

If everything checked out until you got to ping, theres a good chance the problem is with

examples of a successful connection?

your router or connection to the internet.

connman not installed error

If you try to use connman and you get an error that it is not found or is not a command, chances
are that you are using the CHIP OS or Debian image. The connman commands only apply to
CHIPs running the simple buildroot OS.

Step 4: Disconnecting And Forgetting Networks

To disconnect from your network, you might first want a reminder of what unfriendly string is used
to describe your access point, so type:
connmanctl services

which will output information about your current link:

*AO NTC

Use the ID to disconnect:

wifi_7cc70905cd77_4e5443_managed_psk

connmanctl disconnect wifi_7cc70905cd77_4e5443_managed_psk

and youll get some status like this:

[

301.890000] RTL871X: clear key for addr:0a:18:d6:97:2d:26, camid:4

301.920000] IPv6: ADDRCONF(NETDEV_UP): wlan0: link is not ready

301.900000] RTL871X: clear key for addr:0a:18:d6:97:2d:26, camid:5

Disconnected wifi_7cc70905cd77_4e5443_managed_psk

Generally, conman will remember and cache setup information - if you reboot in the vicinity of a

known network, it will attempt to connect. However, if you need to forget a network setup, these
setups can be found by navigating:
cd /var/lib/connman/

You can delete a single connection by seeing what connections are stored
ls /var/lib/connman/

and then delete a setup that you find, for example

rm -r wifi_7cc70905cd77_4e5443_managed_psk

You can delete all the wifi directories with

rm -r wifi*

(the -r is needed because these are directories you are deleting, and the star at the end
of wifi* assumes your configurations all start with the string wifi)
For Advanced Users
Its worth noting that youll see two wireless networking interfaces if you list them with
ifconfig

connman is configured to see only the physical interface wlan0 which simplifies setup. We do this
with a blacklist, which can be modified at /etc/connman/main.conf

Configure Sound Output on Debian

Getting simple audio playback working on CHIP is pretty easy, once you install the correct

packages and enable audio output. In the code examples below, weve inserted the && characters
at the end of lines so you can copy and paste the entire block into a terminal window and execute
each line in series. If you are using CHIP OS, sound output is already configured and working.

However, you may be running a simple version of Debian or buildroot, so these instructions will
help you get sound working on CHIP.

Requirements

CHIP

Monitor and keyboard

SSH or serial connection to CHIP or

Headphones or powered speakers connected to CHIP a/v jack
Connection to a network

Setup CHIP

Update your apt repository list if you havent done so recently:

sudo apt-get update

Then install ALSA:

sudo apt-get install libasound2 alsa-utils

This will install alsa and some utilities for playing sound from the command line. Once those have
installed, youll need to make the outputs active for sound
alsamixer

will open up a simple interface. Use the left and right arrow keys on your keyboard to select among
the items, and use the up/down keys to change the options:

DAC Output - set to Direct

PA - set to desired volume

Left Mixer - set to Left

Right Mixer - set to Right

Play a Sound

Change to the root media directory:

cd /media

Alternatively, you could download a sound into chips home directory:

mkdir /home/chip/Media && cd /home/chip/Media

Use wget to download a sound of piano chords to the file test.wav:

wget -O test.wav

https://upload.wikimedia.org/wikipedia/commons/d/db/Descending_thirds.wav
If wget returns command not found you can install it:
sudo apt-get install wget

We can finally play the sound and hear it over CHIPs headphone jack:
aplay test.wav

If you want to play mp3 or ogg files, you can install mplayer:
sudo apt-get install mplayer

Then try an ogg file:

wget -O test.ogg

https://upload.wikimedia.org/wikipedia/commons/e/e7/Agogo.ogg &&
mplayer test.ogg

And mp3 file:

wget -O test.mp3 http://www.freesound.org/data/previews/315/315618_2050105-

lq.mp3 &&

mplayer test.mp3

Record A Sound

If you want to try the audio input, you need to connect audio input to header U14, pins 06 &

12 or modify CHIP to use audio in on the TRRS connector. Once you have an audio signal going
into CHIP, you can test it out by recording a three second (-d 3) WAV file with arecord:
arecord -f cd -d 3 -D hw:0,0 chipaudioin.wav

More Packages

Developers that want to use sound will probably want to download these packages:
sudo apt-get install portaudio19-dev &&
sudo apt-get install swig &&

sudo apt-get install python-setup-tools &&

sudo apt-get install python-dev

USB Storage Devices

In this tutorial, well describe how you can use the USB port to add more storage with a thumb

drive, hard drive, card reader, or whatever else. You can then copy, store, and edit files on the
storage device, extending the capability of CHIP.

This tutorial is suitable for the buildroot image. If you are following this for other Linux distributions,
there are some adjustments that youll need to make for paths, permissions, and enabling 'sudo.
With buildroot, you work as the root user, so this tutorial is appropriately terse.

Requirements

USB thumb drive or hard drive

Computer running OS X 10.10+, Ubuntu 14.04+, or Windows 7+ (to format USB device, if
needed)

Step 1: Format the Drive

First, youll want to format the drive as an MS-DOS (FAT), NTFS, or ext3 volume. You can do this
on another computer.

Once formatted, insert the drive into CHIPs USB port. Enter the command
dmesg

Youll get output like:

[ 4953.430000] usb 1-1: new high-speed USB device number 2 using ehci-platform
[ 4953.580000] usb-storage 1-1:1.0: USB Mass Storage device detected
[ 4953.590000] scsi host0: usb-storage 1-1:1.0

[ 4954.590000] scsi 0:0:0:0: Direct-Access USB Flash Memory 1.00 PQ: 0 ANSI: 2

[ 4954.600000] sd 0:0:0:0: [sda] 3911616 512-byte logical blocks: (2.00 GB/1.86

GiB)

[ 4954.610000] sd 0:0:0:0: [sda] Write Protect is off

[ 4954.620000] sd 0:0:0:0: [sda] Mode Sense: 65 44 09 30

[ 4954.630000] sd 0:0:0:0: [sda] No Caching mode page found

[ 4954.630000] sd 0:0:0:0: [sda] Assuming drive cache: write through

[ 4954.650000] sda: sda1

[ 4954.650000] sd 0:0:0:0: [sda] Attached SCSI removable disk

Notice the second to last line. This tells you the device location for the drive. Storage devices
generally have device names that start with sd. If you want to see all the storage devices
attached to CHIP, you can use a wildcard to display all devices that start with sd:
ls /dev/sd*

and youll get something like:

/dev/sda /dev/sda1

With one thumb drive attached, it appears as two devices: the device itself (sda), and the storage
partitions (sda1). There is only one partition on this drive.
Another way to find storage devices is the command
blkid

which lists them, along with the names you might have initialized them with:
/dev/sda1: LABEL="TEST" UUID="6668-11E9"

Step 2: Mount the Drive Device to Your Filesystem

Now that you know where your partition is, its time to mount the partition so you can access the
files.

First, make a directory where your drive can mount:

sudo mkdir /drives

Mount the drive device to your /drives directory:

sudo mount /dev/sda1 /drives

Now you can navigate to the drives directory and see all the files in the drive:
cd /drives
ls

Step 3: Unmount the Drive From Filesystem

If you want to remove the drive from the USB port on CHIP, its best to unmount it:
sudo umount /dev/sda1

Step 4: Automatic Mounting on Boot

Youll probably want to mount this drive automatically next time you use it, though. We can set that
up with a quick modification to the fstab (file system table) document:
vi /etc/fstab

Getting around vi is not very intuitive. If you are new to it, heres a quick guide on getting this text
into the fstab document:

'arrow key to the end of the file,

type (or copy-paste) this:

press the 'i key to insert text

/dev/sda1 /drives vfat defaults 0 0

To exit vi,

press the 'esc key,

type 'wq to write and quit vi.

type : (colon),

You can test your work with:

mount -a

If theres an error, double check the fstab file and make sure it has the line /dev/sda1 /drives
vfat defaults 0 0 at the end. If its successful, youll be able to view, modify and copy the files
on the disk:

ls /drives

Now, if you reboot , the drive will mount automatically. If you remove the drive, then insert it again,
youll need the command

mount -a

Connecting Bluetooth Devices

CHIP has built-in Bluetooth and uses the bluez 5 stack for implementing connections and devices.
This tutorial instructs how to use a Bluetooth keyboard, since it is a simple and obvious example.
There are, of course, several types of Bluetooth devices, such as earpieces, audio connectors,
vacuum cleaners, and more. Future tutorials (search our bbs will cover those devices, but the
keyboard is a good introduction to the commands and an easy way to test your system.

Requirements

CHIP

Monitor and keyboard

SSH or serial connection to CHIP or

Bluetooth device, preferably keyboard

Important!

Start with a CHIP completely unplugged and powered down. Add power and boot up. A known
limitation is that after reboot, CHIPs Bluetooth controller may not work until you power and
physically disconnect from a power source.

About bluetoothctl

Well be using the command bluetoothctl to find, pair with, and connect to devices.
In the terminal, type
bluetoothctl

This starts up bluetoothctl in interactive mode. You should see output like
[NEW] Controller 7C:C7:08:05:CD:77 BlueZ 5.27 [default]
[NEW] Device 60:33:4B:13:A7:45 nyb

[NEW] Device 15:03:26:A0:26:26 SK032B02-2626

which is a list of MAC addresses of CHIPs Bluetooth controller chip (the first line) and any other

devices that have been paired with CHIP in the past. Use the help command - it lists all the very
useful commands in the bluetoothctl interactive mode.
In Bluetooth interactive mode, use the command
power on

which outputs

Changing power on succeeded

[CHG] Controller 7C:C7:08:05:CD:77 Powered: yes

Find A Bluetooth Device

If you need to discover a device, start the scan process:

scan on

which will start printing MAC addresses and names (if available) of Bluetooth devices in your
vicinity.

[NEW] Device 15:03:26:A0:26:26 SK032B02-2626

[NEW] Device 1C:1A:C0:85:5E:2C 1C-1A-C0-85-5E-2C

[NEW] Device 60:33:4B:13:A7:45 nyb

Pair With A Bluetooth Device

Pair to a device with the MAC address and the pair command:
pair 1C:1A:C0:85:5E:2C

This may fail if the device is powered off, goes out of range, or your toddler spills water on it.
Heres what failure looks like:

Attempting to pair with 1C:1A:C0:85:5E:2C

[CHG] Device 1C:1A:C0:85:5E:2C Connected: yes

[CHG] Device 1C:1A:C0:85:5E:2C Connected: no

Failed to pair: org.bluez.Error.AuthenticationCanceled

As the scan continues, youll eventually see the device you are interested in, so copy that MAC
address and type:

pair 15:03:26:A0:26:26

with output like:

[CHG] Device 15:03:26:A0:26:26 Connected: yes

[CHG] Device 15:03:26:A0:26:26 Modalias: usb:v05ACp3232d0001

[CHG] Device 15:03:26:A0:26:26 UUIDs:
00001124-0000-1000-8000-00805f9b34fb
00001200-0000-1000-8000-00805f9b34fb

[CHG] Device 15:03:26:A0:26:26 Paired: yes

Pairing successful

[CHG] Device 15:03:26:A0:26:26 Connected: no

Pair with a Bluetooth Device with Password (keyboard)

Some Bluetooth devices need user input to pair. In that case, youll need to turn the agent 'on so
the device can post a password, and you can enter it:

agent on

will output

Agent registered

now you can pair it:

pair DC:2C:26:D7:B6:8F

will output

Attempting to pair with DC:2C:26:D7:B6:8F

[CHG] Device DC:2C:26:D7:B6:8F Connected: yes

[agent] PIN code: 245261

Now you can use the Bluetooth device to enter the PIN code, then hit enter. The terminal will give
some status about the pairing:

[CHG] Device DC:2C:26:D7:B6:8F Modalias: usb:v05ACp022Cd011B

[CHG] Device DC:2C:26:D7:B6:8F UUIDs:

00001000-0000-1000-8000-00805f9b34fb
00001124-0000-1000-8000-00805f9b34fb
00001200-0000-1000-8000-00805f9b34fb

[CHG] Device DC:2C:26:D7:B6:8F Paired: yes

Pairing successful

[CHG] Device DC:2C:26:D7:B6:8F Connected: no

Now that you are paired, you will have to connect.

Connect With A Bluetooth Device

Now that you have paired the Bluetooth device, you wont have to do that again. However, the
device still needs to be connected:
connect 15:03:26:A0:26:26

will output, when successful:

Attempting to connect to 15:03:26:A0:26:26

[CHG] Device 15:03:26:A0:26:26 Connected: yes

Connection successful

[bluetooth]## [ 1405.340000] hid-generic 0005:05AC:3232.0001: unknown main item

tag 0x0

[ 1405.360000] input: SK032B02-2626 as

/devices/platform/soc@01c00000/1c28c00.serial/tty/ttyS1/hci0/hci0:4/0005:05AC:3
232.0001/input/input1

[ 1405.380000] hid-generic 0005:05AC:3232.0001: input: BLUETOOTH HID v0.01

Mouse [SK032B02-2626] on 7c:c7:08:05:cd:77

or, if the device is not available, it will fail:

Attempting to connect to 15:03:26:A0:26:26

[bluetooth]## [ 1304.470000] Bluetooth: HIDP (Human Interface Emulation) ver

1.2

[ 1304.480000] Bluetooth: HIDP socket layer initialized

Failed to connect: org.bluez.Error.Failed

Trusting a Bluetooth Device

Trust between people leads to understanding and perhaps even harmonious living. Trust between

bluetooth devices means that you wont have to connect the device every time its near. Which is a
sort of harmony, I suppose. Once you have connected a bluetooth device to CHIP, if you intend to
use it again, you can trust it:

trust 15:03:26:A0:26:26

Remove a Bluetooth device

You may want CHIP to not pair or connect to a device - perhaps the conveniently trusted device
needs to be freed for another connection. Whatever the reason, if you want to remove your
Bluetooth device,

remove 15:03:26:A0:26:26

Troubleshooting

If your Bluetooth controller module on CHIP is not functioning, you can easily find the problem.
Type

bluetoothctl

to get into the interactive mode, then type

power on

If you get the response

No default controller available

Then theres a problem with CHIP recognizing the Bluetooth module. Read the very first
instructions at the top of this tutorial.

Install X-windows

If you want a windowed desktop on C.H.I.P., you can install X-Windows.

Requirements

CHIP connected to WiFi

Keyboard or Serial or SSH Connection to CHIP

Monitor attached to CHIP

Installation (xfce4)

CHIP is a lightweight computer, so well install the lightweight xfce4:

sudo apt-get install xfce4

It might take some time to download and install all the packages, since there are a lot of

dependencies and libraries involved. Once installed, start the windowing system with the command
startx&

(the & runs Xwindows in the background, so you can still use your terminal). After a minute or so,
youll get an image on the monitor:

Now you can use a mouse and keyboard to explore CHIP and launch programs.

Troubleshooting

If you get errors from apt that report unmet dependencies, you can run the command
sudo apt-get install -f

which will force installation of any alternate or missing dependencies of any installed packages.

Building and Installing PureData (PD) on CHIP

PureData is a graphical programming environment, primarily for making audio and multimedia
applications. This tutorial describes how to build the vanilla version of PD. This is a very

rudimentary version of PD - it does not compile or build the extras objects, such as bob~ or
expr~.

Get Source

First, download and un-archive the source from Miller Puckettes website:
wget http://msp.ucsd.edu/Software/pd-0.46-7.src.tar.gz
gzip -d pd-0.46-7.src.tar.gz
tar -xvf pd-0.46-7.src.tar

Install Dependencies

Now, youll need to install all the dependencies and make a symbolic link to wish:
sudo apt-get update

sudo apt-get install libasound2 alsa-utils mplayer software-properties-common

git autoconf libtool make

build-essential gettext portaudio19-dev

libasound-dev qjackctl jackd2 tcl8.6 tk8.6 unzip

jack

sudo apt-get build-dep puredata

sudo ln -s /usr/bin/wish8.6 /usr/bin/wish

Navigate to the pd directory the archive created:
cd pd-0.46-7

Build It

Youre ready to go ahead and build, running some scripts, then making the install:
cd ~/pd-0.46-7/
./autogen.sh

./configure --disable-portaudio --disable-portmidi --no-recursion

make

sudo make install

Youll probably also want the extra objects such as expr, expr~, clone, fiddle~, bonk~, bob~,

sigmund~, et al. These require an extra build step. The extra folder is in pd-0.46-7/extra, so if
you are still insrc/ you can

cd ../extra

make install

Youll probably also want to install the deken plugin so you can add more externals to your bag of
tricks: https://github.com/pure-data/deken

Ive also found this kiosk plugin to be very handy for making a pure data widow take up the entire
screen: https://puredata.info/downloads/kiosk-plugin

Set Up Priority

Now set up pd so it can run in real-time priority mode for low latency (launching with pd -rt). This
is mostly about giving audio the necessary thread priority and giving the chip user access:
sudo nano /etc/security/limits.conf

Navigate to the end of the file (CTL-V) and add the lines
@audio - rtprio 99

@audio - memlock unlimited

and save (CTL-X to exit, youll be prompted to save) Youll want to double check that
the chip user is in the audio group:
sudo adduser username audio
Then reboot CHIP:
sudo reboot

Test PD

Now test pd with a test patch. Open a terminal and use this command, which should result in a
sine wave:

wget http://log.liminastudio.com/wp-content/uploads/2012/06/testPatch.pd_.zip
unzip testPatch.pd_.zip

pd -rt -nogui -noadc -alsa testPatch.pd

Test MIDI Controller

If you need to test out a midi controller to make sure data is coming into CHIP, you can do this

from the terminal. Youll want to list the connected devices, if not just to get the port name as ALSA
sees it.

amidi -l

Example output might look like shell Dir Device Name IO hw:1,0,0 DS1 MIDI 1
You can then use the command to display MIDI data bytes (in hex) in the terminal window:

amidi -p hw:1,0,0 -d

Moving a fader might provide output like:

B0 29 1D
B0 29 20
B0 29 24
B0 29 29
B0 29 2E
B0 29 32
B0 29 37
B0 29 3A
B0 29 3C

Uninstall

If you need to remove pd, it takes a few steps:

sudo apt-get remove puredata-core

sudo apt-get remove puredata-dev puredata-import puredata-utils

sudo apt-get purge puredata-core

sudo apt-get install aptitude wget unzip

sudo apt-get autoremove

Run PD

Start PD from the terminal with the command

pd -rt &

You can then use the mouse and keyboard to go through the Browser and learn more about PD.

References

Here are some reference links

real time priority mode

pure data on sourceforge

low latency alsa

pd extended on RPi

Headless CHIP

One of the most amazing features of CHIP is that its insanely simple to use it as small, wireless

computer. Low power requirements, battery powered with charge management, and both WiFi and

Bluetooth connectivity makes CHIP easy to run as a headless, autonomous machine. Of course,

youll still want to access it and control it without a monitor or keyboard. You can control CHIP with
another computer and a serial or network connection. Heres how you do this.

Begin

If you want to use CHIP without a monitor or keyboard attached, theres a few ways to do this:

Serial connection with USB to UART cable

Secure Shell (SSH) over wireless or wired ethernet

Serial connection with USB cable

Requirements

Computer running OS X 10.10+, Ubuntu 14.04+, or Windows 7+

Monitor and keyboard (somewhat optional, though handy)

CHIP

Connection to the network

SSH

SSH (or Secure Shell) is a common way to control a computer remotely over a network. Youll
need to first get your computers network name or IP address before you can connect.
How to get your IP address.
The easiest way to get CHIPs IP address is to hook up a monitor and keyboard. Bootup, log
in, connect to the network if you need to, and use the command
hostname -i

which results in your IP address, which might look like this:

10.1.1.99

If the hostname -i command doesnt work you can use

ip addr show dev wlan0

which will output a lot of data. Look for the line wlan0 and the entry inet, something like:
inet 10.1.1.99
Connect to CHIP over a network
Now that you know your IP address, use the command:
ssh [email protected]

Youll be asked for CHIPs password. The default password is chip. This process is the same if
CHIP is connected to the network using built-in wireless or a USB-Ethernet adapter.
Make Connections To CHIP Easy
You may want to setup your network so it will always provide the same (static) IP address to CHIP.
You can then rely on CHIP always having the same IP address.

Alternatively, you can setup zero configuration networking to give your CHIP an easily
remembered name.

You are now free to do whatever it is you do with Linux command line on CHIP.

USB to UART Serial Connection

There are a few reasons youd want to use a serial connection:

No wireless network

Dont know the IP or network name of CHIP

No USB-ethernet cable

Youre old-school and like it

Connect a USB to UART cable to the Ground (GND), Transmit (TX), and Recieve (RX) pins on
CHIP

Well find those on header U14, pin outs 1,3 and 5. See the following diagram, which assumes
CHIPs USB ports are pointed up

About the Cable

If you need a connector, search your favorite shop for USB to UART cable - any will do.
Heres the one we bought. Most of them will have a USB A plug for your computer on one end and
four wires (red, green, black, and white) with female header pins on the other.

You may find other USB-UART cables that have more wires. There will be some labels that will

help you connect to the correct pins (GND, TX, RX) on terminal U14. Just be sure to check your
datasheets to make sure youre using the correct pins.
Install the driver
For this tutorial, we are using a PL2303 USB to Serial cable. If you are using this one too, youll
probably need to install the PL2303 driver for your computer.
Connect the Cable
You only need to worry about three of the wires:

Black = Ground (GND)

White = Transmit (TX)

Green = Receive (RX)

The red wire carries voltage (+5 V). DO NOT USE THE RED ONE. Plugging in a +5 V pin could
damage your CHIP

Again, there is a chance your USB to UART cable may be different. Please check your data
sheets!

This is what our cable looks like plugged in:

USB On The Go Serial Connection

Simpler than the UART cable, you can connect to CHIP with a USB cable to your computer. Your

computer will see CHIP as a serial device as well as provide power to the CHIP. Either way, youll
be able to continue with the directions below.

Control CHIP Using a Serial Terminal

Once youve connected CHIP to your computer with the UART or USB cable, open up a terminal.
Theres lots out there. Heres a few:

OS X: Zterm, screen (built-in to OS X terminal)

Linux: screen, cu

Windows: PuTTy or cygwin

No matter the software, youll need to set some settings for the port (aka connection). Youll
probably only need to set the baud rate, as the others will be defaults:

Baud Rate (Data Rate): 115200

Parity: none

Data Bits: 8
Stop bits: 1

Flow control: none

Using screen
If you are using screen, the command will look something like this:
screen /dev/tty.usbserial 115200
or

screen /dev/ttyUSB0 115200

What comes after the /dev/ may vary among different systems and connections. You can narrow
down the choices by using the command
ls /dev/tty*

to list the serial devices.

Now power up CHIP. You could do this at anytime, but youll have the most reliable experience
powering CHIP after connecting the USB-UART wires. If you make the serial connection after

booting chip, youll probably need to hit 'return on your keyboard a few times to get CHIP to send
some data to you and print in your terminal.

Youll then be prompted for login. Defaults are username root and password chip.
You are now free to do whatever it is you do with Linux command line on CHIP.
Using PuTTy
If you are on Windows using PuTTy, youll probably want to open the windows Device Manager to
get the COM name for the serial port. The device wont show up in the Ports list until after the
kernel loads and presents the device, so it may take a minute or so before Windows actually
detects it.

In the PuTTy configuration panel, you can now use the COM name to set it up. In this case, its
COM4:

Press Open to open a terminal window ,where you can log in to CHIP with username and
password chip.

You are now free to do whatever it is you do with Linux command line on CHIP.

Zero Configuration Networking

You can make working with CHIP on a local network much more convenient by installing zero-conf
networking. OS X users may know this as Bonjour.

With zero-conf properly configured, your CHIP can be contacted using a name, such

as chip.local, rather than an IP. This is especially convenient, if you are moving CHIP to

different networks that might assign different IP addresses. The key technology for this in Linux is

the avahi set of tools. There are a few related packages, but this tutorial is a minimal installation to
get it up and running.

Requirements

CHIP

Monitor and keyboard

SSH or serial connection to CHIP or

Connection to a network

Install avahi

Getting avahi running is extremely simple. First, install the avahi-daemon:

sudo apt-get install avahi-daemon

to install the necessary libraries. You may want to configure the daemon with this service file so
you can find Apple Bonjour devices from CHIP :

sudo nano /etc/avahi/services/afpd.service

Then just copy and paste this XML into it:

<?xml version="1.0" standalone='no'?><!--*-nxml-*-->

<!DOCTYPE service-group SYSTEM "avahi-service.dtd">
<service-group>

<name replace-wildcards="yes">%h</name>
<service>

<type>_afpovertcp._tcp</type>
<port>548</port>
</service>

</service-group>

Then restart avahi-daemon:

sudo /etc/init.d/avahi-daemon restart

You can now find the hostname that you can use to reach CHIP:
hostname

which will probably return chip as the hostname.

Use Zero-Conf

From a terminal on another computer you can try accessing CHIP with the network
name chip.local

ssh [email protected]

and enter the password (default is chip). Thats it. You can now reach CHIP without knowing the
IP.

Change the hostname

If you have more than one CHIP on the network, or you just want to change the name from chip

to fit into your network name scheme, you can modify the hostnames file. Open the file in an editor:
sudo nano /etc/hostname

where youll see a single word chip. Just modify that line (for example, change it to

bobofettywap) and save the file. Youll also need to modify the hosts file where youll need to
change the first line127.0.0.1 chip where you replace chip with your new username.
sudo nano /etc/hosts

Finally, to get this new name to broadcast over the network restart avahi-daemon:
sudo /etc/init.d/avahi-daemon restart

You can now access chip with the new name:

ssh [email protected]

Other packages

You may want to explore some of the other features of avahi, such as browsing a network for other
zero-configure enabled computers. Theres a package you can install:
sudo apt-get update &

sudo apt-get install avahi-utils

which gives you a set of tools for browsing the network, such as the command
avahi-browse -d local _ssh._tcp --resolve -t

which will list other zero-configure-enabled devices on the local network. You could ssh to your
Macintosh named bananna, for example with
ssh username@bananna

An alternative to just installing the avahi-daemon, you can

sudo apt-get install libnss-mdns

which installs some other tools for network name propagation.

Troubleshooting

If your computer returns the error

ssh: Could not resolve hostname chip.local: nodename nor servname provided,

or not known

then you either need to wait a minute or try installing avahi-daemon again, but pay closer attention
to any errors that apt-get returns.

If you cant connect to CHIP even though you are sure avahi is properly configured, confirm that

your CHIP and the computer you are trying to connect are on the same local network (and on the
same subnet).

FAQs
Frequently Asked Questions

Do I need to install something for CHIP to be a computer?

No. CHIP comes preinstalled with the CHIP Operating System and several applications. Just
power on, and get started.

Why composite video?

Several reasons:

Televisions are the most commonly available screen in the world and the vast majority of

Composite video can be integrated without adding licensing fees to the cost of C.H.I.P.

them have a composite input.

Composite is a very low profile connector, allowing us to keep the footprint of the board
small for people wanting to build C.H.I.P. into projects.

Is CHIP an exposed circuit board?

Yes! Not having a case for C.H.I.P. is one of the ways we are able to keep our costs down. As
makers, were excited to introduce people to the physical components of computers and show

them that electronics arent scary, theyre fun! We hope to spark curiosity and encourage people to
begin tinkering themselves.

What resolution can CHIP function at?

With the VGA and HDMI adapters, C.H.I.P. is designed to work at 720p resolution, though the Mali
400 GPU is technically capable of up to 1080p outputs. The composite video connector operates
at the SD resolution of 640x480.

How is CHIP so cheap?

QUANTITY. Our partners at Allwinner worked hard to help us find how to reduce costs, so we
could introduce C.H.I.P. to EVERYBODY. To sell C.H.I.P. for $9, we need to order tens of

thousands of chips. By using common, available, and volume-produced processor, memory, and
wifi chips, we are able to leverage the scales at which tablet manufacturers operate to get
everyone the best price.

What does CHIP stand for?

Were curious to hear what you think ;)

Is CHIP open source? Where are the docs?

YES! Very open source! We are still in the process of testing and refining the whole C.H.I.P. family.
As we hit design completion, well release our design files. Weve already released quite a bit!
Check them out at our GitHub repo!

Can I upgrade CHIPs RAM/Storage/Processor?

Technically, yes, but the components are soldered on and not intended to be swapped out. If you
really like reworking small BGA and fine pitch components, though, we wont stop you. :)
If you want additional storage, you can attach a USB drive!

How many accessible pins does CHIP have?

Eight digital GPIOs, one PWM pin, SPI, TWI (I2C), UART, USB, CSI, Parallel LCD output,

touchpanel input, stereo audio out, mono audio in, composite video out, and a whole bunch of
power rails in and out.

The most up-to-date information is on our GitHub repo.

Can I make my own adapter board?

Absolutely! The schematics and layout for the boards, both of C.H.I.P. and C.H.I.P.s adapters will

be released as they are finalized for production. From that, you can build whatever sort of adapters
or add-ons you want!

Does the HDMI adapter have HDMI audio output?

Not at this time. Because there is no onboard digital audio support from our processor, C.H.I.P.s

current design only has analog audio output via the headphone/composite jack. Adding a USB
sound card is the easiest way to beef up your CHIPs digital audio output options.

Does Linux come pre-installed?

YES! C.H.I.P. comes with Linux installed, and a selection of our favorite programs and games. Like
any real computer, you can download more software and customize C.H.I.P.s applications and
operating system to suit your needs!

Can I plug in a Keyboard, Mouse, AND Power?

The easiest way to accomplish this is to power C.H.I.P. as usual via the microUSB port. Attach a
USB keyboard with an accessory USB port on it, then connect your wired mouse to that port.
Alternatively, a bluetooth keyboard or mouse can be used to free up the need for USB
connections.

For more advanced use cases, C.H.I.P. can be powered via its interconnects, leaving both the full
size USB and microUSB ports available to attach devices to.

Can I stream Netflix?

Due to a lack of support for Silverlight (the back-end software that allows Netflix to be streamed) in

Linux, it is unlikely that Netflix will work on C.H.I.P. using entirely open-source software. This would
require someone to come up with an alternate back-end. That said, some very astute backers
have reported that Netflix should be possible by installing the Google Chrome browser, which
allows Netflix streaming via HTML5.

Does CHIP have a power switch?

Yes! C.H.I.P. has a tiny power on-off button and a status LED on the board itself.

Can I make a supercomputer by linking 100 CHIPs

together?

Were focused on individual uses of C.H.I.P. but what youre talking about is called clustering, and

may be possible A good place to start, if youre interested in clustering, is reading up on DebianBeowulf

What about a camera?

C.H.I.P. has exposed CSI pins on its headers for integrating a camera directly to the processor, or
if drivers and sensor tuning sound like a bit much, you can always add a USB camera too.

How do I connect a display?

You can connect a display through the 3.5mm () TRRS composite video port on C.H.I.P. If youd

like to connect to a vga or hdmi monitor, we have adapters available for that! You can also connect
any parallel LCD to the exposed display pins on C.H.I.P.s headers.

Does CHIP have an SD card slot?

No. But by integrating reliable storage onto the device, were able to both save you a getting

started cost and allow Linux to come preinstalled on C.H.I.P. meaning its ready to go when it

arrives at your door. One of the big goals of this project is making C.H.I.P. easy to use, and this
goes a long way towards that end. If you need additional storage, its easy to add an SD card
reader or other USB storage with the built-in USB port.

Can I connect to composite video AND audio out at the

same time?

YES! The 1/8" mini (TRRS) jack can be used either with a video-only cable, audio only cable,

headphones, headphones with mic, OR a combined Audio/Video composite cable. Pretty versatile
little port, isnt it!?

What software does CHIP ship with? What programs can it

run?

C.H.I.P. comes pre-loaded with some of our favorite open-source applications, and the ability to
install hundreds more. Whats even more exciting, though, is that if any given program isnt

supported out of the box, the community can work together to make it happen. Thats what we <3
about Open Source Software.

What programming languages does CHIP support?

C.H.I.P. is a real computer, and can run software written in all kinds of programming languages,
so long as theres a compiler for them. Python, Java (via JDK8), Ruby, PHP, Squeak, C++, JS,
Assembly, BF.. even our favorite, ArnoldC, and lots lots more.

Does CHIP have Real Time Clock?

No, but adding an RTC is a great (and easy) hardware hack, for the folks that need it. For most

people, though, an RTC isnt necessary since it is easy to get C.H.I.P. to pull time from a remote
NTP server over wifi.

What voltage are GPIOs?

CHIP uses 3V3 digital logic on GPIOs.

What connector is used on the battery?

We are using a JST-2.0 PH 2-pin shrouded male connector to connect LiPo cells to C.H.I.P. In the
current design there are also BATT pins available on the interconnect headers, which allow
alternate battery connectors/placements when attaching C.H.I.P. to a custom PCBA.

I want to know more about the Allwinner R8 processor!

You can find out more from the Allwinner R8 User Manual and the R8 Datasheet

What kind of battery can I use with CHIP?

Any single-cell (3.7V) LiPo battery will work with C.H.I.P. You can go bigger or smaller than
3000mAH as needed for your project!

Does CHIPs WiFi support AP mode?

YES!

Does C.H.I.P. have an ethernet port?

No. But it does have built-in 802.11b/g/n wifi. But if you like wires, you can use a USB-Ethernet
connector.

Does C.H.I.P. come with a banana?

C.H.I.P. is strictly B.Y.O.B. ;)

Is there a command that lets me know more about the CPU

and Memory?

Its a computer! It will tell you anything. If you want to find out more details about CHIPs processor,
use the command:

cat /proc/cpuinfo

This will give output similar to:

processor

: 0

BogoMIPS

: 1001.88

model name
Features

: ARMv7 Processor rev 2 (v7l)

: half thumb fastmult vfp edsp neon vfpv3 tls vfpd32

CPU implementer : 0x41

CPU architecture: 7
CPU variant : 0x3
CPU part

: 0xc08

CPU revision

: 2

Hardware

: Allwinner sun4i/sun5i Families

Serial

: 162542c10c427777

Revision

: 0000

If you want know more about the memory:

cat /proc/meminfo

with output something like:

MemTotal:

507108 kB

MemAvailable:

382592 kB

MemFree:
Buffers:

298600 kB
0 kB

Cached:

92216 kB

Active:

98752 kB

Active(anon):

73180 kB

SwapCached:
Inactive:

Inactive(anon):
Active(file):

Inactive(file):
Unevictable:
Mlocked:

HighTotal:
HighFree:
LowTotal:
LowFree:

SwapTotal:
SwapFree:
Dirty:

Writeback:
AnonPages:
Mapped:
Shmem:

0 kB

64096 kB
5812 kB

25572 kB
58284 kB
0 kB
0 kB
0 kB
0 kB

507108 kB
298600 kB
0 kB
0 kB
0 kB
0 kB

70660 kB
37768 kB
8360 kB

Slab:

22784 kB

SUnreclaim:

11224 kB

SReclaimable:
KernelStack:
PageTables:

NFS_Unstable:

11560 kB
1176 kB
2240 kB
0 kB

Bounce:

WritebackTmp:

0 kB
0 kB

CommitLimit:

253552 kB

VmallocTotal:

507904 kB

Committed_AS:
VmallocUsed:

VmallocChunk:

615216 kB
14560 kB

482532 kB

Troubleshooting
CHIP Wont Boot or Startup

Problem: I attached a keyboard, monitor, and powered CHIP, but it does not do anything. The
LEDs are on, but I cant do anything with CHIP!

Fixes: Dont worry, your CHIP is probably fine. This can be fixed by reflashing CHIP from our web
flasher.

Follow the instructions for flashing your CHIP.

Sudden Shutdown (Brown-out)

Problem: I attached a mouse and keyboard, and my CHIP suddenly turned off.
Fixes: Like most tiny computers, the USB port on CHIP provides a limited amount of power. When
you plug in a keyboard and an optical mouse, for example, they will draw too much current from

CHIP, not leaving enough for the processor. As a result, CHIP will immediately shut down. There
are a few ways to avoid this.

Use a powered USB hub

Use a bluetooth keyboard and mouse. Yes, this is a very specific solution, but a good one
when you are only using the USB port for keyboard and mouse. Keeps your desk cleaner
too!

Execute the command sudo axp209 --no-limit in the terminal before you attach your
USB peripherals.

Provide power from a supply connecting ground and 5V the pins headers 1 and 2 on U13.

Problem: My CHIP booted fine until it got to loading the desktop GUI, then it shut down.

Fixes: This is usually the result of an underpowered power supply. We recommend a 5V power
supply with a minimum 1A current rating.

You can find the current rating on your power supplys Output - it should read 1000

mA or 1A (or a higher number). You may need a magnifying glass to read it, but they all
should have this info on the label!

Instead of powering CHIP using the microUSB port, try using the header pins CHG-IN
(U13-2) and GND (U13-1).

Add a LiPo battery. This provides enough extra current and power buffer to prevent this
problem.

No Video Output

Problem: Monitor is attached, but there is no video on my monitor

Fixes: There are a few possible problems here

wrong TRRS arrangement: try different ends of your cable. Make sure is subscribes to this

PAL monitor: CHIP outputs NTSC format video by default. You can change this, however,

use of the tip, rings, and sleeve

by following this guide.

Video trace cut for mic in: This is pretty unlikely, but if you are working with a used CHIP,
it may be that the tip connector has been switched to work as a microphone input. Before

you do fix this with a bit of solder, take a close look at your board to see if there is evidence
of a score mark indicating the cut trace.

How to Contact Us

If you need more support, try our forums or email us.

Compliance Statement
FCC ID: 2AF9F-HELLA1337
IC: 20863-HELLA1337

FCC

This device complies with part 15 of the FCC Rules. Operation is subject to the following two

conditions: (1) This device may not cause harmful interference, and (2) this device must accept
any interference received, including interference that may cause undesired operation.

Industry Canada

This device complies with Industry Canada license-exempt RSS standard(s). Operation is subject
to the following two conditions:

1. This device may not cause harmful interference;

2. This device must accept any interference received, including interference that may cause
undesired operation of the device.

Cet appareil est conforme Industrie Canada une licence standard RSS exonrs (s). Son

fonctionnement est soumis aux deux conditions suivantes: 1. Cet appareil ne doit pas provoquer

d'interfrences 2. Cet appareil doit accepter toute interfrence reue, y compris les interfrences
pouvant provoquer un fonctionnement indsirable de l'appareil.

Information to User

CAUTION: Changes or modifications not expressly approved for compliance could void your
authority to operate this equipment.