diff --git a/docs/index.rst b/docs/index.rst index a8bde68..3c66f69 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,159 +1,195 @@ -An h1 header +.. _install: + +============ +Installation ============ -Paragraphs are separated by a blank line. - -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. ☺ +.. currentmodule:: picamera +.. _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 - 2. second item - 3. third item + $ sudo apt-get update + $ sudo apt-get install python-picamera python3-picamera -Note again how the actual text starts at 4 columns in (4 characters -from the left side). Here's a code sample: +To upgrade your installation when new releases are made you can simply use +apt's normal upgrade procedure:: - # Let me re-iterate ... - for i in 1 .. 10 { do-something(i) } + $ sudo apt-get update + $ sudo apt-get upgrade -As you probably guessed, indented 4 spaces. By the way, instead of -indenting the block, you can use delimited blocks, if you like: +If you ever need to remove your installation:: -~~~ -define foobar() { - print "Welcome to flavor country!"; -} -~~~ + $ sudo apt-get remove python-picamera python3-picamera -(which makes copying & pasting easier). You can optionally mark the -delimited block for Pandoc to syntax highlight it: +.. note:: -~~~python -import time -# Quick, count to ten! -for i in range(10): - # (but not *too* quick) - time.sleep(0.5) - print(i) -~~~ + If you are using a recent installation of Raspbian, you may find that the + python-picamera package is already installed (it is included by default + in recent versions). + +.. _Raspbian: http://www.raspbian.org/ +.. _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 - * celery - * lentils +If you wish to use the classes in the :mod:`picamera.array` module then specify +the "array" option which will pull in numpy as a dependency (be warned that +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 - this algorithm: +To upgrade your installation when new releases are made:: - find wooden spoon - uncover pot - stir - cover pot - balance wooden spoon precariously on pot handle - wait 10 minutes - goto first step (or shut off burner when done) + $ sudo pip install -U picamera - 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 -that last line which continues item 3 above). + $ sudo pip uninstall picamera -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 -------------- ----- ------------ ------------ -All Business 9 leather brown -Roundabout 10 hemp canvas natural -Cinderella 11 glass transparent +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 +functionality of the Pi's camera module through new firmware releases. Whilst +the picamera library attempts to maintain backward compatibility with older Pi +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 -multi-line tables: + $ uname -a --------- ----------------------- -Keyword Text --------- ----------------------- -red Sunsets, apples, and - other red or reddish - things. +The firmware revision is the number after the ``#``:: -green Leaves, grass, frogs - and other things it's - not easy being. --------- ----------------------- + Linux kermit 3.12.26+ #707 PREEMPT Sat Aug 30 17:39:19 BST 2014 armv6l GNU/Linux + / + / + 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 - : Good for making applesauce. + Previously, these documents have suggested using the ``rpi-update`` utility + 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 - : Citrus! + $ sudo apt-get update + $ sudo apt-get install --reinstall libraspberrypi0 libraspberrypi-{bin,dev,doc} raspberrypi-bootloader + $ sudo rm /boot/.firmware_revision -tomatoes - : There's no "e" in tomatoe. + You will need to reboot after doing so. -Again, text is indented 4 spaces. (Put a blank line between each -term and its definition to spread things out more.) +.. note:: -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 -| Line too -| Line tree +.. _PiTFT: http://www.adafruit.com/product/1601 -and images can be specified like so: -![example image](example-image.jpg "An exemplary image") +.. _dev_install: -Inline math equation: $\omega = d\phi / dt$. Display -math should get its own line like so: +Development installation +======================== -$$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.