Update index.rst
This commit is contained in:
tpollina
GitHub
parent
63f1397807
commit
e0d3ea7275
262
docs/index.rst
262
docs/index.rst
|
|
@ -1,159 +1,195 @@
|
||||||
An h1 header
|
.. _install:
|
||||||
|
|
||||||
|
============
|
||||||
|
Installation
|
||||||
============
|
============
|
||||||
|
|
||||||
Paragraphs are separated by a blank line.
|
.. currentmodule:: picamera
|
||||||
|
|
||||||
2nd paragraph. *Italic*, **bold**, and `monospace`. Itemized lists
|
|
||||||
look like:
|
|
||||||
|
|
||||||
* this one
|
|
||||||
* that one
|
|
||||||
* the other one
|
|
||||||
|
|
||||||
Note that --- not considering the asterisk --- the actual text
|
|
||||||
content starts at 4-columns in.
|
|
||||||
|
|
||||||
> Block quotes are
|
|
||||||
> written like so.
|
|
||||||
>
|
|
||||||
> They can span multiple paragraphs,
|
|
||||||
> if you like.
|
|
||||||
|
|
||||||
Use 3 dashes for an em-dash. Use 2 dashes for ranges (ex., "it's all
|
|
||||||
in chapters 12--14"). Three dots ... will be converted to an ellipsis.
|
|
||||||
Unicode is supported. ☺
|
|
||||||
|
|
||||||
|
|
||||||
|
.. _raspbian_install:
|
||||||
|
|
||||||
An h2 header
|
Raspbian installation
|
||||||
------------
|
=====================
|
||||||
|
|
||||||
Here's a numbered list:
|
If you are using the `Raspbian`_ distro, it is best to install picamera using
|
||||||
|
the system's package manager: apt. This will ensure that picamera is easy to
|
||||||
|
keep up to date, and easy to remove should you wish to do so. It will also make
|
||||||
|
picamera available for all users on the system. To install picamera using apt
|
||||||
|
simply::
|
||||||
|
|
||||||
1. first item
|
$ sudo apt-get update
|
||||||
2. second item
|
$ sudo apt-get install python-picamera python3-picamera
|
||||||
3. third item
|
|
||||||
|
|
||||||
Note again how the actual text starts at 4 columns in (4 characters
|
To upgrade your installation when new releases are made you can simply use
|
||||||
from the left side). Here's a code sample:
|
apt's normal upgrade procedure::
|
||||||
|
|
||||||
# Let me re-iterate ...
|
$ sudo apt-get update
|
||||||
for i in 1 .. 10 { do-something(i) }
|
$ sudo apt-get upgrade
|
||||||
|
|
||||||
As you probably guessed, indented 4 spaces. By the way, instead of
|
If you ever need to remove your installation::
|
||||||
indenting the block, you can use delimited blocks, if you like:
|
|
||||||
|
|
||||||
~~~
|
$ sudo apt-get remove python-picamera python3-picamera
|
||||||
define foobar() {
|
|
||||||
print "Welcome to flavor country!";
|
|
||||||
}
|
|
||||||
~~~
|
|
||||||
|
|
||||||
(which makes copying & pasting easier). You can optionally mark the
|
.. note::
|
||||||
delimited block for Pandoc to syntax highlight it:
|
|
||||||
|
|
||||||
~~~python
|
If you are using a recent installation of Raspbian, you may find that the
|
||||||
import time
|
python-picamera package is already installed (it is included by default
|
||||||
# Quick, count to ten!
|
in recent versions).
|
||||||
for i in range(10):
|
|
||||||
# (but not *too* quick)
|
.. _Raspbian: http://www.raspbian.org/
|
||||||
time.sleep(0.5)
|
|
||||||
print(i)
|
|
||||||
~~~
|
|
||||||
|
|
||||||
|
|
||||||
|
.. _non_raspbian_install:
|
||||||
|
|
||||||
### An h3 header ###
|
Alternate distro installation
|
||||||
|
=============================
|
||||||
|
|
||||||
Now a nested list:
|
On distributions other than Raspbian, it is probably simplest to install system
|
||||||
|
wide using Python's ``pip`` tool::
|
||||||
|
|
||||||
1. First, get these ingredients:
|
$ sudo pip install picamera
|
||||||
|
|
||||||
* carrots
|
If you wish to use the classes in the :mod:`picamera.array` module then specify
|
||||||
* celery
|
the "array" option which will pull in numpy as a dependency (be warned that
|
||||||
* lentils
|
building numpy takes a *long* time on a Pi)::
|
||||||
|
|
||||||
2. Boil some water.
|
$ sudo pip install "picamera[array]"
|
||||||
|
|
||||||
3. Dump everything in the pot and follow
|
To upgrade your installation when new releases are made::
|
||||||
this algorithm:
|
|
||||||
|
|
||||||
find wooden spoon
|
$ sudo pip install -U picamera
|
||||||
uncover pot
|
|
||||||
stir
|
|
||||||
cover pot
|
|
||||||
balance wooden spoon precariously on pot handle
|
|
||||||
wait 10 minutes
|
|
||||||
goto first step (or shut off burner when done)
|
|
||||||
|
|
||||||
Do not bump wooden spoon or it will fall.
|
If you ever need to remove your installation::
|
||||||
|
|
||||||
Notice again how text always lines up on 4-space indents (including
|
$ sudo pip uninstall picamera
|
||||||
that last line which continues item 3 above).
|
|
||||||
|
|
||||||
Here's a link to [a website](http://foo.bar), to a [local
|
|
||||||
doc](local-doc.html), and to a [section heading in the current
|
|
||||||
doc](#an-h2-header). Here's a footnote [^1].
|
|
||||||
|
|
||||||
[^1]: Some footnote text.
|
.. _firmware:
|
||||||
|
|
||||||
Tables can look like this:
|
Firmware upgrades
|
||||||
|
=================
|
||||||
|
|
||||||
Name Size Material Color
|
The behaviour of the Pi's camera module is dictated by the Pi's firmware. Over
|
||||||
------------- ----- ------------ ------------
|
time, considerable work has gone into fixing bugs and extending the
|
||||||
All Business 9 leather brown
|
functionality of the Pi's camera module through new firmware releases. Whilst
|
||||||
Roundabout 10 hemp canvas natural
|
the picamera library attempts to maintain backward compatibility with older Pi
|
||||||
Cinderella 11 glass transparent
|
firmwares, it is only tested against the latest firmware at the time of
|
||||||
|
release, and not all functionality may be available if you are running an older
|
||||||
|
firmware. As an example, the :attr:`~PiCamera.annotate_text` attribute relies
|
||||||
|
on a recent firmware; older firmwares lacked the functionality.
|
||||||
|
|
||||||
Table: Shoes sizes, materials, and colors.
|
You can determine the revision of your current firmware with the following
|
||||||
|
command::
|
||||||
|
|
||||||
(The above is the caption for the table.) Pandoc also supports
|
$ uname -a
|
||||||
multi-line tables:
|
|
||||||
|
|
||||||
-------- -----------------------
|
The firmware revision is the number after the ``#``::
|
||||||
Keyword Text
|
|
||||||
-------- -----------------------
|
|
||||||
red Sunsets, apples, and
|
|
||||||
other red or reddish
|
|
||||||
things.
|
|
||||||
|
|
||||||
green Leaves, grass, frogs
|
Linux kermit 3.12.26+ #707 PREEMPT Sat Aug 30 17:39:19 BST 2014 armv6l GNU/Linux
|
||||||
and other things it's
|
/
|
||||||
not easy being.
|
/
|
||||||
-------- -----------------------
|
firmware revision --+
|
||||||
|
|
||||||
A horizontal rule follows.
|
On Raspbian, the standard upgrade procedure should keep your firmware
|
||||||
|
up to date::
|
||||||
|
|
||||||
***
|
$ sudo apt-get update
|
||||||
|
$ sudo apt-get upgrade
|
||||||
|
|
||||||
Here's a definition list:
|
.. warning::
|
||||||
|
|
||||||
apples
|
Previously, these documents have suggested using the ``rpi-update`` utility
|
||||||
: Good for making applesauce.
|
to update the Pi's firmware; this is now discouraged. If you have
|
||||||
|
previously used the ``rpi-update`` utility to update your firmware, you can
|
||||||
|
switch back to using ``apt`` to manage it with the following commands::
|
||||||
|
|
||||||
oranges
|
$ sudo apt-get update
|
||||||
: Citrus!
|
$ sudo apt-get install --reinstall libraspberrypi0 libraspberrypi-{bin,dev,doc} raspberrypi-bootloader
|
||||||
|
$ sudo rm /boot/.firmware_revision
|
||||||
|
|
||||||
tomatoes
|
You will need to reboot after doing so.
|
||||||
: There's no "e" in tomatoe.
|
|
||||||
|
|
||||||
Again, text is indented 4 spaces. (Put a blank line between each
|
.. note::
|
||||||
term and its definition to spread things out more.)
|
|
||||||
|
|
||||||
Here's a "line block" (note how whitespace is honored):
|
Please note that the `PiTFT`_ screen (and similar GPIO-driven screens)
|
||||||
|
requires a custom firmware for operation. This firmware lags behind the
|
||||||
|
official firmware and at the time of writing lacks several features
|
||||||
|
including long exposures and text overlays.
|
||||||
|
|
||||||
| Line one
|
.. _PiTFT: http://www.adafruit.com/product/1601
|
||||||
| Line too
|
|
||||||
| Line tree
|
|
||||||
|
|
||||||
and images can be specified like so:
|
|
||||||
|
|
||||||
|
.. _dev_install:
|
||||||
|
|
||||||
Inline math equation: $\omega = d\phi / dt$. Display
|
Development installation
|
||||||
math should get its own line like so:
|
========================
|
||||||
|
|
||||||
$$I = \int \rho R^{2} dV$$
|
If you wish to develop picamera itself, it is easiest to obtain the source by
|
||||||
|
cloning the GitHub repository and then use the “develop” target of the Makefile
|
||||||
|
which will install the package as a link to the cloned repository allowing
|
||||||
|
in-place development (it also builds a tags file for use with vim/emacs with
|
||||||
|
Exuberant’s ctags utility). The following example demonstrates this method
|
||||||
|
within a virtual Python environment::
|
||||||
|
|
||||||
|
$ sudo apt-get install lsb-release build-essential git git-core \
|
||||||
|
exuberant-ctags python-virtualenv python3-virtualenv python-dev \
|
||||||
|
python3-dev libjpeg8-dev zlib1g-dev libav-tools \
|
||||||
|
texlive-latex-recommended texlive-latex-extra texlive-fonts-recommended
|
||||||
|
$ virtualenv -p /usr/bin/python3 sandbox
|
||||||
|
$ source sandbox/bin/activate
|
||||||
|
(sandbox) $ git clone https://github.com/waveform80/picamera.git
|
||||||
|
(sandbox) $ cd picamera
|
||||||
|
(sandbox) $ make develop
|
||||||
|
|
||||||
|
To pull the latest changes from git into your clone and update your
|
||||||
|
installation::
|
||||||
|
|
||||||
|
$ source sandbox/bin/activate
|
||||||
|
(sandbox) $ cd picamera
|
||||||
|
(sandbox) $ git pull
|
||||||
|
(sandbox) $ make develop
|
||||||
|
|
||||||
|
To remove your installation blow away the sandbox and the clone::
|
||||||
|
|
||||||
|
$ rm -fr ~/sandbox/ ~/picamera/
|
||||||
|
|
||||||
|
For anybody wishing to hack on the project, I would strongly recommend reading
|
||||||
|
through the :class:`PiCamera` class' source, to get a handle on using the
|
||||||
|
``mmalobj`` layer. This is a layer introduced in picamera 1.11 to ease the
|
||||||
|
usage of ``libmmal`` (the underlying library that picamera, ``raspistill``,
|
||||||
|
and ``raspivid`` all rely upon).
|
||||||
|
|
||||||
|
Beneath ``mmalobj`` is a :mod:`ctypes` translation of the ``libmmal`` headers
|
||||||
|
but my hope is that most developers will never need to deal with this
|
||||||
|
directly (thus, a working knowledge of C is hopefully no longer necessary to
|
||||||
|
hack on picamera).
|
||||||
|
|
||||||
|
Various classes for specialized applications also exist
|
||||||
|
(:class:`PiCameraCircularIO`, :class:`~array.PiBayerArray`, etc.)
|
||||||
|
|
||||||
|
Even if you don’t feel up to hacking on the code, I’d love to hear suggestions
|
||||||
|
from people of what you’d like the API to look like (even if the code itself
|
||||||
|
isn’t particularly pythonic, the interface should be)!
|
||||||
|
|
||||||
|
|
||||||
|
.. _test_suite:
|
||||||
|
|
||||||
|
Test suite
|
||||||
|
==========
|
||||||
|
|
||||||
|
If you wish to run the picamera test suite, follow the instructions in
|
||||||
|
:ref:`dev_install` above and then make the "test" target within the sandbox::
|
||||||
|
|
||||||
|
$ source sandbox/bin/activate
|
||||||
|
(sandbox) $ cd picamera
|
||||||
|
(sandbox) $ make test
|
||||||
|
|
||||||
|
.. warning::
|
||||||
|
|
||||||
|
The test suite takes a *very* long time to execute (at least 1 hour on an
|
||||||
|
overclocked Pi 3). Depending on configuration, it can also lockup the
|
||||||
|
camera requiring a reboot to reset, so ensure you are familiar with SSH or
|
||||||
|
using alternate TTYs to access a command line in the event you need to
|
||||||
|
reboot.
|
||||||
|
|
||||||
And note that you can backslash-escape any punctuation characters
|
|
||||||
which you wish to be displayed literally, ex.: \`foo\`, \*bar\*, etc.
|
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue