NAVI

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, you’ll have CHIP’s operating system on your screen, ready to do computer things.

DERP desktop

CHIP is built for making - we’ve 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 it’s based on the popular Linux Debian, if there’s something you need, you can probably install it.

So how do use this thing? Let’s get started.

Start CHIP. Boot CHIP.

First things first. Let’s 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. We’re going to cover how to turn CHIP “on”. This might seem so straightforward that it doesn’t deserve several paragraphs, but CHIP is pretty clever, so there’s actually a few things worth knowing.

What’s 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, you’ll be happy to know there’s a lot of ways to get the electricity flowing.

How Do I Know CHIP Is On?

CHIP is silent. It doesn’t take much energy, so it’s 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 CHIP’s 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 don’t 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 (that’s the same cable most phones, tablets, and whatnot use to charge) into the wall-wart and CHIP, and you’ll see the PWR LED light up. This CHIP is using the power from a computer’s USB port:

CHIP indicator LEDs

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.

CHIP powered by a battery. Slick!

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 doesn’t feel right!

What’s 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 you’ll be prompted for it.

Select a wireless connection access point

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:

Network connection editor

Connect Bluetooth

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

Bluetooth settings menu

When you begin a connection, you’ll be guided through the necessary steps to connect to your device. For example, when you pair with a keyboard, you’ll 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.

Bluetooth settings menu

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

Bluetooth devices panel

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. Don’t 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 you’ll be asked for a new password. Don’t 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, you’ll often find yourself in the terminal. If you’re a beginner, here’s 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 using man 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.

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.

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:

Additionally, some of the advanced tutorials require:

Powered USB Hub

You’ll 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 CHIP’s micro USB power port can only provide so much power for the USB port. If you don’t have a powered USB port, you’ll 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, it’s likely the two will draw too much current, so you’ll want to connect to a powered hub before you connect.

keyboard, mouse, and powered USB hub connected to CHIP

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. See connecting to bluetooth section

Monitor

In the spirit of keeping things small, CHIP packs all the audio and video into a small TRRS (Tip-Ring-Ring-Sleeve) connector. Built-in video output is restricted to standard composite video resolution of 640x480. (Higher resolutions can be achieved with the upcoming VGA and DVI output accessories.)

monitor connected to CHIP

Here’s 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:

monitor connected to CHIP

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.

Typical AV cable that carries stereo audio and composite video

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 isn’t working through the yellow cable, see if red works. If not, your cable may be a version that’s arranged in a way that it just won’t work with CHIP:

The conductors on the TRRS plug are arranged like this:

Tip: Audio Left, Ring: Audio Right, Ring: Ground, Sleeve: Video

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, you’ll 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=composite-ntsc,overscan_x=40,overscan_y=20

setenv video-mode sunxi:720x576-24@50,monitor=composite-pal,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 CHIP’s 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 from pins 4, 6 & 8 on header U14.

CHIP connected to headphones

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, you’ll 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 mic and middle pad. Now the outer ring can be used for audio input.

Slice video trace, bridge mic in pad

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

Xray vision of TV and Mic traces from top of CHIP

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.

USB Storage

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

USB drive attatched to CHIP

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 you’ve 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. There’s 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.

Screenshot of GUI showing where to change WiFi settings

Screenshot of GUI showing where to change WiFi settings

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, you’ll be prompted for it.

Select a wireless connection access point

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:

Network connection editor

Bluetooth

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

Bluetooth settings menu

When you begin a connection, you’ll be guided through the necessary steps to connect to your device. For example, when you pair with a keyboard, you’ll 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.

Bluetooth settings menu

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

Bluetooth devices panel

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:

Desktop volume control

Or, open the Audio Mixer in the Multimedia category:

Open Audio Mixer app in Multimedia category

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

Control panel for sound

If you don’t see that control, just click on the “Select Controls” button and enable all controls:

Enable all controls for audio mixer

Display

Use the Settings->Display control panel to adjust the monitor’s 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.

Change monitor settings with the Display control panel

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

Change desktop look with Desktop panel

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.

Orage Globaltime is used to set the time and date

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

Screenshot of mouse configuration panel

Language and Location

CHIP’s operating system comes with a default language of English. You can change the language and the location, but you’ll 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

You’ll get a large menu to select locales. Use the arrow keys to scroll down and spacebar to mark your location with an [*]. It’s 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

Orage Globaltime is used to set the time and date

Launching Installed Apps

CHIP comes prepackaged with many open-source applications to get you started. It’s easy to launch an application. You can select an application from the “Computer Things!” menu and select an app from the categories:

Screenshot of GUI launching apps

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

Screenshot of GUI launching apps

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

AbiWord can process words.

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.

Browse the web with IceWeasel

Video Player

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

Mplayer plays video

Terminal (commandline)

The life blood of linux. If there’s something you can’t do on the desktop, or you want to automate tasks, or access different hardware settings using nothing but a keyboard and text, you’ll open up Terminal.

Terminal does even more computer things

Complete List of Installed Software

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

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 debain-based systems. You can learn more about Synaptic here

There’s a simple search bar to make it easy to find packages you are interested in. If you don’t find the package you are looking for, hit the Reload button to refresh Synaptic’s record of available packages.

Install software with Synaptic

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 you’ll get a lot of results. Scroll through, and you’ll eventually find “scratch” in the packages window. However, you’ll probably want to narrow your results with better search terms, such as “scratch programming environments”

Search Synaptic for Scratch

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

Scratch package found

Press the top “Apply” button, and you’ll get the following dialog:

Scratch package found

and you’ll be notified of the progress:

Scratch installing

After a minute or so, you’ll be notified that it’s finished:

Scratch installed

Now that it’s installed, you can launch scratch:

Scratch installed

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:

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

Uninstall with Synaptic

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

Uninstall with Synaptic

If there are additional, related packages that need to be removed, you’ll be notified:

Uninstall with Synaptic

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

Uninstall with Synaptic

You’ll be notified what changes will be applied:

Uninstall with Synaptic

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

Uninstall with Synaptic

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 CHIP with buildroot, or Debian (with no GUI).

CHIP Hardware

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

Parts and Pieces

Callout graphic of chip parts on top Callout graphic of chip parts on bottom

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 CHIP’s 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. Here’s a basic diagram that labels all the pins:

CHIP pinout

U13L U13R U14L U14R
GND : ground CHG-IN : 5V input (power and battery charge) GND : ground VCC-5V : 5V power
VCC-5V : 5V power GND : ground UART1-TX : UART serial transmit HPL : audio out left
VCC-3V3 : 3V power TS : analog temperature sensor input UART1-RX : UART serial receive HPCOM : audio out common ground
VCC-1V8 : 1.8 V power BAT : LiPo battery FEL : “fel mode”: connect to ground to put CHIP in fel mode for firmware HPR : audio out right
TWI1-SDA : two-wire serial bus 1 PWRON : power on VCC-3V3 : 3 volt power MICM : mic mute
TWI1-SCK : two-wire serial bus 1 GND : ground LRADC : low-res Analog-Digital Converter MICIN1 : audio in
X1 : Resistive touchpanel input (touchscreen) X2 : Resistive touchpanel input (touchscreen) XIO-P0 : expander GPIO XIO-P1 : expander GPIO pin 1
Y1 : Resistive touchpanel input Y2 : Resistive touchpanel input (touchscreen) XIO-P2 : expander GPIO pin 2 XIO-P3 : expander GPIO pin 3
LCD-D2 : RGB666 data PWM0 : pulse width modulation (also used for LCD backlight dimming) XIO-P4 : expander GPIO pi XIO-P5 : expander GPIO pin 5
LCD-D4 : RGB666 data LCD-D3 : RGB666 data XIO-P6 : expander GPIO pin 6 XIO-P7 : expander GPIO pin 7
LCD-D6 : RGB666 data LCD-D5 : RGB666 data GND : ground GND : ground
LCD-D10 : RGB666 data LCD-D7 : RGB666 data AP-EINT1 : Application Processor Interrupt AP-EINT3 : Application Processor Interrupt pin, necessary for certain kinds of hardware-software interactions (keyboard expander, etc.)
LCD-D12 : RGB666 data LCD-D11 : RGB666 data TWI2-SDA : two-wire serial bus 2 (I2C) TWI2-SCK(*) : two-wire serial bus 2 (I2C)
LCD-D14 : RGB666 data LCD-D13 : RGB666 data CSIPCK : CMOS serial interface CSICK : CMOS serial interface, can be used for attaching a serial camera sensor
LCD-D18 : RGB666 data LCD-D15 : RGB666 data CSIHSYNC : CMOS serial interface CSIVSYNC : CMOS sync
LCD-D20 : RGB666 data LCD-D19 : RGB666 data CSID0 : CMOS serial interface CSID1 : CMOS serial interface
LCD-D22 : RGB666 data LCD-D21 : RGB666 data CSID2 : CMOS serial interface CSID3 : CMOS serial interface
LCD-CLK : RGB666 clock LCD-D23 : RGB666 data CSID4 : CMOS serial interface CSID5 : CMOS serial interface
LCD-VSYNC : vertical sync for LCD screen LCD-HSYNC : horizontal sync for LCD CSID6 : CMOS serial interface CSID7 : CMOS serial interface
GND : ground LCD-DE : RGB666 data GND : ground GND : ground

(*)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.

Open Source Hardware: Where To Get It

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

Sample schematic of CHIP

Making Stuff

CHIP is more than cool, small, inexpensive computer. It’s a complete system for building projects that require remote control, network connectivity, and physical interfacing with people and the environment. CHIP’s 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.

CHIP’s 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, here’s some things to try.

Requirements

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, you’ll find the GPIO pins in the middle of the right header, U14, Pins 13-20, labeled XIO-P0 to P7:

Pinout diagram for CHIP

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. PinsXIO-P0 to P7 linearly map to gpio408 to gpio415.

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:

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

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

  cat /sys/class/gpio/gpio415/direction

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

  cat /sys/class/gpio/gpio415/value

Some GPIO Output

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

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

Now that it’s in output mode, you can write a value to the pin:

  sudo sh -c 'echo 1 > /sys/class/gpio/gpio415/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:

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

Learn More

You can learn more about GPIO and Linux here:

Python Library

A Python-based library for accessing GPIO data is in development. You can see some examples in use

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 don’t 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 yet implemented for CHIP.

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. We’ve made it really easy to do this by embedding the entire process in a browser-based application.

Things you will need

Instructions

If you don’t have the Google Chrome or the open-source Chromium browser, 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, it’s suggested that you attach a USB2-compliant hub and connect your CHIP to the hub, instead of directly to the USB3 port.

It’s possible to run the entire operation online. There are also options for downloading the OS image to your harddrive, then flashing your CHIP with no additional need for internet access.

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

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, it’s pretty safe to say that Ubuntu users can flash without the virtual machine.

Requirements

Software Setup

There are several required software pieces to get the CHIP SDK virtual machine running.

Install VirtualBox and Extensions

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:

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

Here’s all the commands in one place:

git clone https://github.com/NextThingCo/CHIP-SDK
cd CHIP-SDK
vagrant up
vagrant ssh

Congratulations! Now you’re 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 CHIP-SDK 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.

Couldn’t Find File

If you get the error:

error: Couldn't open file /Volumes/Satellite/gitbins/CHIP-SDK/base

that means you didn’t 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. It’s only slightly more involved than sync'ing with the git repo; you have to update the virtual machine, too.

Requirements

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

Here’s 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 to prepare Ubuntu to flash

Have you repaired your CHIP?

The original batch of CHIPs shipped with a software bug in the NAND flash storage. We’ve 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). Here’s a reference image that labels the headers and pins:

CHIP with jumper wire attached

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-B 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, you’ll 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 a sample 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, you’ll 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 a sample 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-update-firmware.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 you’re finished with your selections, exit by hitting the F9 key, which will automatically save your custom buildroot to:

  /home/vagrant/CHIP-buildroot/.config

Now let’s 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/stable/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  1.83MB/s   in 29s

2015-10-21 15:59:45 (1.82 MB/s) - ‘/home/doge/gits/CHIP-tools/.firmware/images/rootfs.ubi’ saved [54525952/54525952]

/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
Created:      Wed Oct 21 15:59:46 2015
Image Type:   ARM Linux Script (uncompressed)
Data Size:    736 Bytes = 0.72 kB = 0.00 MB
Load Address: 00000000
Entry Point:  00000000
Contents:
   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/37
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.ubi
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.ubi
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-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/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-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/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
Created:      Wed Oct 21 16:08:49 2015
Image Type:   ARM Linux Script (uncompressed)
Data Size:    736 Bytes = 0.72 kB = 0.00 MB
Load Address: 00000000
Entry Point:  00000000
Contents:
   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’ll 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, there’s a good chance you’ll flash CHIP more than once in your life. You’ll 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 don’t 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

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 can’t be found”, you are probably booting from an Ubuntu Live CD (or USB stick). You’ll 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

You’ll 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

Here’s 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-tools-fsutils
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, you’ll want to use the first section about connecting with nmcli. If you have flashed CHIP with our buildroot OS, you’ll 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:

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
*  NextThing HQ    Infra  11    54 Mbit/s  100     ▂▄▆█  --
   NextThing Shop  Infra  6     54 Mbit/s  30      ▂___  WPA1 WPA2
   2WIRE533        Infra  10    54 Mbit/s  44      ▂▄__  WPA1 WPA2

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
wlan0    wifi      connected     NextThing HQ
wlan1    wifi      disconnected  --
ip6tnl0  ip6tnl    unmanaged     --
lo       loopback  unmanaged     --
sit0     sit       unmanaged     --

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  UUID                                  TYPE             DEVICE
NTC   59962bac-3441-437b-94ea-bf31dee66e8f  802-11-wireless  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. Google’s 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 there’s no network, you can’t connect. Go find a network!

Incorrect password

If you type in the wrong password, you’ll 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 don’t 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 you’d 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, you’ll 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 - you’ll need to use nmcli.

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

Requirements

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
                         wifi_7cc70905cd77_hidden_managed_psk
    NTC Guest            wifi_7cc70905cd77_4e5443204775657374_managed_psk
                         wifi_7cc70905cd77_hidden_managed_none
    ATT312               wifi_7cc70905cd77_415454333132_managed_psk
    HP-Print-99-LaserJet 1102 wifi_7cc70905cd77_48502d5072696e742d39392d4c617365724a65742031313032_managed_none
    ATT344               wifi_7cc70905cd77_415454333434_managed_psk
    CBCI-1B57-2.4        wifi_7cc70905cd77_434243492d314235372d322e34_managed_psk
    mi-fi                wifi_7cc70905cd77_6d692d6669_managed_none
    0024A5D8CF33         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 doesn’t use the nice name on the left of the services list. It wants the unfriendly string on the right, so you’ll 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, you’ll get some output that will indicate a successful connection, such as:

[  961.780000] RTL871X: rtw_set_802_11_connect(wlan0)  fw_state=0x00000008
[  962.070000] RTL871X: start auth
[  962.080000] RTL871X: auth success, start assoc
[  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, you’ll get an error.

B: Password-Protected

To deal with passwords, you’ll 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 what’s 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

Here’s all the commands in one place:

  connmanctl
  agent on
  connect wifi_7cc70905cd77_4e5443_managed_psk
  quit

Step 3: Test Connection

In CHIP’s 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
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                  wifi_7cc70905cd77_4e5443_managed_psk

Use the ID to disconnect:

  connmanctl disconnect wifi_7cc70905cd77_4e5443_managed_psk

and you’ll get some status like this:

[  301.890000] RTL871X: clear key for addr:0a:18:d6:97:2d:26, camid:4
[  301.900000] RTL871X: clear key for addr:0a:18:d6:97:2d:26, camid:5
[  301.920000] IPv6: ADDRCONF(NETDEV_UP): wlan0: link is not ready
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

It’s worth noting that you’ll 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, we’ve 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

Setup CHIP

Update your apt repository list if you haven’t 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, you’ll 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:

alsamixer interface

Play a Sound

Change to the root media directory:

  cd /media

Alternatively, you could download a sound into chip’s 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 CHIP’s 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, we’ll 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 you’ll need to make for paths, permissions, and enabling 'sudo.’ With buildroot, you work as the root user, so this tutorial is appropriately terse.

Requirements

Step 1: Format the Drive

First, you’ll 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 CHIP’s USB port. Enter the command

dmesg

You’ll 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 you’ll 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, it’s 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, it’s best to unmount it:

sudo umount /dev/sda1

Step 4: Automatic Mounting on Boot

You’ll 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, here’s a quick guide on getting this text into the fstab document:

/dev/sda1 /drives vfat defaults 0 0

To exit vi,

You can test your work with:

mount -a

If there’s 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 it’s successful, you’ll 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, you’ll need the command

mount -a

Connecting Bluetooth Devices

CHIP has built-in Bluetooth. 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 will cover those devices, but the keyboard is a good introduction to the commands and an easy way to test your system.

Requirements

Important!

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

About bluetoothctl

We’ll 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 CHIP’s 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. Here’s 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, you’ll 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, you’ll 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 won’t 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:3232.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

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 there’s 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

Installation (xfce4)

CHIP is a lightweight computer, so we’ll 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, you’ll get an image on the monitor:

Xwindows up and running on CHIP

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 Puckette’s 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, you’ll 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  jack libasound-dev qjackctl jackd2 tcl8.6 tk8.6 unzip
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

You’re 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

You’ll 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 in src/ you can

cd ../extra
make install

You’ll 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

I’ve 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, you’ll be prompted to save) You’ll 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. You’ll 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

Headless CHIP

One of the most amazing features of CHIP is that it’s 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, you’ll 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. Here’s how you do this.

Begin

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

Requirements

SSH

SSH (or “Secure Shell”) is a common way to control a computer remotely over a network. You’ll need to first get your computer’s 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 doesn’t 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 root@10.1.1.99

You’ll be asked for CHIP’s 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 you’d want to use a serial connection:

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

We’ll find those on header U14, pin outs 1,3 and 5. See the following diagram, which assumes CHIP’s USB ports are pointed up…

Pinout diagram for CHIP

About the Cable

If you need a connector, search your favorite shop for ‘USB to UART cable’ - any will do.

Here’s 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 you’re 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, you’ll probably need to install the PL2303 driver for your computer.

Connect the Cable

You only need to worry about three of the wires:

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:

Properly connect USB to UART cable

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, you’ll be able to continue with the directions below.

Control CHIP Using a Serial Terminal

Once you’ve connected CHIP to your computer with the UART or USB cable, open up a terminal. There’s lots out there. Here’s a few:

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

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 you’ll have the most reliable experience powering CHIP after connecting the USB-UART wires. If you make the serial connection after booting chip, you’ll 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.

You’ll 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, you’ll probably want to open the windows Device Manager to get the COM name for the serial port. The device won’t 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.

Device Manager showing serial ports

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

PuTTy configuration

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

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 chip@chip.local

and enter the password (default is chip). That’s 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 you’ll see a single word “chip.” Just modify that line (for example, change it to “bobofettywap”) and save the file. You’ll also need to modify the hosts file where you’ll need to change the first line 127.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 root@bobofettywap.local 

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. There’s 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 can’t 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).

CHIP Boot Repair Tool

The initial batch of CHIPs shipped with a problem in the NAND flash storage. Don’t worry, this is a software issue, and we’ve built a repair tool to correct this issue. Here’s everything you need to know to repair your CHIP’s NAND.

Things you will need

Required materials for repairing

The Really Easy Way Using A Browser

The easiest way to repair CHIP’s NAND is to use the online tools. You’ll need to install Google’s Chrome browser or the open-source Chromium browser. Once installed, open the browser and visit http://flash.getchip.com and follow the instructions.

If this is not appealing to you for whatever reason, then read on for instructions on repairing NAND directly from your computer.

For Ubuntu 14.4

apt-get commands in terminal

Search for the app

Waiting for FEL

FEL the board

CHIP to laptop

FEL Mode

CHIP fixed

For Windows 7, 8, & 10

Download the Repair Tool here. Double-click on the application icon and follow the on-screen directions to complete the repair process.

The Repair Tool works on Windows 7, 8, and 10. It’d problably work on Windows 9, but they didn’t make it!


startRepair


step1


step2


step4


step5


step6


For Mac OS X 10.10 (Yosemite)

Download the Repair Tool here. Double-click on the application icon and follow the on-screen directions to complete the repair process.

The Repair Tool works on Mac OS X 10.10 (Yosemite).


startRepair


step1


step2


step4


step5


step6


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:

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, we’re excited to introduce people to the physical components of computers and show them that electronics aren’t scary, they’re 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?

We’re 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, we’ll release our design files. We’ve already released quite a bit! Check them out at our GitHub repo!

Can I upgrade CHIP’s 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 won’t 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 CHIP’s 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?

We’re focused on individual uses of C.H.I.P. but what you’re talking about is called clustering, and may be possible – A good place to start, if you’re interested in clustering, is reading up on Debian-Beowulf

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 you’d 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, we’re able to both save you a “getting started” cost and allow Linux to come preinstalled on C.H.I.P. meaning it’s 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, it’s 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, isn’t 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. What’s even more exciting, though, is that if any given program isn’t supported out of the box, the community can work together to make it happen. That’s 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 there’s 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 isn’t 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 use 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 CHIP’s 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?

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

cat /proc/cpuinfo

This will give output similar to:

processor   : 0
model name  : ARMv7 Processor rev 2 (v7l)
BogoMIPS    : 1001.88
Features    : 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
Revision    : 0000
Serial      : 162542c10c427777

If you want know more about the memory:

cat /proc/meminfo

with output something like:

MemTotal:         507108 kB
MemFree:          298600 kB
MemAvailable:     382592 kB
Buffers:               0 kB
Cached:            92216 kB
SwapCached:            0 kB
Active:            98752 kB
Inactive:          64096 kB
Active(anon):      73180 kB
Inactive(anon):     5812 kB
Active(file):      25572 kB
Inactive(file):    58284 kB
Unevictable:           0 kB
Mlocked:               0 kB
HighTotal:             0 kB
HighFree:              0 kB
LowTotal:         507108 kB
LowFree:          298600 kB
SwapTotal:             0 kB
SwapFree:              0 kB
Dirty:                 0 kB
Writeback:             0 kB
AnonPages:         70660 kB
Mapped:            37768 kB
Shmem:              8360 kB
Slab:              22784 kB
SReclaimable:      11560 kB
SUnreclaim:        11224 kB
KernelStack:        1176 kB
PageTables:         2240 kB
NFS_Unstable:          0 kB
Bounce:                0 kB
WritebackTmp:          0 kB
CommitLimit:      253552 kB
Committed_AS:     615216 kB
VmallocTotal:     507904 kB
VmallocUsed:       14560 kB
VmallocChunk:     482532 kB

Troubleshooting

CHIP Won’t Boot or Startup

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

Fixes: The initial batch of CHIPs shipped with a problem in their NAND flash storage. Don’t worry, this is a software issue, and we’ve built a repair tool.

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.

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.

No Video Output

Problem: Monitor is attached, but there is no video on my monitor

Fixes: There are a few possible problems here

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 exonérés (s). Son fonctionnement est soumis aux deux conditions suivantes: 1. Cet appareil ne doit pas provoquer d'interférences 2. Cet appareil doit accepter toute interférence reçue, y compris les interférences pouvant provoquer un fonctionnement indésirable de l'appareil.

Information to User

CAUTION: Changes or modifications not expressly approved for compliance could void your authority to operate this equipment.