getchip / chip-docs

User Manual and Documentation of Next Thing Co's C.H.I.P.

Next Thing CHIP Documentation

This is a source repo for documentation. If you want to see it as a website, you'll need to render it to HTML. Read on!

Quick Start

git clone https://github.com/NextThingCo/CHIP_Pro-Docs
cd CHIP_Pro-Docs
bundle install
bundle exec middleman server

Go to your browser and visit http://localhost:4567 to view the docs.

If this fails, read on!

Intro

All documentation is written in markdown and staged on github pages. Published documentation is viewable on the github pages.

If you want to add or modify a document, add your markdown file to the includes directory and make a pull request. You can use Github markdown or regular markdown.

Each include represents a top-level topic in the left-hand navigation if it is in the list of includes in index.html.

Note: If you view the files in the include/ directory here on github, the image links appear broken. This is to be expected because these pages have yet to be rendered into a viewable state.

Uses the Slate Documentation Generator

This repo is forked from Slate. Read the docs on the original Slate repo wiki if you want all the details. There are also some sample docs worth perusing.

Here's the crux of the matter, though:

Prerequisites

You're going to need:

• Linux or OS X — Windows may work, but is unsupported.
• Ruby, version 1.9.3 or newer
• Bundler — If Ruby is already installed, but the bundle command doesn't work, just run gem install bundler in a terminal.

Ubuntu 14.04 LTS

Install the following packages, then jump to the Preview section.

sudo apt-get install git ruby-dev
sudo gem install bundler
cd 
git clone [email protected]:NextThingCo/DIP-Docs.git
cd DIP-Docs
bundle install

Getting El Capitan to Behave

Installing on El Capitan (OS X 10.11) can be difficult. Once you clone the directory, you may need to cd to the chipdocs directory, then run the command bundle install. If you get errors when you try to run ./deploy.sh after that, try bundle update to install the bundler, and then try ./deploy.sh again.

There may be some other black magic involved in getting it working on El Capitan, including:

brew install ruby
sudo gem install therubyracer -v '0.12.2'
sudo gem install libv8 -v '3.16.14.13' -- --with-system-v8

or perhaps even adding -n /usr/local/bin to the end of those last two items. I had to fumble around with a lot of various suggestions on the internets to finally get this working on El Capitan, so it is hard to say exactly which one fixed it. The last command I tried before it worked was bundle update, so I'd try that first!

Preview

If you want to preview your changes to the documents in a browser before you make a pull request or push changes, navigate to the chipdocs/ directory, and use the middleman server to render and serve the documentation in HTML. The terminal will tell you the URL to use to check out the docs.

bundle install
bundle exec middleman server

Publish

The normal Slate workflow requires that changes to the master branch be commited and pushed. Then, the deploy.sh script can be run locally to render HTML, push changes to the gh-pages branch, and made live. We've modified the workflow so an external script monitors this repo, renders any changes to the HTML, then merges with the other "-Docs" and "landingpage" repositories in this organization to create the "masterdocs" repository. Ultimately it all ends up at docs.getchip.com

chip-docs's Issues

Typo in linux web flasher instructions

https://docs.getchip.com/chip.html#web-flasher-os-specific-issues

I'm not sure if this issue is specific to my OS but my bash terminal doesn't recognize the parentheses around the USER variable. Use the following instead:

sudo usermod -a -G dialout ${USER}
sudo usermod -a -G plugdev ${USER}

Over USB tether setup advice missing ..

specifically for people that don't have the composite video cable.

topics: nmtui versus nmcli.

• their varying availaibily on Macs and different flavors/versions of Linux

Updating the CHIP-SDK Virtual Machine

1. In this section of the docs, it says to issue the following vagrant commands in this order:

vagrant halt
vagrant provision

However, when I issue "vagrant provision", I get:

~/GitHub/CHIP-SDK$ vagrant halt
~/GitHub/CHIP-SDK$ vagrant provision
==> default: VM is not currently running. Please, first bring it up with `vagrant up` then run this command.

Correction to docs ...?

2. So I tried reversing the order ... vagrant up is successful, but provision results in the following:

==> default: /home/vagrant
**==> default: fatal: destination path 'chip-mtd-utils' already exists and is not an empty directory.**
==> default: /home/vagrant/chip-mtd-utils /home/vagrant
==> default: Already on 'by/1.5.2/next-mlc-debian'
...
==> default:  Installing CHIP-tools
==> default: /home/vagrant/CHIP-tools /home/vagrant
==> default: Already up-to-date.
==> default: /home/vagrant
**==> default: fatal: destination path 'CHIP-tools' already exists and is not an empty directory.**
==> default:  Installing CHIP-buildroot

So there seems to be two fatal errors ...?

How much does CHIP weight?

GPIO input instructions: off by 1?

The instructions at https://docs.getchip.com/chip.html#making-stuff for reading input from GPIO refer to "XIO-P7", but refer to /sys/class/gpio/gpio1019 (for 4.4.13-ntc-mlc), which seems to be connected to XIO-P6. I think the docs should be referring to /sys/class/gpio/gpio1020 in those cases (which does seem to correspond with XIO-P7.

Make hardware pin voltage precautions more explicit

The maximum voltages for hardware pins are somewhat hard to find in the documentation and are missing from some of the key sections describing hardware interfacing.

1. the Pin Headers section should list max. voltages. In particular, pins that are likely to be used for ad-hoc/experimentation such as GPIO and UART should have explicit mentions.
2. The GPIO section in Making Stuff should mention GPIO voltage ranges and precautions.
3. The Headless CHIP section doesn't mention voltage requirements. "About the Cable" states " If you need a connector, search your favorite shop for ‘USB to UART cable’ - any will do. This section should mention that it needs to be TTL not RS-232 voltages, and whether it needs to be 3v3 connection or whether 5 vdc is also acceptable?

Some other comments regarding these sections.

• The example cable that is listed in the serial section uses female headers. There is no mention of needing male headers, or pieces of paper clips, etc. to connect the two female headers. Also, it might be better to direct people to get a cable that has an FTDI or CP210x chip to avoid some of the drier issues with PL2303 chips/clones.
• The Making Stuff section is pretty minimal, in many cases it explains the SYSFS interfaces, but doesn't mention which pins would be useful for that type of interface.
• The PWM section in Making Stuff is problematic. it currently says can be 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. First, generally one shouldn't go connecting motors directly to your GPIO pins without protection and likely need drivers that can supply more current than the GPIO can provide. Second, the fast enough for robust and smooth control doesn't make a lot of sense in the context of motors. It might be better to say that "PWM can be used to cycle a pin on and off rapidly at a range of frequencies or duty cycles. In some cases, PWM can be used to simulate an analog output. For example, an LED driven by PWM can be used to simulate dimming."

Link repo to website

Minor thing: I'd link this GitHub repo to docs.getchip.com like on

Battery Polarity Warning

In the "Power From A Battery" it would be good to add a note that the black (-) wire should be on the outside edge and/or add text and arrow to the image. I bought a lipo battery that came without the connector, so bought a pack of connector wires from ebay. Apparently there is a type A and type B JST-PH 2.0mm connector with reversed red and black wiring. Most of the connector packs sold on ebay are the wrong polarity and need to be soldered with crossed colors! I didn't check at first so inserted my battery reversed-- fortunately I didn't burn out anything. Thankfully, there must be a reversed battery protection circuit.

CONTRIBUTING.md states "Use dev branch" - No dev branch?

CONTRIBUTING.md states:

Please point your pull requests at the dev branch. We don't accept pull requests to master.

Since there is no dev branch, what branch would you prefer to receive a pull request against?

chip-update-firmware.sh '-d' option no longer exists

This line in the docs refers to the '-d' option:
https://github.com/getchip/CHIP-Docs/blame/612b72f6aae65d45da058797018b28009585305c/source/includes/_advanced.md#L178

But the last version of the update firmware script doesn't have a '-d' option:
https://github.com/NextThingCo/CHIP-tools/blob/chip/stable/chip-update-firmware.sh#L28

The doc also says

The -f option means “fastboot.”

But seems that it is not the case in current version:

-f  --  Force clean        [re-download if applicable]

Accessing UART (not via UART)

_making.md should state how to read UART, that is how to use CHIP to access and read/write another device's UART. That would allow connecting to a microcontroller or other peripheral which has a serial interface.

Seems that a decent starting place for that is:
http://elinux.org/RPi_Serial_Connection