:orphan:

*****************
Quick Start Guide
*****************

.. role:: bash(code)
   :language: bash

Operating system installation
=============================

Prerequisites:
	* Any **Raspberry Pi** model
	* A **microSD card** (preferably `speed class 10 <https://www.sdcard.org/developers/overview/speed_class/>`__)
	* A computer with a microSD **card reader**

Required steps:
	#. Format the microSD card (preferably with the `SD Memory Card Formatter <https://www.sdcard.org/downloads/formatter_4/>`__)
	#. Download the zipped disk image for the `latest version of Raspbian <https://downloads.raspberrypi.org/raspbian_latest>`__ from https://www.raspberrypi.org/downloads/raspbian/
	#. Unzip the disk image
	#. Find the disk number of microSD card using :bash:`diskutil list`
	#. Unmount micro SD card using :bash:`diskutil unmount /dev/disk<number>` e.g. :bash:`diskutil unmount /dev/disk2s1`
	#. Copy Raspian disk image onto micro SD card using :bash:`sudo dd bs=1m if=<disk image file name> of=/dev/rdisk<number> conv=sync` e.g. :bash:`sudo dd bs=1m if=2018-03-13-raspbian-stretch.img of=/dev/rdisk2 conv=sync`
	#. Wait until the copy process is finished (This will take around 7 minutes. You can check the process by hitting ctrl-T)


Enable USB OTG mode
===================

All Raspberry Pi models have been designed to be used by connecting a power supply, monitor, keyboard and mouse.

If You have a Raspberry Pi model with only one USB connector (= any model without a built-in USB hub), then You can use Your computer and a single USB cable to connect and power Your Raspberry Pi by enabling the USB OTG mode (= USB On-The-Go).

Prerequisites:
	* A Raspberry Pi model **A, A+, Zero or Zero W** (= any model with only one USB connector)
	* A microSD card with Raspbian installed onto it
	* A computer with a microSD card reader

Required steps:
	#. Connect the microSD card to Your computer
	#. Open the file **cmdline.txt** with a text editor and insert :bash:`modules-load=dwc2,g_ether` after :bash:`rootwait` and save the changes
	#. Open the file **config.txt** with a text editor and add a line :bash:`dtoverlay=dwc2` at the bottom and save the changes
	#. Create a new file in the same directory called **ssh** (without any content or file name extension) e.g. by typing :bash:`touch /Volumes/boot/ssh`

The original instructions can be found on `Andrew Mullholland's Blog <https://blog.gbaman.info>`__ at https://blog.gbaman.info/?p=791.


Connect to a Raspberry Pi over USB
==================================

Prerequisites:
	* A Raspberry Pi model **A, A+, Zero or Zero W** (= any model with only one USB connector)
	* A micro SD card with Raspbian installed onto it and **enabled OTG mode**
	* A micro USB cable
	* A computer with a USB port

Required steps:
   #. Insert the microSD card into the Raspberry Pi
   #. Connect the Raspberry Pi micro-USB cable to the socket labelled 'USB' (the other one 'PWR' works only as a power socket) and Your computer
   #. Open up Terminal and connect via SSH (Secure Shell) by typing :bash:`ssh pi@raspberrypi.local`
   #. Watch the *Network* panel in *System Preferences*: You should see the *RNDIS/Ethernet Gadget*
   #. The default password is :bash:`raspberry`
   #. In macOS the IP address of the adapter will be 169.254.xxx.xxx on the host side.
   #. To disconnect type :bash:`exit`
   #. To shutdown type :bash:`sudo shutdown -h now` (when connected)
   #. If *ssh pi@raspberrypi.local* does not work try :bash:`arp -a`


Remove ssh key from known_hosts
===============================

Remove line in text file :bash:`open ~/.ssh/known_hosts`


Configure the Raspberry Pi
==========================

Run the Raspberry Pi configuration tool

.. code-block:: bash

	sudo raspi-config

and

	#. Change the hostname (2 Network Options -> N1 Hostname)
	#. Connect to a wireless network (2 Network Options -> N2 Wi-fi)
	#. Enable SPI (5 Interface Options -> P4 SPI)


Install additional Libraries
============================

Using pip3
----------

**Test the internet connection**

.. code-block:: bash

	ping 8.8.8.8

**Update pip3**

.. code-block:: bash

	sudo -H pip3 install --upgrade pip

**Install Adafruit_GPIO** (from https://pypi.org/project/Adafruit-GPIO/)

.. code-block:: bash

	sudo pip3 install Adafruit-GPIO

**Install Adafruit_LED_Backpack** (from https://pypi.org/project/Adafruit-LED-Backpack/)

.. code-block:: bash

	sudo pip3 install Adafruit-LED-Backpack

**Install Adafruit_SSD1306** (from https://pypi.org/project/Adafruit-SSD1306/)

.. code-block:: bash

	sudo pip3 install Adafruit-SSD1306

**Install Adafruit_IO** (from https://pypi.org/project/adafruit-io/)

.. code-block:: bash

	sudo pip3 install adafruit-io

Using apt-get
-------------

**Test the internet connection**

.. code-block:: bash

	ping 8.8.8.8

**Update/install required software**

.. code-block:: bash

	sudo apt-get update
	sudo apt-get install build-essential python-pip python-dev python-smbus git

**Install Adafruit_GPIO** (from https://github.com/adafruit/Adafruit_Python_GPIO)

.. code-block:: bash

	git clone https://github.com/adafruit/Adafruit_Python_GPIO.git
	cd Adafruit_Python_GPIO
	sudo python3 setup.py install

**Install Adafruit_LED_Backpack** (from https://github.com/adafruit/Adafruit_Python_LED_Backpack)

.. code-block:: bash

	git clone https://github.com/adafruit/Adafruit_Python_LED_Backpack.git
	cd Adafruit_Python_LED_Backpack
	sudo python3 setup.py install

**Install Adafruit_SSD1306** (from https://github.com/adafruit/Adafruit_Python_SSD1306)

.. code-block:: bash

	git clone https://github.com/adafruit/Adafruit_Python_SSD1306.git
	cd Adafruit_Python_SSD1306
	sudo python3 setup.py install

**Install Adafruit_IO** (from https://github.com/adafruit/io-client-python)

.. code-block:: bash

	git clone https://github.com/adafruit/io-client-python.git
	cd io-client-python
	sudo python3 setup.py install


..
	Install using PIP :bash:`sudo pip3 install adafruit-io`


..
	RESOURCES
	Raspberry Pi Zero OTG – MacOSX http://www.secuid0.net/?p=464