UCT EE Wiki - User contributions [en-gb]

Main Page

2021-02-16T11:38:04Z

CRNKEE002: Reverted edits by Swinberg (talk) to last revision by 102.140.112.36

[[Category:Management]]
<strong>Welcome to the Department of Electrical Engineering Wiki</strong>

The Department's Website is located at [https://ee.uct.ac.za ee.uct.ac.za]

This wiki is intended to give information on tools, software and hardware that make studying and research in the department easier. It is <strong>not</strong> a place to host course specific content. For that, please see [http://ocw.ee.uct.ac.za/ EE Department OpenCourseWare site].

If you have any queries, complaints, compliments, criticisms or suggestions, please send them to ucteewiki[at]gmail.com

= Using the wiki =
[[File:UsingWikimedia.jpg|right|100px|]]
Most of the time, as a user seeking information, you basically want to go to the search box at the top of the page and type in keywords related to the issue you want to find out about. According to 'wiki editing philosophy' (See [[Project:Editing]]) we are attempting to keep things marked with keyworkds and put in suitable namespaces to keep the information well index and easily searchable. If you have additional ideas on how we can improve the indexing and creation of contact, or ideas generally to improve our knowledge management practices, we would be most grateful to hear your ideas (please email them to ucteewiki[at]gmail.com).

= Main Categories =
[[File:CategoriesSearch.jpeg|right|100px|]]
The Categories are the top-level categories that pages in this wiki are arranged into. Each of the categories listed below essentially link to pages that have further links to the actual content that you may want to browser for answers to your questions, see: {{Special:Prefixindex/Category:}}

= A Hitchhiker's Guide to this Wiki =
* To view all pages on the Wiki, see [[All Pages]]
* If you'd like to learn how to create pages on this Wiki and what the philosophies of data organisation are, please see [[Project:Editing]]
* Guide on formatting: [https://meta.wikimedia.org/wiki/Help:Wikitext_examples Wikitext formatting examples]

= Other Useful Links =
* [http://hive.ee.uct.ac.za/ Hive, a single access point for all things EE]
* [http://ocw.ee.uct.ac.za/ EE Department OpenCourseWare site]
* [https://github.com/UCT-EE-OCW The UCT OCW GitHub]
* [http://wiki.ee.uct.ac.za/Templates_for_Articles,_Dissertations_and_Reports]
* [https://docs.google.com/document/d/1tp_YYqvUUViPUb_ZTzGNi4BVfWNqkrOlXcdM63DAwWY/edit Justin's Useful Linker (White Lab Links)]

VHDL

2021-01-28T11:00:10Z

CRNKEE002: /* VHDL Operators */

[[Category:FPGAs]][[Category:Software]]
VHDL stands for VHSIC-HDL, which in turn stands for Very High Speed Integrated Circuit Hardware Description Language. It is one way in which hardware can be described.
The guide below was adapted by notes originally written by Samuel Ginsberg, which can be downloaded as a PDF here. [[File:VHDL Notes 2016 updated SamuelGinsberg.pdf]]

= Structure and Behaviour =
There are two fundamentally different ways of specifying logic. The first method is to specify the structure of the logic and the other method is to specify the behaviour of the system.

<span class="mw-customtoggle-StructureandBehaviour" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-StructureandBehaviour" class="mw-collapsible mw-collapsed">

== Structure ==
<span class="mw-customtoggle-Structure" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-Structure" class="mw-collapsible mw-collapsed">
The structure of a system describes that system in terms of "what is connected to what". The system is thus broken down into smaller units which are connected together to form a whole. The whole unit is called an entity. Inputs and outputs to/from the entity are called ports.

TODO: IMAGE

In this illustration the overall entity is called Z. The input ports are called A, B and C. The output ports are called D and E. The interconnections inside the entity Z are called signals. You will observe that X and Y are themselves entities. The entities X and Y would in turn have to be specified in terms of either their behaviour or their structure. This nested definition system implies that by using structural descriptions very big and complex blocks may be built up out of a number of simple blocks. This is fundamental to problem solving of almost any type.
</div>

== Behaviour ==
<span class="mw-customtoggle-Behaviour" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-Behaviour" class="mw-collapsible mw-collapsed">
You will see that structural descriptions are extremely useful for building systems from smaller components. Ultimately we need to specify what each component actually does. In this case structural descriptions are of limited use. We need some way of describing the behaviour of the entities that we use. At the very minimum we need to specify the behaviour of the entities at the bottom of the hierarchical structure. VHDL thus provides a means of specifying the behaviour of entities by means of a behavioural description. Behavioural descriptions resemble a programming language. We will discuss syntax as we need it to implement the concepts that follow. Please bear in mind as we go that, despite the similarities, a VHDL description is a hardware description, and that the analogy to a programming language is actually fairly weak.
</div>

== Entities ==
<span class="mw-customtoggle-Entities" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-Entities" class="mw-collapsible mw-collapsed">
As we have mentioned an entity is a "box" with inputs and outputs called ports. We need to give the ports names and associate them with an entity. Here is an example of this:

<syntaxhighlight lang="vhdl" line='line'>
entity hadder is
port
(inA, inB : in std_logic;
sum,carry : out std_logic); --note the semicolon
end hadder;
</syntaxhighlight>

This entity declaration states that we are creating an entity called hadder. This entity has two inputs called inA and inB and two outputs called sum and carry. Further we have declared that the ports are all 'std_logic' values. A std_logic value is basically a binary bit, which can take on the value 0 and 1. Std_logic bits can also take on a few other states, such as high impedance and undefined, in order to closely model the behaviour of real logic bits. The entity is shown graphically here:

TODO: IMAGE
</div>

== Architectures ==
<span class="mw-customtoggle-Architectures" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-Architectures" class="mw-collapsible mw-collapsed">
Once we have declared the entity we need to describe how it works. We use an architecture to do this. We could use either a structural description or a behavioural one.

Suppose for the sake of the illustration that the above entity implements a half adder. Our adder's circuit diagram is as follows:

TODO: IMAGE

Here is an example of structural description:
<syntaxhighlight lang="vhdl" line='line'>
architecture structure of hadder is
--We now need to describe the interface to the components that we are
--using. These components are described in the ALTERA MAXPLUS2 library.
component a_7408 --AND gate
port (a_2: in STD_LOGIC;
a_3: in STD_LOGIC;
a_1: out STD_LOGIC);
end component;
component a_7486 --XOR gate
port (a_2: in STD_LOGIC;
a_3: in STD_LOGIC;
a_1: out STD_LOGIC);
end component;
--Signals are like wires used to connect components
signal inputA,inputB : std_logic;
begin
--see equivalent diagram in notes to understand this.
inputA<=inA;
inputB<=inB;
myAND: a_7408 port map (a_2=>inputA,a_3=>inputB,a_1=>carry);
myXOR: a_7486 port map (a_2=>inputA,a_3=>inputB,a_1=>sum);
end structure;
</syntaxhighlight>

The first thing that we do is state which components are contained in our box. These are an AND gate and an XOR gate. We also define the ports of these components. Note that the components were created previously and we are only using them here. We then define two signals. These signals are the internal "wires" which connect components together. The signals are inputA and inputB.

After we have defined all of the types of things that go into our description we need to instantiate them. We do that in the next section of code. We make an instance of the AND gate called myAND and an instance of the XOR gate called myXOR. When we instantiate the components we list how the inputs are connected to the signals. This effectively creates a netlist. A netlist is a list of how components connect together. The first two statements connect the internal signals inputA and inputB to the input ports, as shown in the circuit diagram.
</div>

</div>

= Processes =
<span class="mw-customtoggle-Processes" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-Processes" class="mw-collapsible mw-collapsed">
We sometimes want a set of VHDL statements to execute sequentially, one after the other. This allows us to build up a set of instructions that are 'executed' one after the other. The execution of this list is triggered by some event happening, very often on a port of the entity.

As an example consider this simple flip flop design:

<syntaxhighlight lang="vhdl" line='line'>
LIBRARY ieee;
USE ieee.std_logic_1164.all;
ENTITY test_proc1 IS
PORT
(D_input : IN STD_LOGIC;
clk_input : IN STD_LOGIC;
Q_output : OUT STD_LOGIC);
END test_proc1;
ARCHITECTURE a OF test_proc1 IS
BEGIN
PROCESS (clk_input) --trigger this when clk_input changes
BEGIN
if (clk_input='1') then
Q_output <= D_input;
end if;
END
</syntaxhighlight>

In this example we are describing the behavior of a D type flip flop. The flip flop's D input is transferred to the Q output and held there on the rising edge of the clock signal.
We declare an entity as before.

The architecture begins with the keyword 'Process' followed by a list of port names, in this case clk_input. This list is called a 'sensitivity list'. Whenever one (or more) of the items in the sensitivity list changes the code that is contained in the process is executed. In this example when clk_input changes, the code within the process is executed. This code examines the state of the clk_input bit and if it is high the Q output is updated to be equal to the D input. We achieve the rising edge triggered action by looking for a change in clk_input and then examining to see if the change was a rising or a falling edge.

</div>

= Variables =
<span class="mw-customtoggle-Variables" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-Variables" class="mw-collapsible mw-collapsed">
It is possible to have variables in an architecture. Variables are used to store data within a process. Signals differ from variables in that variables cannot trigger events, nor can a change in a variable trigger a process.

Furthermore, signal values within a process change only when the process is completed, whereas variables are evaluated immediately.

Variables are modified with the variable assignment operator which is :=, thus assigning one variable to another is done as follows:

<syntaxhighlight lang="vhdl" line='line'>
one_variable := another_variable;
</syntaxhighlight>
</div>

= VHDL Syntax =
<span class="mw-customtoggle-Syntax" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-Syntax" class="mw-collapsible mw-collapsed">
== Comments ==
Comments are preceded by "--" (two dashes) and extend to the end of the line. Multiline comments are not available, but some code editors provide a multiline comment feature.

== Identifiers ==
Identifiers are names of signals, variables, components etc. etc. The names must all begin with a letter. After the initial letter they may have any combination of letters, numbers and underscores. VHDL is not case sensitive.

== Numbers ==
VHDL has support for a very wide range of number representations.

Numbers may be in any base between 2 and 16. The hash (#) separator is used to separate the base from the rest of the number, by surrounding the number. e.g. 2#10101010# =10101010 base 2. Note that the base is an integer expressed in base 10.

Real literals may have decimal points. These numbers are real numbers with a fixed fractional part. The VHDL standard supports floating point numbers although some VHDL compilers do not. Floating point operations are extremely expensive to implement because of the inefficiency incurred in synthesizing the floating point operations. e.g. 3.1415 is a fixed point real number.

Remember that VHDL only looks like a programming language. Bear in mind that when you use a floating point number the required operation has to be constructed out of gates when the design is put onto a chip. Numbers may have exponents. The exponents are expressed in decimal and may only be integers. Exponents may be positive or negative. The exponent is signified by an 'E'. The exponent is raised to the base. For example, a number expressed in base 2 will be multiplied by 2 to the power of the exponent.

Example: 2#1010#E1=1010*2^1=10100=20 decimal.

Here is an example of VHDL using integer types:
<syntaxhighlight lang="vhdl" line='line'>
entity Code_Example is
port (clock : In std_logic;
sel : In std_logic;
output: Out integer range 0 to 255);
end Code_Example;

architecture archy of Code_Example is
begin
process (clock)
begin
if clock='1' then
if sel='1' then
output<=16#55#;
else
output<=2#1010_1010#;
end if;
end if;
end process;
end archy;
</syntaxhighlight>

Integer types are used for representing numbers with no fractional part. VHDL guarantees that integers will be represented by at least 32 bits. Integers are signed. We can limit the range of integers by using the range keyword. This is useful for limiting the size of the representation and for making your code more compiler independent. In general limit your range to the size that you need. When we limit the range of a type we obtain a <i>Subtype</i>.

When limiting the range of an integer only the size of the representation is limited, not the actual range of the number. As an example if we said <code>dout: OUT integer range 0 to 2</code> in the example above we would still have had a 2 bit counter. The code that could be represented on those 2 bits would still include “11”, even though it is outside of our defined range. Some simulation packages would flag a warning if this occurs, but many would not.

When using an integer as a port, the port will have as many physical lines as are needed to represent the integer using standard binary coding. Thus, in the example above, 'dout' will be represented by two physical port lines.

== Characters and Strings ==
Characters are enclosed in single quotation marks and are equivalent to their ASCII number. e.g. '0'=48

Strings are enclosed in double quotation marks. Example "Samuel" To include a double quotation mark inside quotation marks use it twice "Fred said""hello"".

Strings may be formed in other number bases. These bases are binary, octal and hex.

<syntaxhighlight lang="vhdl" line='line'>

entity Code_Example is
port (clock : In std_logic;
sel : In Std_logic;
output: Out std_logic_vector (7 downto 0));
end Code_Example;
architecture archy of Code_Example is
begin
process (clock)
begin
if clock='1' then
if sel='1' then
output<="01010101"; --binary string. Use a string to fill vector
else
output<=X"FF"; --Hexadecimal string
end if;
end if;
end process;
</syntaxhighlight>

== Enumerated Types ==
VHDL provides enumerated types for convenience. We have already come across one of these, std_logic, in which the logic states are represented as an enumerated type having nine different states which represent different electrical possibilities available on logic signals.

<syntaxhighlight lang="vhdl" line='line'>
entity Code_Example is
port (clock : In std_logic;
output: Out integer range 0 to 1);
end Code_Example;
architecture archy of Code_Example is
type colour is (green, blue);
--declare types in architecture declarative section
begin
process (clock)
variable status: colour;
--declare variables in process declarative section
begin
if clock='1' then
if status =green then
output<=1;
status:=blue;
else
output<=0;
status:=green;
end if;
end if;
end process;
end archy;
</syntaxhighlight>

== Arrays ==
These have the same meaning that you are used to. Arrays may have any number of dimensions and may be formed from any supported type, or previously defined type.

There are predefined types, such as strings and bit vectors.

The definition for the string type is given as follows:
<syntaxhighlight lang="vhdl">
type string is array (positive range <>) of character;
</syntaxhighlight>

The definition for bit vectors is as follows:
<syntaxhighlight lang="vhdl">
type bit_vector is array (natural range <>) of bit;
</syntaxhighlight>

The "<>" angle brackets are called a box. They are placeholders which indicate that the range will be filled in when the types are used.

Bit vectors are essentially an array of bits used for binary numbers. Here is an example of the usage of a bit
vector:
<syntaxhighlight lang="vhdl">
din: in bit_vector (2 downto 0);
</syntaxhighlight>
In this case the box will be filled in with the range 2 downto 0.

Arrays may be indexed to access individual elements. If we wish to access the first bit in din then we can say:
<code>if din(2)='1' then....</code>

Note that in the case of bit vectors when we specify the range we are specifying an array index. As a result, we are not specifying the numerical range, but rather the actual number of bits in the array.

If we use the “downto” keyword then the most significant bit will occupy the highest numbered array position. The opposite will apply if we use the “to” keyword.

We will not use bit vectors much, rather we will use 'standard logic vectors' which are more widely supported. The reason for this is that most of the libraries that are available for our VHDL system are defined in terms of standard logic vectors, rather than bit vectors. The behavior of std_logic_vectors is however very similar to the bit vector, except that, as noted above, std_logic has more possible states.

See above for examples of std_logic_vector usage.

</div>

= VHDL Operators =
Like any language VHDL has a set of operators. These operators may be divided into three types: Logical, arithmetic and comparison.

<span class="mw-customtoggle-Operators" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-Operators" class="mw-collapsible mw-collapsed">

== Logical Operators ==
Logical operators are used to derive logical results from bits and bit_vectors. When used with bit_vectors the operators act in a bitwise manner. When used with bit_vectors, those vectors must be of the same length.
The logical operators are as follows:
* NOT
* AND
* OR
* NAND
* NOR
* XOR
These should require no further explanation.
In addition there is a concatenation operator. This is the ampersand "&". This concatenates two bit vectors.
Example:
<syntaxhighlight lang="vhdl" line='line'>
signal a: bit_vector (1 to 3);
signal b: bit_vector (1 to 5);
signal c: bit_vector (1 to 8);
c <= a & b; --legal concatenation operation.
</syntaxhighlight>

== Arithmetic Operators ==
These operators perform basic arithmetic operations on numbers. Normally these operations are only intended for use on integers. Some VHDL suites come with libraries which contain arithmetic functions for use with bit_vectors and std_logic vectors.

The operators are:
* addition (+)
* subtraction (-)
* multiplication (*)
* division (/)

The only caution that applies here is that some packages only support multiplication and division by integer powers of two. This in effect reduces multiplication and division to the status of arithmetic shift operations.

== Comparison Operators ==
These operators are used to compare two scalar or bit_vector arguments and they return 'true ' or 'false'. If bit_vectors are compared then the vectors must be of the same length.
{|
| <
| smaller than
|-
| <=
| smaller than or equal
|-
| >
| greater than
|-
| >=
| greater than or equal
|-
| =
| equal
|-
| /=
|not equal
|}

</div>

= Attributes of Objects =
Attributes are properties of VHDL types that can be very useful. We use attributes to extract further information about a VHDL object.

<span class="mw-customtoggle-AoO" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-AoO" class="mw-collapsible mw-collapsed">

All attributes are accessed by using the apostrophe ' operator, sometimes pronounced “tick”. In theory attributes are classified by what sort of thing they return, but in authoritative sources (compare Ashenden 2008 to Perry 2002) they are dealt with in quite different ways. For purposes of this course we will be quite loose in our handling of attributes, aiming for utility rather than formal correctness.

== Attributes of Signals ==
These attributes either derive information about signals or define new signals based on other signals. We have seen one of these already, the 'event attribute. This attribute creates a signal that is true when its base signal has changed in the last cycle. Examples have been shown above. There is also a 'last_value attribute which returns the value of a signal prior to its last transition.

There are many more of these attributes, however many of them are for simulation purposes only and cannot be directly synthesized to hardware. These would typically be used for generating testbenches.

== Attributes of Scalar Types ==

'pos – str'pos ("fred") gives the position of fred in the string str.

'val – Var'val(x) gives the value at position x of variable var.

'leftof – value in a variable to the left of a specified position.

'rightof – value in a variable to the right of a specified position.

'pred – value of a preceding position. Depends on range direction.

'succ – value of a succeeding position. Depends on range direction.

Note that not all of these attributes apply to all types. Most of the above are useful with enumerated types. If an array is declared with a range of indices from 10 to 30 then Array'left will return 10.

Example:
Suppose we have the following declarations:
<syntaxhighlight lang="vhdl">
lsb_output: OUT std_logic --declare a bit-wide port
signal count_signal_name : STD_LOGIC_VECTOR (3 downto 0); --declare a 4 bit wide signal
</syntaxhighlight>

Then the following line extracts the least significant bit from the signal and assigns it to the port:
<syntaxhighlight lang="vhdl">
lsb_output <= count_signal_name (count_signal_name'right);
</syntaxhighlight>
This is useful for making procedures which handle arrays independently of the array width.

</div>

= More on Processes =
= Changing Execution Flow in VHDL =
= Dividing Big Jobs into Little Jobs =
= Packages =
= Conversion Functions =
= Megafunctions =

VHDL

2021-01-28T10:59:53Z

CRNKEE002: /* Attributes of Objects */

[[Category:FPGAs]][[Category:Software]]
VHDL stands for VHSIC-HDL, which in turn stands for Very High Speed Integrated Circuit Hardware Description Language. It is one way in which hardware can be described.
The guide below was adapted by notes originally written by Samuel Ginsberg, which can be downloaded as a PDF here. [[File:VHDL Notes 2016 updated SamuelGinsberg.pdf]]

= Structure and Behaviour =
There are two fundamentally different ways of specifying logic. The first method is to specify the structure of the logic and the other method is to specify the behaviour of the system.

<span class="mw-customtoggle-StructureandBehaviour" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-StructureandBehaviour" class="mw-collapsible mw-collapsed">

== Structure ==
<span class="mw-customtoggle-Structure" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-Structure" class="mw-collapsible mw-collapsed">
The structure of a system describes that system in terms of "what is connected to what". The system is thus broken down into smaller units which are connected together to form a whole. The whole unit is called an entity. Inputs and outputs to/from the entity are called ports.

TODO: IMAGE

In this illustration the overall entity is called Z. The input ports are called A, B and C. The output ports are called D and E. The interconnections inside the entity Z are called signals. You will observe that X and Y are themselves entities. The entities X and Y would in turn have to be specified in terms of either their behaviour or their structure. This nested definition system implies that by using structural descriptions very big and complex blocks may be built up out of a number of simple blocks. This is fundamental to problem solving of almost any type.
</div>

== Behaviour ==
<span class="mw-customtoggle-Behaviour" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-Behaviour" class="mw-collapsible mw-collapsed">
You will see that structural descriptions are extremely useful for building systems from smaller components. Ultimately we need to specify what each component actually does. In this case structural descriptions are of limited use. We need some way of describing the behaviour of the entities that we use. At the very minimum we need to specify the behaviour of the entities at the bottom of the hierarchical structure. VHDL thus provides a means of specifying the behaviour of entities by means of a behavioural description. Behavioural descriptions resemble a programming language. We will discuss syntax as we need it to implement the concepts that follow. Please bear in mind as we go that, despite the similarities, a VHDL description is a hardware description, and that the analogy to a programming language is actually fairly weak.
</div>

== Entities ==
<span class="mw-customtoggle-Entities" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-Entities" class="mw-collapsible mw-collapsed">
As we have mentioned an entity is a "box" with inputs and outputs called ports. We need to give the ports names and associate them with an entity. Here is an example of this:

<syntaxhighlight lang="vhdl" line='line'>
entity hadder is
port
(inA, inB : in std_logic;
sum,carry : out std_logic); --note the semicolon
end hadder;
</syntaxhighlight>

This entity declaration states that we are creating an entity called hadder. This entity has two inputs called inA and inB and two outputs called sum and carry. Further we have declared that the ports are all 'std_logic' values. A std_logic value is basically a binary bit, which can take on the value 0 and 1. Std_logic bits can also take on a few other states, such as high impedance and undefined, in order to closely model the behaviour of real logic bits. The entity is shown graphically here:

TODO: IMAGE
</div>

== Architectures ==
<span class="mw-customtoggle-Architectures" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-Architectures" class="mw-collapsible mw-collapsed">
Once we have declared the entity we need to describe how it works. We use an architecture to do this. We could use either a structural description or a behavioural one.

Suppose for the sake of the illustration that the above entity implements a half adder. Our adder's circuit diagram is as follows:

TODO: IMAGE

Here is an example of structural description:
<syntaxhighlight lang="vhdl" line='line'>
architecture structure of hadder is
--We now need to describe the interface to the components that we are
--using. These components are described in the ALTERA MAXPLUS2 library.
component a_7408 --AND gate
port (a_2: in STD_LOGIC;
a_3: in STD_LOGIC;
a_1: out STD_LOGIC);
end component;
component a_7486 --XOR gate
port (a_2: in STD_LOGIC;
a_3: in STD_LOGIC;
a_1: out STD_LOGIC);
end component;
--Signals are like wires used to connect components
signal inputA,inputB : std_logic;
begin
--see equivalent diagram in notes to understand this.
inputA<=inA;
inputB<=inB;
myAND: a_7408 port map (a_2=>inputA,a_3=>inputB,a_1=>carry);
myXOR: a_7486 port map (a_2=>inputA,a_3=>inputB,a_1=>sum);
end structure;
</syntaxhighlight>

The first thing that we do is state which components are contained in our box. These are an AND gate and an XOR gate. We also define the ports of these components. Note that the components were created previously and we are only using them here. We then define two signals. These signals are the internal "wires" which connect components together. The signals are inputA and inputB.

After we have defined all of the types of things that go into our description we need to instantiate them. We do that in the next section of code. We make an instance of the AND gate called myAND and an instance of the XOR gate called myXOR. When we instantiate the components we list how the inputs are connected to the signals. This effectively creates a netlist. A netlist is a list of how components connect together. The first two statements connect the internal signals inputA and inputB to the input ports, as shown in the circuit diagram.
</div>

</div>

= Processes =
<span class="mw-customtoggle-Processes" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-Processes" class="mw-collapsible mw-collapsed">
We sometimes want a set of VHDL statements to execute sequentially, one after the other. This allows us to build up a set of instructions that are 'executed' one after the other. The execution of this list is triggered by some event happening, very often on a port of the entity.

As an example consider this simple flip flop design:

<syntaxhighlight lang="vhdl" line='line'>
LIBRARY ieee;
USE ieee.std_logic_1164.all;
ENTITY test_proc1 IS
PORT
(D_input : IN STD_LOGIC;
clk_input : IN STD_LOGIC;
Q_output : OUT STD_LOGIC);
END test_proc1;
ARCHITECTURE a OF test_proc1 IS
BEGIN
PROCESS (clk_input) --trigger this when clk_input changes
BEGIN
if (clk_input='1') then
Q_output <= D_input;
end if;
END
</syntaxhighlight>

In this example we are describing the behavior of a D type flip flop. The flip flop's D input is transferred to the Q output and held there on the rising edge of the clock signal.
We declare an entity as before.

The architecture begins with the keyword 'Process' followed by a list of port names, in this case clk_input. This list is called a 'sensitivity list'. Whenever one (or more) of the items in the sensitivity list changes the code that is contained in the process is executed. In this example when clk_input changes, the code within the process is executed. This code examines the state of the clk_input bit and if it is high the Q output is updated to be equal to the D input. We achieve the rising edge triggered action by looking for a change in clk_input and then examining to see if the change was a rising or a falling edge.

</div>

= Variables =
<span class="mw-customtoggle-Variables" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-Variables" class="mw-collapsible mw-collapsed">
It is possible to have variables in an architecture. Variables are used to store data within a process. Signals differ from variables in that variables cannot trigger events, nor can a change in a variable trigger a process.

Furthermore, signal values within a process change only when the process is completed, whereas variables are evaluated immediately.

Variables are modified with the variable assignment operator which is :=, thus assigning one variable to another is done as follows:

<syntaxhighlight lang="vhdl" line='line'>
one_variable := another_variable;
</syntaxhighlight>
</div>

= VHDL Syntax =
<span class="mw-customtoggle-Syntax" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-Syntax" class="mw-collapsible mw-collapsed">
== Comments ==
Comments are preceded by "--" (two dashes) and extend to the end of the line. Multiline comments are not available, but some code editors provide a multiline comment feature.

== Identifiers ==
Identifiers are names of signals, variables, components etc. etc. The names must all begin with a letter. After the initial letter they may have any combination of letters, numbers and underscores. VHDL is not case sensitive.

== Numbers ==
VHDL has support for a very wide range of number representations.

Numbers may be in any base between 2 and 16. The hash (#) separator is used to separate the base from the rest of the number, by surrounding the number. e.g. 2#10101010# =10101010 base 2. Note that the base is an integer expressed in base 10.

Real literals may have decimal points. These numbers are real numbers with a fixed fractional part. The VHDL standard supports floating point numbers although some VHDL compilers do not. Floating point operations are extremely expensive to implement because of the inefficiency incurred in synthesizing the floating point operations. e.g. 3.1415 is a fixed point real number.

Remember that VHDL only looks like a programming language. Bear in mind that when you use a floating point number the required operation has to be constructed out of gates when the design is put onto a chip. Numbers may have exponents. The exponents are expressed in decimal and may only be integers. Exponents may be positive or negative. The exponent is signified by an 'E'. The exponent is raised to the base. For example, a number expressed in base 2 will be multiplied by 2 to the power of the exponent.

Example: 2#1010#E1=1010*2^1=10100=20 decimal.

Here is an example of VHDL using integer types:
<syntaxhighlight lang="vhdl" line='line'>
entity Code_Example is
port (clock : In std_logic;
sel : In std_logic;
output: Out integer range 0 to 255);
end Code_Example;

architecture archy of Code_Example is
begin
process (clock)
begin
if clock='1' then
if sel='1' then
output<=16#55#;
else
output<=2#1010_1010#;
end if;
end if;
end process;
end archy;
</syntaxhighlight>

Integer types are used for representing numbers with no fractional part. VHDL guarantees that integers will be represented by at least 32 bits. Integers are signed. We can limit the range of integers by using the range keyword. This is useful for limiting the size of the representation and for making your code more compiler independent. In general limit your range to the size that you need. When we limit the range of a type we obtain a <i>Subtype</i>.

When limiting the range of an integer only the size of the representation is limited, not the actual range of the number. As an example if we said <code>dout: OUT integer range 0 to 2</code> in the example above we would still have had a 2 bit counter. The code that could be represented on those 2 bits would still include “11”, even though it is outside of our defined range. Some simulation packages would flag a warning if this occurs, but many would not.

When using an integer as a port, the port will have as many physical lines as are needed to represent the integer using standard binary coding. Thus, in the example above, 'dout' will be represented by two physical port lines.

== Characters and Strings ==
Characters are enclosed in single quotation marks and are equivalent to their ASCII number. e.g. '0'=48

Strings are enclosed in double quotation marks. Example "Samuel" To include a double quotation mark inside quotation marks use it twice "Fred said""hello"".

Strings may be formed in other number bases. These bases are binary, octal and hex.

<syntaxhighlight lang="vhdl" line='line'>

entity Code_Example is
port (clock : In std_logic;
sel : In Std_logic;
output: Out std_logic_vector (7 downto 0));
end Code_Example;
architecture archy of Code_Example is
begin
process (clock)
begin
if clock='1' then
if sel='1' then
output<="01010101"; --binary string. Use a string to fill vector
else
output<=X"FF"; --Hexadecimal string
end if;
end if;
end process;
</syntaxhighlight>

== Enumerated Types ==
VHDL provides enumerated types for convenience. We have already come across one of these, std_logic, in which the logic states are represented as an enumerated type having nine different states which represent different electrical possibilities available on logic signals.

<syntaxhighlight lang="vhdl" line='line'>
entity Code_Example is
port (clock : In std_logic;
output: Out integer range 0 to 1);
end Code_Example;
architecture archy of Code_Example is
type colour is (green, blue);
--declare types in architecture declarative section
begin
process (clock)
variable status: colour;
--declare variables in process declarative section
begin
if clock='1' then
if status =green then
output<=1;
status:=blue;
else
output<=0;
status:=green;
end if;
end if;
end process;
end archy;
</syntaxhighlight>

== Arrays ==
These have the same meaning that you are used to. Arrays may have any number of dimensions and may be formed from any supported type, or previously defined type.

There are predefined types, such as strings and bit vectors.

The definition for the string type is given as follows:
<syntaxhighlight lang="vhdl">
type string is array (positive range <>) of character;
</syntaxhighlight>

The definition for bit vectors is as follows:
<syntaxhighlight lang="vhdl">
type bit_vector is array (natural range <>) of bit;
</syntaxhighlight>

The "<>" angle brackets are called a box. They are placeholders which indicate that the range will be filled in when the types are used.

Bit vectors are essentially an array of bits used for binary numbers. Here is an example of the usage of a bit
vector:
<syntaxhighlight lang="vhdl">
din: in bit_vector (2 downto 0);
</syntaxhighlight>
In this case the box will be filled in with the range 2 downto 0.

Arrays may be indexed to access individual elements. If we wish to access the first bit in din then we can say:
<code>if din(2)='1' then....</code>

Note that in the case of bit vectors when we specify the range we are specifying an array index. As a result, we are not specifying the numerical range, but rather the actual number of bits in the array.

If we use the “downto” keyword then the most significant bit will occupy the highest numbered array position. The opposite will apply if we use the “to” keyword.

We will not use bit vectors much, rather we will use 'standard logic vectors' which are more widely supported. The reason for this is that most of the libraries that are available for our VHDL system are defined in terms of standard logic vectors, rather than bit vectors. The behavior of std_logic_vectors is however very similar to the bit vector, except that, as noted above, std_logic has more possible states.

See above for examples of std_logic_vector usage.

</div>

= VHDL Operators =
<span class="mw-customtoggle-Operators" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-Operators" class="mw-collapsible mw-collapsed">

Like any language VHDL has a set of operators. These operators may be divided into three types: Logical, arithmetic and comparison.

== Logical Operators ==
Logical operators are used to derive logical results from bits and bit_vectors. When used with bit_vectors the operators act in a bitwise manner. When used with bit_vectors, those vectors must be of the same length.
The logical operators are as follows:
* NOT
* AND
* OR
* NAND
* NOR
* XOR
These should require no further explanation.
In addition there is a concatenation operator. This is the ampersand "&". This concatenates two bit vectors.
Example:
<syntaxhighlight lang="vhdl" line='line'>
signal a: bit_vector (1 to 3);
signal b: bit_vector (1 to 5);
signal c: bit_vector (1 to 8);
c <= a & b; --legal concatenation operation.
</syntaxhighlight>

== Arithmetic Operators ==
These operators perform basic arithmetic operations on numbers. Normally these operations are only intended for use on integers. Some VHDL suites come with libraries which contain arithmetic functions for use with bit_vectors and std_logic vectors.

The operators are:
* addition (+)
* subtraction (-)
* multiplication (*)
* division (/)

The only caution that applies here is that some packages only support multiplication and division by integer powers of two. This in effect reduces multiplication and division to the status of arithmetic shift operations.

== Comparison Operators ==
These operators are used to compare two scalar or bit_vector arguments and they return 'true ' or 'false'. If bit_vectors are compared then the vectors must be of the same length.
{|
| <
| smaller than
|-
| <=
| smaller than or equal
|-
| >
| greater than
|-
| >=
| greater than or equal
|-
| =
| equal
|-
| /=
|not equal
|}

</div>

= Attributes of Objects =
Attributes are properties of VHDL types that can be very useful. We use attributes to extract further information about a VHDL object.

<span class="mw-customtoggle-AoO" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-AoO" class="mw-collapsible mw-collapsed">

All attributes are accessed by using the apostrophe ' operator, sometimes pronounced “tick”. In theory attributes are classified by what sort of thing they return, but in authoritative sources (compare Ashenden 2008 to Perry 2002) they are dealt with in quite different ways. For purposes of this course we will be quite loose in our handling of attributes, aiming for utility rather than formal correctness.

== Attributes of Signals ==
These attributes either derive information about signals or define new signals based on other signals. We have seen one of these already, the 'event attribute. This attribute creates a signal that is true when its base signal has changed in the last cycle. Examples have been shown above. There is also a 'last_value attribute which returns the value of a signal prior to its last transition.

There are many more of these attributes, however many of them are for simulation purposes only and cannot be directly synthesized to hardware. These would typically be used for generating testbenches.

== Attributes of Scalar Types ==

'pos – str'pos ("fred") gives the position of fred in the string str.

'val – Var'val(x) gives the value at position x of variable var.

'leftof – value in a variable to the left of a specified position.

'rightof – value in a variable to the right of a specified position.

'pred – value of a preceding position. Depends on range direction.

'succ – value of a succeeding position. Depends on range direction.

Note that not all of these attributes apply to all types. Most of the above are useful with enumerated types. If an array is declared with a range of indices from 10 to 30 then Array'left will return 10.

Example:
Suppose we have the following declarations:
<syntaxhighlight lang="vhdl">
lsb_output: OUT std_logic --declare a bit-wide port
signal count_signal_name : STD_LOGIC_VECTOR (3 downto 0); --declare a 4 bit wide signal
</syntaxhighlight>

Then the following line extracts the least significant bit from the signal and assigns it to the port:
<syntaxhighlight lang="vhdl">
lsb_output <= count_signal_name (count_signal_name'right);
</syntaxhighlight>
This is useful for making procedures which handle arrays independently of the array width.

</div>

= More on Processes =
= Changing Execution Flow in VHDL =
= Dividing Big Jobs into Little Jobs =
= Packages =
= Conversion Functions =
= Megafunctions =

VHDL

2021-01-28T10:53:40Z

CRNKEE002:

[[Category:FPGAs]][[Category:Software]]
VHDL stands for VHSIC-HDL, which in turn stands for Very High Speed Integrated Circuit Hardware Description Language. It is one way in which hardware can be described.
The guide below was adapted by notes originally written by Samuel Ginsberg, which can be downloaded as a PDF here. [[File:VHDL Notes 2016 updated SamuelGinsberg.pdf]]

= Structure and Behaviour =
There are two fundamentally different ways of specifying logic. The first method is to specify the structure of the logic and the other method is to specify the behaviour of the system.

<span class="mw-customtoggle-StructureandBehaviour" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-StructureandBehaviour" class="mw-collapsible mw-collapsed">

== Structure ==
<span class="mw-customtoggle-Structure" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-Structure" class="mw-collapsible mw-collapsed">
The structure of a system describes that system in terms of "what is connected to what". The system is thus broken down into smaller units which are connected together to form a whole. The whole unit is called an entity. Inputs and outputs to/from the entity are called ports.

TODO: IMAGE

In this illustration the overall entity is called Z. The input ports are called A, B and C. The output ports are called D and E. The interconnections inside the entity Z are called signals. You will observe that X and Y are themselves entities. The entities X and Y would in turn have to be specified in terms of either their behaviour or their structure. This nested definition system implies that by using structural descriptions very big and complex blocks may be built up out of a number of simple blocks. This is fundamental to problem solving of almost any type.
</div>

== Behaviour ==
<span class="mw-customtoggle-Behaviour" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-Behaviour" class="mw-collapsible mw-collapsed">
You will see that structural descriptions are extremely useful for building systems from smaller components. Ultimately we need to specify what each component actually does. In this case structural descriptions are of limited use. We need some way of describing the behaviour of the entities that we use. At the very minimum we need to specify the behaviour of the entities at the bottom of the hierarchical structure. VHDL thus provides a means of specifying the behaviour of entities by means of a behavioural description. Behavioural descriptions resemble a programming language. We will discuss syntax as we need it to implement the concepts that follow. Please bear in mind as we go that, despite the similarities, a VHDL description is a hardware description, and that the analogy to a programming language is actually fairly weak.
</div>

== Entities ==
<span class="mw-customtoggle-Entities" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-Entities" class="mw-collapsible mw-collapsed">
As we have mentioned an entity is a "box" with inputs and outputs called ports. We need to give the ports names and associate them with an entity. Here is an example of this:

<syntaxhighlight lang="vhdl" line='line'>
entity hadder is
port
(inA, inB : in std_logic;
sum,carry : out std_logic); --note the semicolon
end hadder;
</syntaxhighlight>

This entity declaration states that we are creating an entity called hadder. This entity has two inputs called inA and inB and two outputs called sum and carry. Further we have declared that the ports are all 'std_logic' values. A std_logic value is basically a binary bit, which can take on the value 0 and 1. Std_logic bits can also take on a few other states, such as high impedance and undefined, in order to closely model the behaviour of real logic bits. The entity is shown graphically here:

TODO: IMAGE
</div>

== Architectures ==
<span class="mw-customtoggle-Architectures" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-Architectures" class="mw-collapsible mw-collapsed">
Once we have declared the entity we need to describe how it works. We use an architecture to do this. We could use either a structural description or a behavioural one.

Suppose for the sake of the illustration that the above entity implements a half adder. Our adder's circuit diagram is as follows:

TODO: IMAGE

Here is an example of structural description:
<syntaxhighlight lang="vhdl" line='line'>
architecture structure of hadder is
--We now need to describe the interface to the components that we are
--using. These components are described in the ALTERA MAXPLUS2 library.
component a_7408 --AND gate
port (a_2: in STD_LOGIC;
a_3: in STD_LOGIC;
a_1: out STD_LOGIC);
end component;
component a_7486 --XOR gate
port (a_2: in STD_LOGIC;
a_3: in STD_LOGIC;
a_1: out STD_LOGIC);
end component;
--Signals are like wires used to connect components
signal inputA,inputB : std_logic;
begin
--see equivalent diagram in notes to understand this.
inputA<=inA;
inputB<=inB;
myAND: a_7408 port map (a_2=>inputA,a_3=>inputB,a_1=>carry);
myXOR: a_7486 port map (a_2=>inputA,a_3=>inputB,a_1=>sum);
end structure;
</syntaxhighlight>

The first thing that we do is state which components are contained in our box. These are an AND gate and an XOR gate. We also define the ports of these components. Note that the components were created previously and we are only using them here. We then define two signals. These signals are the internal "wires" which connect components together. The signals are inputA and inputB.

After we have defined all of the types of things that go into our description we need to instantiate them. We do that in the next section of code. We make an instance of the AND gate called myAND and an instance of the XOR gate called myXOR. When we instantiate the components we list how the inputs are connected to the signals. This effectively creates a netlist. A netlist is a list of how components connect together. The first two statements connect the internal signals inputA and inputB to the input ports, as shown in the circuit diagram.
</div>

</div>

= Processes =
<span class="mw-customtoggle-Processes" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-Processes" class="mw-collapsible mw-collapsed">
We sometimes want a set of VHDL statements to execute sequentially, one after the other. This allows us to build up a set of instructions that are 'executed' one after the other. The execution of this list is triggered by some event happening, very often on a port of the entity.

As an example consider this simple flip flop design:

<syntaxhighlight lang="vhdl" line='line'>
LIBRARY ieee;
USE ieee.std_logic_1164.all;
ENTITY test_proc1 IS
PORT
(D_input : IN STD_LOGIC;
clk_input : IN STD_LOGIC;
Q_output : OUT STD_LOGIC);
END test_proc1;
ARCHITECTURE a OF test_proc1 IS
BEGIN
PROCESS (clk_input) --trigger this when clk_input changes
BEGIN
if (clk_input='1') then
Q_output <= D_input;
end if;
END
</syntaxhighlight>

In this example we are describing the behavior of a D type flip flop. The flip flop's D input is transferred to the Q output and held there on the rising edge of the clock signal.
We declare an entity as before.

The architecture begins with the keyword 'Process' followed by a list of port names, in this case clk_input. This list is called a 'sensitivity list'. Whenever one (or more) of the items in the sensitivity list changes the code that is contained in the process is executed. In this example when clk_input changes, the code within the process is executed. This code examines the state of the clk_input bit and if it is high the Q output is updated to be equal to the D input. We achieve the rising edge triggered action by looking for a change in clk_input and then examining to see if the change was a rising or a falling edge.

</div>

= Variables =
<span class="mw-customtoggle-Variables" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-Variables" class="mw-collapsible mw-collapsed">
It is possible to have variables in an architecture. Variables are used to store data within a process. Signals differ from variables in that variables cannot trigger events, nor can a change in a variable trigger a process.

Furthermore, signal values within a process change only when the process is completed, whereas variables are evaluated immediately.

Variables are modified with the variable assignment operator which is :=, thus assigning one variable to another is done as follows:

<syntaxhighlight lang="vhdl" line='line'>
one_variable := another_variable;
</syntaxhighlight>
</div>

= VHDL Syntax =
<span class="mw-customtoggle-Syntax" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-Syntax" class="mw-collapsible mw-collapsed">
== Comments ==
Comments are preceded by "--" (two dashes) and extend to the end of the line. Multiline comments are not available, but some code editors provide a multiline comment feature.

== Identifiers ==
Identifiers are names of signals, variables, components etc. etc. The names must all begin with a letter. After the initial letter they may have any combination of letters, numbers and underscores. VHDL is not case sensitive.

== Numbers ==
VHDL has support for a very wide range of number representations.

Numbers may be in any base between 2 and 16. The hash (#) separator is used to separate the base from the rest of the number, by surrounding the number. e.g. 2#10101010# =10101010 base 2. Note that the base is an integer expressed in base 10.

Real literals may have decimal points. These numbers are real numbers with a fixed fractional part. The VHDL standard supports floating point numbers although some VHDL compilers do not. Floating point operations are extremely expensive to implement because of the inefficiency incurred in synthesizing the floating point operations. e.g. 3.1415 is a fixed point real number.

Remember that VHDL only looks like a programming language. Bear in mind that when you use a floating point number the required operation has to be constructed out of gates when the design is put onto a chip. Numbers may have exponents. The exponents are expressed in decimal and may only be integers. Exponents may be positive or negative. The exponent is signified by an 'E'. The exponent is raised to the base. For example, a number expressed in base 2 will be multiplied by 2 to the power of the exponent.

Example: 2#1010#E1=1010*2^1=10100=20 decimal.

Here is an example of VHDL using integer types:
<syntaxhighlight lang="vhdl" line='line'>
entity Code_Example is
port (clock : In std_logic;
sel : In std_logic;
output: Out integer range 0 to 255);
end Code_Example;

architecture archy of Code_Example is
begin
process (clock)
begin
if clock='1' then
if sel='1' then
output<=16#55#;
else
output<=2#1010_1010#;
end if;
end if;
end process;
end archy;
</syntaxhighlight>

Integer types are used for representing numbers with no fractional part. VHDL guarantees that integers will be represented by at least 32 bits. Integers are signed. We can limit the range of integers by using the range keyword. This is useful for limiting the size of the representation and for making your code more compiler independent. In general limit your range to the size that you need. When we limit the range of a type we obtain a <i>Subtype</i>.

When limiting the range of an integer only the size of the representation is limited, not the actual range of the number. As an example if we said <code>dout: OUT integer range 0 to 2</code> in the example above we would still have had a 2 bit counter. The code that could be represented on those 2 bits would still include “11”, even though it is outside of our defined range. Some simulation packages would flag a warning if this occurs, but many would not.

When using an integer as a port, the port will have as many physical lines as are needed to represent the integer using standard binary coding. Thus, in the example above, 'dout' will be represented by two physical port lines.

== Characters and Strings ==
Characters are enclosed in single quotation marks and are equivalent to their ASCII number. e.g. '0'=48

Strings are enclosed in double quotation marks. Example "Samuel" To include a double quotation mark inside quotation marks use it twice "Fred said""hello"".

Strings may be formed in other number bases. These bases are binary, octal and hex.

<syntaxhighlight lang="vhdl" line='line'>

entity Code_Example is
port (clock : In std_logic;
sel : In Std_logic;
output: Out std_logic_vector (7 downto 0));
end Code_Example;
architecture archy of Code_Example is
begin
process (clock)
begin
if clock='1' then
if sel='1' then
output<="01010101"; --binary string. Use a string to fill vector
else
output<=X"FF"; --Hexadecimal string
end if;
end if;
end process;
</syntaxhighlight>

== Enumerated Types ==
VHDL provides enumerated types for convenience. We have already come across one of these, std_logic, in which the logic states are represented as an enumerated type having nine different states which represent different electrical possibilities available on logic signals.

<syntaxhighlight lang="vhdl" line='line'>
entity Code_Example is
port (clock : In std_logic;
output: Out integer range 0 to 1);
end Code_Example;
architecture archy of Code_Example is
type colour is (green, blue);
--declare types in architecture declarative section
begin
process (clock)
variable status: colour;
--declare variables in process declarative section
begin
if clock='1' then
if status =green then
output<=1;
status:=blue;
else
output<=0;
status:=green;
end if;
end if;
end process;
end archy;
</syntaxhighlight>

== Arrays ==
These have the same meaning that you are used to. Arrays may have any number of dimensions and may be formed from any supported type, or previously defined type.

There are predefined types, such as strings and bit vectors.

The definition for the string type is given as follows:
<syntaxhighlight lang="vhdl">
type string is array (positive range <>) of character;
</syntaxhighlight>

The definition for bit vectors is as follows:
<syntaxhighlight lang="vhdl">
type bit_vector is array (natural range <>) of bit;
</syntaxhighlight>

The "<>" angle brackets are called a box. They are placeholders which indicate that the range will be filled in when the types are used.

Bit vectors are essentially an array of bits used for binary numbers. Here is an example of the usage of a bit
vector:
<syntaxhighlight lang="vhdl">
din: in bit_vector (2 downto 0);
</syntaxhighlight>
In this case the box will be filled in with the range 2 downto 0.

Arrays may be indexed to access individual elements. If we wish to access the first bit in din then we can say:
<code>if din(2)='1' then....</code>

Note that in the case of bit vectors when we specify the range we are specifying an array index. As a result, we are not specifying the numerical range, but rather the actual number of bits in the array.

If we use the “downto” keyword then the most significant bit will occupy the highest numbered array position. The opposite will apply if we use the “to” keyword.

We will not use bit vectors much, rather we will use 'standard logic vectors' which are more widely supported. The reason for this is that most of the libraries that are available for our VHDL system are defined in terms of standard logic vectors, rather than bit vectors. The behavior of std_logic_vectors is however very similar to the bit vector, except that, as noted above, std_logic has more possible states.

See above for examples of std_logic_vector usage.

</div>

= VHDL Operators =
<span class="mw-customtoggle-Operators" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-Operators" class="mw-collapsible mw-collapsed">

Like any language VHDL has a set of operators. These operators may be divided into three types: Logical, arithmetic and comparison.

== Logical Operators ==
Logical operators are used to derive logical results from bits and bit_vectors. When used with bit_vectors the operators act in a bitwise manner. When used with bit_vectors, those vectors must be of the same length.
The logical operators are as follows:
* NOT
* AND
* OR
* NAND
* NOR
* XOR
These should require no further explanation.
In addition there is a concatenation operator. This is the ampersand "&". This concatenates two bit vectors.
Example:
<syntaxhighlight lang="vhdl" line='line'>
signal a: bit_vector (1 to 3);
signal b: bit_vector (1 to 5);
signal c: bit_vector (1 to 8);
c <= a & b; --legal concatenation operation.
</syntaxhighlight>

== Arithmetic Operators ==
These operators perform basic arithmetic operations on numbers. Normally these operations are only intended for use on integers. Some VHDL suites come with libraries which contain arithmetic functions for use with bit_vectors and std_logic vectors.

The operators are:
* addition (+)
* subtraction (-)
* multiplication (*)
* division (/)

The only caution that applies here is that some packages only support multiplication and division by integer powers of two. This in effect reduces multiplication and division to the status of arithmetic shift operations.

== Comparison Operators ==
These operators are used to compare two scalar or bit_vector arguments and they return 'true ' or 'false'. If bit_vectors are compared then the vectors must be of the same length.
{|
| <
| smaller than
|-
| <=
| smaller than or equal
|-
| >
| greater than
|-
| >=
| greater than or equal
|-
| =
| equal
|-
| /=
|not equal
|}

</div>

= Attributes of Objects =
= More on Processes =
= Changing Execution Flow in VHDL =
= Dividing Big Jobs into Little Jobs =
= Packages =
= Conversion Functions =
= Megafunctions =

VHDL

2021-01-27T14:51:16Z

CRNKEE002: /* VHDL Syntax */

[[Category:FPGAs]][[Category:Software]]
VHDL stands for VHSIC-HDL, which in turn stands for Very High Speed Integrated Circuit Hardware Description Language. It is one way in which hardware can be described. The guide below was adapted by notes originally written by Samuel Ginsberg, which can be downloaded as a PDF here. [[File:VHDL Notes 2016 updated SamuelGinsberg.pdf]]

= Structure and Behaviour =
There are two fundamentally different ways of specifying logic. The first method is to specify the structure of the logic and the other method is to specify the behaviour of the system.

<span class="mw-customtoggle-StructureandBehaviour" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-StructureandBehaviour" class="mw-collapsible mw-collapsed">

== Structure ==
<span class="mw-customtoggle-Structure" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-Structure" class="mw-collapsible mw-collapsed">
The structure of a system describes that system in terms of "what is connected to what". The system is thus broken down into smaller units which are connected together to form a whole. The whole unit is called an entity. Inputs and outputs to/from the entity are called ports.

TODO: IMAGE

In this illustration the overall entity is called Z. The input ports are called A, B and C. The output ports are called D and E. The interconnections inside the entity Z are called signals. You will observe that X and Y are themselves entities. The entities X and Y would in turn have to be specified in terms of either their behaviour or their structure. This nested definition system implies that by using structural descriptions very big and complex blocks may be built up out of a number of simple blocks. This is fundamental to problem solving of almost any type.
</div>

== Behaviour ==
<span class="mw-customtoggle-Behaviour" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-Behaviour" class="mw-collapsible mw-collapsed">
You will see that structural descriptions are extremely useful for building systems from smaller components. Ultimately we need to specify what each component actually does. In this case structural descriptions are of limited use. We need some way of describing the behaviour of the entities that we use. At the very minimum we need to specify the behaviour of the entities at the bottom of the hierarchical structure. VHDL thus provides a means of specifying the behaviour of entities by means of a behavioural description. Behavioural descriptions resemble a programming language. We will discuss syntax as we need it to implement the concepts that follow. Please bear in mind as we go that, despite the similarities, a VHDL description is a hardware description, and that the analogy to a programming language is actually fairly weak.
</div>

== Entities ==
<span class="mw-customtoggle-Entities" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-Entities" class="mw-collapsible mw-collapsed">
As we have mentioned an entity is a "box" with inputs and outputs called ports. We need to give the ports names and associate them with an entity. Here is an example of this:

<syntaxhighlight lang="vhdl" line='line'>
entity hadder is
port
(inA, inB : in std_logic;
sum,carry : out std_logic); --note the semicolon
end hadder;
</syntaxhighlight>

This entity declaration states that we are creating an entity called hadder. This entity has two inputs called inA and inB and two outputs called sum and carry. Further we have declared that the ports are all 'std_logic' values. A std_logic value is basically a binary bit, which can take on the value 0 and 1. Std_logic bits can also take on a few other states, such as high impedance and undefined, in order to closely model the behaviour of real logic bits. The entity is shown graphically here:

TODO: IMAGE
</div>

== Architectures ==
<span class="mw-customtoggle-Architectures" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-Architectures" class="mw-collapsible mw-collapsed">
Once we have declared the entity we need to describe how it works. We use an architecture to do this. We could use either a structural description or a behavioural one.

Suppose for the sake of the illustration that the above entity implements a half adder. Our adder's circuit diagram is as follows:

TODO: IMAGE

Here is an example of structural description:
<syntaxhighlight lang="vhdl" line='line'>
architecture structure of hadder is
--We now need to describe the interface to the components that we are
--using. These components are described in the ALTERA MAXPLUS2 library.
component a_7408 --AND gate
port (a_2: in STD_LOGIC;
a_3: in STD_LOGIC;
a_1: out STD_LOGIC);
end component;
component a_7486 --XOR gate
port (a_2: in STD_LOGIC;
a_3: in STD_LOGIC;
a_1: out STD_LOGIC);
end component;
--Signals are like wires used to connect components
signal inputA,inputB : std_logic;
begin
--see equivalent diagram in notes to understand this.
inputA<=inA;
inputB<=inB;
myAND: a_7408 port map (a_2=>inputA,a_3=>inputB,a_1=>carry);
myXOR: a_7486 port map (a_2=>inputA,a_3=>inputB,a_1=>sum);
end structure;
</syntaxhighlight>

The first thing that we do is state which components are contained in our box. These are an AND gate and an XOR gate. We also define the ports of these components. Note that the components were created previously and we are only using them here. We then define two signals. These signals are the internal "wires" which connect components together. The signals are inputA and inputB.

After we have defined all of the types of things that go into our description we need to instantiate them. We do that in the next section of code. We make an instance of the AND gate called myAND and an instance of the XOR gate called myXOR. When we instantiate the components we list how the inputs are connected to the signals. This effectively creates a netlist. A netlist is a list of how components connect together. The first two statements connect the internal signals inputA and inputB to the input ports, as shown in the circuit diagram.
</div>

</div>

= Processes =
<span class="mw-customtoggle-Processes" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-Processes" class="mw-collapsible mw-collapsed">
We sometimes want a set of VHDL statements to execute sequentially, one after the other. This allows us to build up a set of instructions that are 'executed' one after the other. The execution of this list is triggered by some event happening, very often on a port of the entity.

As an example consider this simple flip flop design:

<syntaxhighlight lang="vhdl" line='line'>
LIBRARY ieee;
USE ieee.std_logic_1164.all;
ENTITY test_proc1 IS
PORT
(D_input : IN STD_LOGIC;
clk_input : IN STD_LOGIC;
Q_output : OUT STD_LOGIC);
END test_proc1;
ARCHITECTURE a OF test_proc1 IS
BEGIN
PROCESS (clk_input) --trigger this when clk_input changes
BEGIN
if (clk_input='1') then
Q_output <= D_input;
end if;
END
</syntaxhighlight>

In this example we are describing the behavior of a D type flip flop. The flip flop's D input is transferred to the Q output and held there on the rising edge of the clock signal.
We declare an entity as before.

The architecture begins with the keyword 'Process' followed by a list of port names, in this case clk_input. This list is called a 'sensitivity list'. Whenever one (or more) of the items in the sensitivity list changes the code that is contained in the process is executed. In this example when clk_input changes, the code within the process is executed. This code examines the state of the clk_input bit and if it is high the Q output is updated to be equal to the D input. We achieve the rising edge triggered action by looking for a change in clk_input and then examining to see if the change was a rising or a falling edge.

</div>

= Variables =
<span class="mw-customtoggle-Variables" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-Variables" class="mw-collapsible mw-collapsed">
It is possible to have variables in an architecture. Variables are used to store data within a process. Signals differ from variables in that variables cannot trigger events, nor can a change in a variable trigger a process.

Furthermore, signal values within a process change only when the process is completed, whereas variables are evaluated immediately.

Variables are modified with the variable assignment operator which is :=, thus assigning one variable to another is done as follows:

<syntaxhighlight lang="vhdl" line='line'>
one_variable := another_variable;
</syntaxhighlight>
</div>

= VHDL Syntax =
<span class="mw-customtoggle-Syntax" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-Syntax" class="mw-collapsible mw-collapsed">
== Comments ==
Comments are preceded by "--" (two dashes) and extend to the end of the line. Multiline comments are not available, but some code editors provide a multiline comment feature.

== Identifiers ==
Identifiers are names of signals, variables, components etc. etc. The names must all begin with a letter. After the initial letter they may have any combination of letters, numbers and underscores. VHDL is not case sensitive.

== Numbers ==
VHDL has support for a very wide range of number representations.

Numbers may be in any base between 2 and 16. The hash (#) separator is used to separate the base from the rest of the number, by surrounding the number. e.g. 2#10101010# =10101010 base 2. Note that the base is an integer expressed in base 10.

Real literals may have decimal points. These numbers are real numbers with a fixed fractional part. The VHDL standard supports floating point numbers although some VHDL compilers do not. Floating point operations are extremely expensive to implement because of the inefficiency incurred in synthesizing the floating point operations. e.g. 3.1415 is a fixed point real number.

Remember that VHDL only looks like a programming language. Bear in mind that when you use a floating point number the required operation has to be constructed out of gates when the design is put onto a chip. Numbers may have exponents. The exponents are expressed in decimal and may only be integers. Exponents may be positive or negative. The exponent is signified by an 'E'. The exponent is raised to the base. For example, a number expressed in base 2 will be multiplied by 2 to the power of the exponent.

Example: 2#1010#E1=1010*2^1=10100=20 decimal.

Here is an example of VHDL using integer types:
<syntaxhighlight lang="vhdl" line='line'>
entity Code_Example is
port (clock : In std_logic;
sel : In std_logic;
output: Out integer range 0 to 255);
end Code_Example;

architecture archy of Code_Example is
begin
process (clock)
begin
if clock='1' then
if sel='1' then
output<=16#55#;
else
output<=2#1010_1010#;
end if;
end if;
end process;
end archy;
</syntaxhighlight>

Integer types are used for representing numbers with no fractional part. VHDL guarantees that integers will be represented by at least 32 bits. Integers are signed. We can limit the range of integers by using the range keyword. This is useful for limiting the size of the representation and for making your code more compiler independent. In general limit your range to the size that you need. When we limit the range of a type we obtain a <i>Subtype</i>.

When limiting the range of an integer only the size of the representation is limited, not the actual range of the number. As an example if we said <code>dout: OUT integer range 0 to 2</code> in the example above we would still have had a 2 bit counter. The code that could be represented on those 2 bits would still include “11”, even though it is outside of our defined range. Some simulation packages would flag a warning if this occurs, but many would not.

When using an integer as a port, the port will have as many physical lines as are needed to represent the integer using standard binary coding. Thus, in the example above, 'dout' will be represented by two physical port lines.

== Characters and Strings ==
Characters are enclosed in single quotation marks and are equivalent to their ASCII number. e.g. '0'=48

Strings are enclosed in double quotation marks. Example "Samuel" To include a double quotation mark inside quotation marks use it twice "Fred said""hello"".

Strings may be formed in other number bases. These bases are binary, octal and hex.

<syntaxhighlight lang="vhdl" line='line'>

entity Code_Example is
port (clock : In std_logic;
sel : In Std_logic;
output: Out std_logic_vector (7 downto 0));
end Code_Example;
architecture archy of Code_Example is
begin
process (clock)
begin
if clock='1' then
if sel='1' then
output<="01010101"; --binary string. Use a string to fill vector
else
output<=X"FF"; --Hexadecimal string
end if;
end if;
end process;
</syntaxhighlight>

== Enumerated Types ==
VHDL provides enumerated types for convenience. We have already come across one of these, std_logic, in which the logic states are represented as an enumerated type having nine different states which represent different electrical possibilities available on logic signals.

<syntaxhighlight lang="vhdl" line='line'>
entity Code_Example is
port (clock : In std_logic;
output: Out integer range 0 to 1);
end Code_Example;
architecture archy of Code_Example is
type colour is (green, blue);
--declare types in architecture declarative section
begin
process (clock)
variable status: colour;
--declare variables in process declarative section
begin
if clock='1' then
if status =green then
output<=1;
status:=blue;
else
output<=0;
status:=green;
end if;
end if;
end process;
end archy;
</syntaxhighlight>

== Arrays ==
These have the same meaning that you are used to. Arrays may have any number of dimensions and may be formed from any supported type, or previously defined type.

There are predefined types, such as strings and bit vectors.

The definition for the string type is given as follows:
<syntaxhighlight lang="vhdl">
type string is array (positive range <>) of character;
</syntaxhighlight>

The definition for bit vectors is as follows:
<syntaxhighlight lang="vhdl">
type bit_vector is array (natural range <>) of bit;
</syntaxhighlight>

The "<>" angle brackets are called a box. They are placeholders which indicate that the range will be filled in when the types are used.

Bit vectors are essentially an array of bits used for binary numbers. Here is an example of the usage of a bit
vector:
<syntaxhighlight lang="vhdl">
din: in bit_vector (2 downto 0);
</syntaxhighlight>
In this case the box will be filled in with the range 2 downto 0.

Arrays may be indexed to access individual elements. If we wish to access the first bit in din then we can say:
<code>if din(2)='1' then....</code>

Note that in the case of bit vectors when we specify the range we are specifying an array index. As a result, we are not specifying the numerical range, but rather the actual number of bits in the array.

If we use the “downto” keyword then the most significant bit will occupy the highest numbered array position. The opposite will apply if we use the “to” keyword.

We will not use bit vectors much, rather we will use 'standard logic vectors' which are more widely supported. The reason for this is that most of the libraries that are available for our VHDL system are defined in terms of standard logic vectors, rather than bit vectors. The behavior of std_logic_vectors is however very similar to the bit vector, except that, as noted above, std_logic has more possible states.

See above for examples of std_logic_vector usage.

</div>

= VHDL Operators =
= Attributes of Objects =
= More on Processes =
= Changing Execution Flow in VHDL =
= Dividing Big Jobs into Little Jobs =
= Packages =
= Conversion Functions =
= Megafunctions =

VHDL

2021-01-27T14:39:15Z

CRNKEE002: /* Variables */

VHDL

2021-01-27T14:39:00Z

CRNKEE002: /* Variables */

VHDL

2021-01-27T14:37:32Z

CRNKEE002: /* Variables */

RaspberryPi:ProgrammingInPython

2020-10-28T06:03:38Z

CRNKEE002: /* Using Threads */

[[Category:RaspberryPi]]
= Overview =
Most of the content in the guide comes from the documentation, available online [https://sourceforge.net/p/raspberry-gpio-python/wiki/Home/ here].

Python, while not as powerful as C or C++, is quickly becoming a common choice for embedded systems developers due to its ease of use and rapid development times. See [https://spectrum.ieee.org/at-work/innovation/the-2018-top-programming-languages this IEEE article]. For information on programming in C or C++, go to [[RaspberryPi:ProgrammingInC]].

This chapter serves as a short guide for programming in Python on the RPi. You will also find some templates for techniques such as debouncing, or making use of the Raspberry Pi’s multicore architecture by implementing threading.

= The RPI.GPIO Library =

The RPi.GPIO library is the common Python library used on the Raspberry Pi. Documentation for the library can be found here:<br />
https://sourceforge.net/p/raspberry-gpio-python/wiki/Home/

It is included in the environment variables by default, so to use it, you can simply just import it into your Python script:

<syntaxhighlight lang="python">import RPi.GPIO as GPIO</syntaxhighlight>
You need to specify which board mode you’re using. For more information on board modes, see Section [[RaspberryPi:Overview#GPIO_Pins]]. Board modes are specified as follows:

<syntaxhighlight lang="python">GPIO.setmode(GPIO.BOARD)
# or
GPIO.setmode(GPIO.BCM)</syntaxhighlight>
You also need to perform “cleanup” on GPIOs when your application exists. By performing cleanup and resetting all pins to their default modes, you can prevent possible damage to your Raspberry Pi. The cleanup function is called as follows:

<syntaxhighlight lang="python">GPIO.cleanup()</syntaxhighlight>
If your program is meant to run indefinitely, and only close upon an exception, you can wrap it in a try catch, as follows:

<syntaxhighlight lang="python">if __name__ == "__main__":
# Make sure the GPIO is stopped correctly
try:
while True:
main()
except KeyboardInterrupt:
print("Exiting gracefully")
GPIO.cleanup()
except e:
print("Some other error occurred: {}".format(e.message)})
GPIO.cleanup()</syntaxhighlight>

= Basic IO =

Read the documentation, available [https://sourceforge.net/p/raspberry-gpio-python/wiki/Outputs/ here].

== Digital Logic ==

Digital output on the Raspberry Pi is accomplished by writing values to channels. A channel is a pin, which is numbered in the way you’ve configured. Basic configuration of a pin for output is as follows:

<syntaxhighlight lang="python">GPIO.output(<channel>, <Logic>)</syntaxhighlight>
Your logic (high, 3.3V, or low, 0V), can be specified as follows:

<ul>
<li><p>For 3.3V (high) output:</p>
<syntaxhighlight lang="python">
GPIO.output(<channel>, GPIO.HIGH)
GPIO.output(<channel>, 1)
GPIO.output(<channel>, True)
</syntaxhighlight></li>

<li><p>For 0V (low) output:</p>
<syntaxhighlight lang="python">
GPIO.output(<channel>, GPIO.LOW)
GPIO.output(<channel>, 0)
GPIO.output(<channel>, False)
</syntaxhighlight></li></ul>

Channels can also be specified in lists, for example:

<syntaxhighlight lang="python">LEDs = (11,12)
GPIO.output(LEDs, GPIO.HIGH) # Will turn all channels HIGH
GPIO.output(LEDs, (GPIO.HIGH, GPIO.LOW)) # Will the first channel HIGH, and the second LOW</syntaxhighlight>

Note that you can also read the state of the pin/channel that is set as an output by using the <code>input()</code> function. For example, if you wanted to toggle pin 12, you could do something as follows:

<syntaxhighlight lang="python">GPIO.output(12, not GPIO.input(12))</syntaxhighlight>

== Analog ==

The Raspberry Pi does not have any analog input pins. You will need to use something like the [https://cdn-shop.adafruit.com/datasheets/MCP3008.pdf MCP3008] to read analog voltages.

== Inputs ==

=== Digital Read ===

To read the value of a digital pin, you can use the <code>input()</code> function:

<syntaxhighlight lang="python">if GPIO.input(12):
print("Pin 12 HIGH")
else:
print("Pin 12 LOW")</syntaxhighlight>
=== Pull Up/Pull Down Resistors ===

Using pull up and pull down resistors is essential when working with digital logic. Thankfully, the Raspberry Pi has internal pull up and pull down resistors. To make use of these, initialize the pin/channel as follows:

<syntaxhighlight lang="python">GPIO.setup(<channel>, GPIO.IN, pull_up_down=GPIO.PUD_UP)
# or
GPIO.setup(<channel>, GPIO.IN, pull_up_down=GPIO.PUD_DOWN)</syntaxhighlight>
=== Interrupts ===

Very often it is useful to set up an interrupt, for example to trigger an event when a button is pressed. Callback functions are executed on a different thread. If you have multiple callbacks, know that they will be executed sequentially as only one thread exists for interrupts. Interrupts can be implemented as follows:

<syntaxhighlight lang="python"># The bounce time is given in milliseconds.
# If your pin is set to use pull down resistors
# Connect a button between <channel> and 3.3V
GPIO.add_event_detect(<channel>, GPIO.RISING, callback=callback_method(), bouncetime=200)
# If your pin is set to use pull up resistors
# Connect a button between <channel> and GND
GPIO.add_event_detect(<channel>, GPIO.FALLING, callback=callback_method(), bouncetime=200) </syntaxhighlight>
=== Other functions ===

The RPi.GPIO Library offers other functions for interrupts the first is the <code>wait_for_edge()</code> function, which is designed to block execution until an edge is detected. You can detect edges of <code>GPIO.RISING</code>, <code>GPIO.FALLING</code>, or <code>GPIO.BOTH</code>. The timeout is given in milliseconds:

<syntaxhighlight lang="python"># wait for up to 5 seconds for a rising edge
edge = GPIO.wait_for_edge(<channel>, GPIO_RISING, timeout=5000)
if edge is None:
print('Timeout occurred')
else:
print('Edge detected on pin <CHANNEL>')</syntaxhighlight>

Another function is the <code>event_detected()</code> function. From the docs: “The event_detected() function is designed to be used in a loop with other things, but unlike polling it is not going to miss the change in state of an input while the CPU is busy working on other things. This could be useful when using something like Pygame or PyQt where there is a main loop listening and responding to GUI events in a timely basis.”

<syntaxhighlight lang="python">GPIO.add_event_detect(channel, GPIO.RISING) # add rising edge detection on a channel
if GPIO.event_detected(channel):
print('Button pressed')</syntaxhighlight>

= Communication Protocols =

The RPi.GPIO library has no native support for communication protocols. Very often, specific Python libraries are provided on a per-device use case. However, this can become tedious and cause your code to become bloated. See the sections below for relevant libraries for using I2C and SPI directly.

== I2C ==

Ensure you enable I2C in <code>raspi-config</code>.

To use I2C in Python, you can use the <code>smbus</code> library. To do this, we need to install and configure smbus. This is usually done by default, but instructions are included for posterity.

<pre>$ sudo apt-get install i2c-tools
$ sudo apt-get install python-smbus
$ sudo adduser <username> i2c
$ sudo reboot</pre>
Once you connect a device, you can run <code>$gpio i2cdetect</code> to determine if a device is detected on the I2C bus. In the example below, there is an electronic compass (GY-271) connected to the Pi.

[[File:I2cdetect.png|frame|none|alt=|An i2cdetect example]]

To initialize an I2C device, do the following:

<pre>import smbus
i2cdevice = smbus.SMBus(1) # 1 indicates /dev/i2c-1
address = 0x1e #whatever the device is for your i2c device</pre>
To read a byte from the I2C device:

<pre>result = i2cdevice.read_byte_data(address, <register>)</pre>
To write a byte to the I2C device:

<pre>i2cdevice.write_byte_data(address, <register>, <value>)</pre>
=== Methods Available ===

<code>smbus</code> has multiple methods. The documentation for these is quite minimal, but brief descriptions are available [http://wiki.erazor-zone.de/wiki:linux:python:smbus:doc here].

Note: If you're working with EEPROM (specifically 24C32), you may need to read the answer to the questions given [https://www.raspberrypi.org/forums/viewtopic.php?p=1401819&sid=582cace49dad59d93f4e0369047dd89d#p1401819 here].

== SPI ==

Ensure you enable SPI in <code>raspi-config</code>.

You can use SPI in Python by using the <code>spidev</code> library. Documentation is available [https://pypi.org/project/spidev/ here]. Basic usage is as follows:

<pre>import spidev

#Bus is 0 or 1, depending on which SPI bus you've connected to
bus = 0
#Device is the chip select pin. Set to 0 or 1, depending on the connections
device = 1

spi = spidev.SpiDev() #Enable SPI
spi.open(bus, device) #Open connection to a specific bus and device (CS pin)

# Set settings (SPI speed and mode)
spi.max_speed_hz = 500000
spi.mode = 0

to_send = [0x01, 0x02, 0x03] #define what to send
spi.xfer(to_send)

# Close the SPI connection
close()</pre>
=== Settings ===

The following settings are configurable in the <code>spidev</code> library, and can be set as follows:

<pre>spi = spidev.SpiDev() #Enable SPI
spi.<setting> = <value></pre>
List of settings:

* <code>bits_per_word</code>
* <code>cs_high</code>
* <code>loop</code><br />
Set the “SPI_LOOP” flag to enable loopback mode
* <code>no_cs</code><br />
Set the “SPI_NO_CS” flag to disable use of the chip select (although the driver may still own the CS pin)
* <code>lsbfirst</code>
* <code>max_speed_hz</code>
* <code>mode</code><br />
SPI mode as two bit pattern of clock polarity and phase [CPOL/CPHA], min: 0b00 = 0, max: 0b11 = 3
* <code>threewire</code><br />
SI/SO signals shared

=== Methods ===

The following methods are available in the <code>spidev</code> library

<ul>

<li><code>open(bus, device)</code><br>
Connects to the specified SPI device, opening <code>/dev/spidev<bus>.<device></code>
</li>
<li><code>readbytes(n)</code><br>
Read n bytes from SPI device.
</li>
<li><code>writebytes(list of values)</code><br />
Writes a list of values to SPI device.
</li>
<li> <code>writebytes2(list of values)</code><br />
Similar to ‘writebytes‘ but accepts arbitrary large lists. If list size exceeds buffer size (which is read from <code>/sys/module/spidev/parameters/bufsiz</code>), data will be split into smaller chunks and sent in multiple operations. Also, writebytes2 understands [https://docs.python.org/3/c-api/buffer.html buffer protocol] so it can accept numpy byte arrays for example without need to convert them with <code>tolist()</code> first. This offers much better performance where you need to transfer frames to SPI-connected displays for instance.
</li>
<li><code>xfer(list of values[, speed_hz, delay_usec, bits_per_word])</code><br />
Performs an SPI transaction. Chip-select should be released and reactivated between blocks. Delay specifies the delay in usec between blocks.
</li>
<li><code>xfer2(list of values[, speed_hz, delay_usec, bits_per_word])</code><br />
Performs an SPI transaction. Chip-select should be held active between blocks.
</li>
<li><code>xfer3(list of values[, speed_hz, delay_usec, bits_per_word])</code><br />
Similar to xfer2 but accepts arbitrary large lists. If list size exceeds buffer size (which is read from <code>/sys/module/spidev/parameters/bufsiz</code>), data will be split into smaller chunks and sent in multiple operations.
</li>
<li><code>close()</code><br />
Disconnects from the SPI device.
</li>
</ul>

= Using Threads =

[https://realpython.com/intro-to-python-threading/ This guide] serves as the basis for the text below. This manual does not teach everything there is to know about threading in Python, but will give you the basics to be able to utilize threads for simple tasks that may be of use to you in the practicals. It’s strongly recommended you read through that text if you have not yet been exposed to threading concepts.

This text does not cover issues and precautions when working with threads, such as mutex’s and locks, data races, producer/consumer concerns and the likes. However, these are knowledge areas of critical importance, and it is strongly suggested that the reader tries to make an effort to understand these concerns before writing threaded code.

== The Threading Library ==

The Python library <code>threading</code> library offers all the functionality one would expect. Import it in to your code in the standard way:

<pre>import threading</pre>
There are 4 basic things you need to do when creating a thread:

# Initialize it
# Start it
# Let is execute
# “Shut it down” by joining

== Basic Thread Usage ==

For example, if you want to create a separate thread to fetch a sensor value five times, you could do it as follows:

<syntaxhighlight lang="python" line='line'>import threading
import time
import RPi.GPIO as GPIO

def setup():
#Contains all code for initialisation of RPi.GPIO

def fetch_sensor_vals(sensor_pin):
for i in range(5):
GPIO.input(sensor_pin)
time.sleep(2)

if __name__ == "__main__":
setup()
# Create a thread to call the function and pass "12" in as sensor pin
x = threading.Thread(target=fetch_sensor_vals, args=(12,))
print("Starting thread")
x.start()
print("Waiting for the thread to finish")
x.join()
print("Reading finished")
</syntaxhighlight>

== Timed Thread Usage ==

Often in embedded systems we want a specific task to run every X time units. There is an option in the Python threading library. It works as follows:

<syntaxhighlight lang="python" line='line'>import threading
import datetime

def print_time_thread():
"""
This function prints the time to the screen every five seconds
"""
thread = threading.Timer(5.0, print_time_thread)
thread.daemon = True # Daemon threads exit when the program does
thread.start()
print(datetime.datetime.now())

if __name__ == "__main__":
print_time_thread() # call it once to start the thread

# Tell our program to run indefinitely
while True:
pass

</syntaxhighlight>

You will see that in this code example, we have also set the <code>daemon</code> flag of the thread to be be <code>True</code>. A daemon thread will shut down immediately when the program exits. In essence, the daemon thread will run indefinitely in the background until your application exits, and you do not need to worry about calling <code>join()</code>.<ref>It’s important to note that calling t.join() will wait for a thread to finish executing, even if it is a daemon.
</ref>

RaspberryPi:ProgrammingInPython

2020-09-22T12:00:42Z

CRNKEE002: /* Timed Thread Usage */

[[Category:RaspberryPi]]
= Overview =
Most of the content in the guide comes from the documentation, available online [https://sourceforge.net/p/raspberry-gpio-python/wiki/Home/ here].

Python, while not as powerful as C or C++, is quickly becoming a common choice for embedded systems developers due to its ease of use and rapid development times. See [https://spectrum.ieee.org/at-work/innovation/the-2018-top-programming-languages this IEEE article]. For information on programming in C or C++, go to [[RaspberryPi:ProgrammingInC]].

This chapter serves as a short guide for programming in Python on the RPi. You will also find some templates for techniques such as debouncing, or making use of the Raspberry Pi’s multicore architecture by implementing threading.

= The RPI.GPIO Library =

The RPi.GPIO library is the common Python library used on the Raspberry Pi. Documentation for the library can be found here:<br />
https://sourceforge.net/p/raspberry-gpio-python/wiki/Home/

It is included in the environment variables by default, so to use it, you can simply just import it into your Python script:

<syntaxhighlight lang="python">include RPi.GPIO as GPIO</syntaxhighlight>
You need to specify which board mode you’re using. For more information on board modes, see Section [[RaspberryPi:Overview#GPIO_Pins]]. Board modes are specified as follows:

<syntaxhighlight lang="python">GPIO.setmode(GPIO.BOARD)
# or
GPIO.setmode(GPIO.BCM)</syntaxhighlight>
You also need to perform “cleanup” on GPIOs when your application exists. By performing cleanup and resetting all pins to their default modes, you can prevent possible damage to your Raspberry Pi. The cleanup function is called as follows:

<syntaxhighlight lang="python">GPIO.cleanup()</syntaxhighlight>
If your program is meant to run indefinitely, and only close upon an exception, you can wrap it in a try catch, as follows:

<syntaxhighlight lang="python">if __name__ == "__main__":
# Make sure the GPIO is stopped correctly
try:
while True:
main()
except KeyboardInterrupt:
print("Exiting gracefully")
GPIO.cleanup()
except e:
print("Some other error occurred: {}".format(e.message)})
GPIO.cleanup()</syntaxhighlight>

= Basic IO =

Read the documentation, available [https://sourceforge.net/p/raspberry-gpio-python/wiki/Outputs/ here].

== Digital Logic ==

Digital output on the Raspberry Pi is accomplished by writing values to channels. A channel is a pin, which is numbered in the way you’ve configured. Basic configuration of a pin for output is as follows:

<syntaxhighlight lang="python">GPIO.output(<channel>, <Logic>)</syntaxhighlight>
Your logic (high, 3.3V, or low, 0V), can be specified as follows:

<ul>
<li><p>For 3.3V (high) output:</p>
<syntaxhighlight lang="python">
GPIO.output(<channel>, GPIO.HIGH)
GPIO.output(<channel>, 1)
GPIO.output(<channel>, True)
</syntaxhighlight></li>

<li><p>For 0V (low) output:</p>
<syntaxhighlight lang="python">
GPIO.output(<channel>, GPIO.LOW)
GPIO.output(<channel>, 0)
GPIO.output(<channel>, False)
</syntaxhighlight></li></ul>

Channels can also be specified in lists, for example:

<syntaxhighlight lang="python">LEDs = (11,12)
GPIO.output(LEDs, GPIO.HIGH) # Will turn all channels HIGH
GPIO.output(LEDs, (GPIO.HIGH, GPIO.LOW)) # Will the first channel HIGH, and the second LOW</syntaxhighlight>

Note that you can also read the state of the pin/channel that is set as an output by using the <code>input()</code> function. For example, if you wanted to toggle pin 12, you could do something as follows:

<syntaxhighlight lang="python">GPIO.output(12, not GPIO.input(12))</syntaxhighlight>

== Analog ==

The Raspberry Pi does not have any analog input pins. You will need to use something like the [https://cdn-shop.adafruit.com/datasheets/MCP3008.pdf MCP3008] to read analog voltages.

== Inputs ==

=== Digital Read ===

To read the value of a digital pin, you can use the <code>input()</code> function:

<syntaxhighlight lang="python">if GPIO.input(12):
print("Pin 12 HIGH")
else:
print("Pin 12 LOW")</syntaxhighlight>
=== Pull Up/Pull Down Resistors ===

Using pull up and pull down resistors is essential when working with digital logic. Thankfully, the Raspberry Pi has internal pull up and pull down resistors. To make use of these, initialize the pin/channel as follows:

<syntaxhighlight lang="python">GPIO.setup(<channel>, GPIO.IN, pull_up_down=GPIO.PUD_UP)
# or
GPIO.setup(<channel>, GPIO.IN, pull_up_down=GPIO.PUD_DOWN)</syntaxhighlight>
=== Interrupts ===

Very often it is useful to set up an interrupt, for example to trigger an event when a button is pressed. Callback functions are executed on a different thread. If you have multiple callbacks, know that they will be executed sequentially as only one thread exists for interrupts. Interrupts can be implemented as follows:

<syntaxhighlight lang="python"># The bounce time is given in milliseconds.
# If your pin is set to use pull down resistors
# Connect a button between <channel> and 3.3V
GPIO.add_event_detect(<channel>, GPIO.RISING, callback=callback_method(), bouncetime=200)
# If your pin is set to use pull up resistors
# Connect a button between <channel> and GND
GPIO.add_event_detect(<channel>, GPIO.FALLING, callback=callback_method(), bouncetime=200) </syntaxhighlight>
=== Other functions ===

The RPi.GPIO Library offers other functions for interrupts the first is the <code>wait_for_edge()</code> function, which is designed to block execution until an edge is detected. You can detect edges of <code>GPIO.RISING</code>, <code>GPIO.FALLING</code>, or <code>GPIO.BOTH</code>. The timeout is given in milliseconds:

<syntaxhighlight lang="python"># wait for up to 5 seconds for a rising edge
edge = GPIO.wait_for_edge(<channel>, GPIO_RISING, timeout=5000)
if edge is None:
print('Timeout occurred')
else:
print('Edge detected on pin <CHANNEL>')</syntaxhighlight>

Another function is the <code>event_detected()</code> function. From the docs: “The event_detected() function is designed to be used in a loop with other things, but unlike polling it is not going to miss the change in state of an input while the CPU is busy working on other things. This could be useful when using something like Pygame or PyQt where there is a main loop listening and responding to GUI events in a timely basis.”

<syntaxhighlight lang="python">GPIO.add_event_detect(channel, GPIO.RISING) # add rising edge detection on a channel
if GPIO.event_detected(channel):
print('Button pressed')</syntaxhighlight>

= Communication Protocols =

The RPi.GPIO library has no native support for communication protocols. Very often, specific Python libraries are provided on a per-device use case. However, this can become tedious and cause your code to become bloated. See the sections below for relevant libraries for using I2C and SPI directly.

== I2C ==

Ensure you enable I2C in <code>raspi-config</code>.

To use I2C in Python, you can use the <code>smbus</code> library. To do this, we need to install and configure smbus. This is usually done by default, but instructions are included for posterity.

<pre>$ sudo apt-get install i2c-tools
$ sudo apt-get install python-smbus
$ sudo adduser <username> i2c
$ sudo reboot</pre>
Once you connect a device, you can run <code>$gpio i2cdetect</code> to determine if a device is detected on the I2C bus. In the example below, there is an electronic compass (GY-271) connected to the Pi.

[[File:I2cdetect.png|frame|none|alt=|An i2cdetect example]]

To initialize an I2C device, do the following:

<pre>import smbus
i2cdevice = smbus.SMBus(1) # 1 indicates /dev/i2c-1
address = 0x1e #whatever the device is for your i2c device</pre>
To read a byte from the I2C device:

<pre>result = i2cdevice.read_byte_data(address, <register>)</pre>
To write a byte to the I2C device:

<pre>i2cdevice.write_byte_data(address, <register>, <value>)</pre>
=== Methods Available ===

<code>smbus</code> has multiple methods. The documentation for these is quite minimal, but brief descriptions are available [http://wiki.erazor-zone.de/wiki:linux:python:smbus:doc here].

Note: If you're working with EEPROM (specifically 24C32), you may need to read the answer to the questions given [https://www.raspberrypi.org/forums/viewtopic.php?p=1401819&sid=582cace49dad59d93f4e0369047dd89d#p1401819 here].

== SPI ==

Ensure you enable SPI in <code>raspi-config</code>.

You can use SPI in Python by using the <code>spidev</code> library. Documentation is available [https://pypi.org/project/spidev/ here]. Basic usage is as follows:

<pre>import spidev

#Bus is 0 or 1, depending on which SPI bus you've connected to
bus = 0
#Device is the chip select pin. Set to 0 or 1, depending on the connections
device = 1

spi = spidev.SpiDev() #Enable SPI
spi.open(bus, device) #Open connection to a specific bus and device (CS pin)

# Set settings (SPI speed and mode)
spi.max_speed_hz = 500000
spi.mode = 0

to_send = [0x01, 0x02, 0x03] #define what to send
spi.xfer(to_send)

# Close the SPI connection
close()</pre>
=== Settings ===

The following settings are configurable in the <code>spidev</code> library, and can be set as follows:

<pre>spi = spidev.SpiDev() #Enable SPI
spi.<setting> = <value></pre>
List of settings:

* <code>bits_per_word</code>
* <code>cs_high</code>
* <code>loop</code><br />
Set the “SPI_LOOP” flag to enable loopback mode
* <code>no_cs</code><br />
Set the “SPI_NO_CS” flag to disable use of the chip select (although the driver may still own the CS pin)
* <code>lsbfirst</code>
* <code>max_speed_hz</code>
* <code>mode</code><br />
SPI mode as two bit pattern of clock polarity and phase [CPOL/CPHA], min: 0b00 = 0, max: 0b11 = 3
* <code>threewire</code><br />
SI/SO signals shared

=== Methods ===

The following methods are available in the <code>spidev</code> library

<ul>

<li><code>open(bus, device)</code><br>
Connects to the specified SPI device, opening <code>/dev/spidev<bus>.<device></code>
</li>
<li><code>readbytes(n)</code><br>
Read n bytes from SPI device.
</li>
<li><code>writebytes(list of values)</code><br />
Writes a list of values to SPI device.
</li>
<li> <code>writebytes2(list of values)</code><br />
Similar to ‘writebytes‘ but accepts arbitrary large lists. If list size exceeds buffer size (which is read from <code>/sys/module/spidev/parameters/bufsiz</code>), data will be split into smaller chunks and sent in multiple operations. Also, writebytes2 understands [https://docs.python.org/3/c-api/buffer.html buffer protocol] so it can accept numpy byte arrays for example without need to convert them with <code>tolist()</code> first. This offers much better performance where you need to transfer frames to SPI-connected displays for instance.
</li>
<li><code>xfer(list of values[, speed_hz, delay_usec, bits_per_word])</code><br />
Performs an SPI transaction. Chip-select should be released and reactivated between blocks. Delay specifies the delay in usec between blocks.
</li>
<li><code>xfer2(list of values[, speed_hz, delay_usec, bits_per_word])</code><br />
Performs an SPI transaction. Chip-select should be held active between blocks.
</li>
<li><code>xfer3(list of values[, speed_hz, delay_usec, bits_per_word])</code><br />
Similar to xfer2 but accepts arbitrary large lists. If list size exceeds buffer size (which is read from <code>/sys/module/spidev/parameters/bufsiz</code>), data will be split into smaller chunks and sent in multiple operations.
</li>
<li><code>close()</code><br />
Disconnects from the SPI device.
</li>
</ul>

= Using Threads =

[https://realpython.com/intro-to-python-threading/ This guide] serves as the basis for the text below. This manual does not teach everything there is to know about threading in Python, but will give you the basics to be able to utilize threads for simple tasks that may be of use to you in the practicals. It’s strongly recommended you read through that text if you have not yet been exposed to threading concepts.

This text does not cover issues and precautions when working with threads, such as mutex’s and locks, data races, producer/consumer concerns and the likes. However, these are knowledge areas of critical importance, and it is strongly suggested that the reader tries to make an effort to understand these concerns before writing threaded code.

== The Threading Library ==

The Python library <code>threading</code> library offers all the functionality one would expect. Import it in to your code in the standard way:

<pre>import threading</pre>
There are 4 basic things you need to do when creating a thread:

# Initialize it
# Start it
# Let is execute
# “Shut it down” by joining

== Basic Thread Usage ==

For example, if you want to create a separate thread to fetch a sensor value five times, you could do it as follows:

<pre>import threading
import time
import RPi.GPIO as GPIO

def setup():
#Contains all code for initialisation of RPi.GPIO

def fetch_sensor_vals(sensor_pin):
for i in range(5):
GPIO.input(sensor_pin)
time.sleep(2)

if __name__ == "__main__":
setup()
# Create a thread to call the function and pass "12" in as sensor pin
x = threading.Thread(target=fetch_sensor_vals, args=(12,))
print("Starting thread")
x.start()
print("Waiting for the thread to finish")
x.join()
print("Reading finished")</pre>
== Timed Thread Usage ==

Often in embedded systems we want a specific task to run every X time units. There is an option in the Python threading library. It works as follows:

<syntaxhighlight lang="python" line='line'>import threading
import datetime

def print_time_thread():
"""
This function prints the time to the screen every five seconds
"""
thread = threading.Timer(5.0, print_time_thread)
thread.daemon = True # Daemon threads exit when the program does
thread.start()
print(datetime.datetime.now())

if __name__ == "__main__":
print_time_thread() # call it once to start the thread

# Tell our program to run indefinitely
while True:
pass

</syntaxhighlight>

You will see that in this code example, we have also set the <code>daemon</code> flag of the thread to be be <code>True</code>. A daemon thread will shut down immediately when the program exits. In essence, the daemon thread will run indefinitely in the background until your application exits, and you do not need to worry about calling <code>join()</code>.<ref>It’s important to note that calling t.join() will wait for a thread to finish executing, even if it is a daemon.
</ref>

RaspberryPi:DebuggingConnectivity

2020-09-15T07:51:41Z

CRNKEE002: /* Ubuntu */

[[Category:RaspberryPi]]
= Debugging Connections =

This section is a work in progress. As more common issues are reported by students, this section will be expanded. It's important to note that most connectivity problems come down to an incorrectly configured file, where you may have missed a space, or misspelled something.

= Note for Windows Users =

If you are having trouble accessing the internet from your Pi using the Ethernet Passthrough technique, it’s likely the Windows bridge needs a reset. Change the IPv4 address of your Ethernet port to “Obtain an IP address automatically”, then on your WiFi connection, disable sharing, click okay, and then re-enable sharing. Go back to the IP configuration of your Ethernet post, and double check the IP to see if it’s been assigned 192.168.137.1. If not, you will need to change it using the “Advanced settings” button.

= Ping =
''Ping'' sends a packet to a particular host (in this case the Pi), and measures the time taken for a response from that host.

To use the ping command, open a command prompt window or terminal and type the following:

<pre>$ ping 192.168.137.15</pre>
If that host is unreachable (the Pi hasn’t booted yet or is incorrectly configured), a message will show that the host is unreachable. If everything was correctly configured, you should get

<pre>Reply from 192.168.137.15: bytes=32 time<1ns TTL=64</pre>
This means your Pi and computer are both correctly configured.

'''NB:''' Don’t be surprised if you can’t ping a Windows machine from your Pi. Windows blocks the specific type of packet required for a ping in the firewall.

= WiFi =

See if you can see wireless networks.

<pre>$ iwlist wlan0 scan</pre>
If you cannot connect via WiFi, enter into a shell on the Pi and run:

<pre>$ journalctl -u wpa_supplicant | grep wlan0
$ journalctl -u dhcpcd.service | grep wlan0</pre>
This will output the log files and notify you of any incorrect configurations in wpa_supplicant.

The following command will force the interface to be up (if it can be):

<pre>sudo ifconfig wlan0 up</pre>
If all else fails, reboot and try again. Some services can be restarted without restarting the Pi, for example:

<pre>sudo systemctl restart dhcpcd</pre>
Test wpa_supplicant config by killing the process, and running it in debug mode:

<pre>sudo killall wpa_supplicant
sudo /sbin/wpa_supplicant -d -c/etc/wpa_supplicant/wpa_supplicant.conf -Dnl80211,wext -iwlan0</pre>

= "Failure resolving URLs" or "unknown host" =

If you try to ping a website from the Pi and it fails, but pinging a IP such as 8.8.8.8 works as expected, it is likely an issue with DNS configuration. Open the resolv.conf file:

<pre>$ sudo nano /etc/resolv.conf</pre>
And edit it to read the following:

<pre>nameserver 8.8.8.8
nameserver 192.168.137.1</pre>
8.8.8.8 is the IP of Google’s DNS server. A DNS (Domain Name Service) server is responsible for converting human-readable addressed (for example google.co.za) to something the network architecture can understand (172.217.170.67, in this example).

If you still get this error, try running the following command:

<pre>$ sudo route add default gw 192.168.137.1</pre>
Where the IP supplied is the IP of the computer or router you are connected to.

= SSH'ing Into the Pi 0/0W =
This section assumes you've correctly modified the SD card contents using the correct editor, and are using the correct USB port on the Pi.
== Windows ==
<ol>
<li> Open up device manager by pressing the Windows key and X and selecting "Device Manager" from the drop down</li>
<li>If you have no other USB to Ethernet Gadgets plugged in, and you see this, it means your Pi is connected correctly and you need to double check you've installed Bonjour and are connecting to the correct hostname.
[[File:RNDISWithCorrectDrivers.png|none|left]]
</li>
<li> If the device manager is constantly "flashing" after giving the Pi enough time to boot, it means there isn't enough power delivery to the Pi. This is only really a problem on older systems. To resolve this issue, add an additional connection from the "power" USB port to something that can provide additional current, like a cellphone charger, or even just another USB port.</li>
<li> If under "Universal Serial Bus controllers" you see something like "Unknown USB Device (Device Descriptor Failed)", it means the driver is not installed. <br>
[[File:RNDISDriverNotInstalled.png|none|left]]
To install the driver, you need to do the following:
<ol>
<li>Right click on the "Unknown USB Device" and uninstall the driver.</li>
<li>Unplug the Pi from your computer</li>
<li>Download the RNDIS drivers here: [[Media:Mod-duo-rndis.zip|Windows 10 RNDIS Drivers]] </li>
<li>Extract the contents</li>
<li>Right click on "RNDIS.inf" and select "install"</li>
<li> Plug in the Raspberry Pi again, it should be picked up as a USB Ethernet Device under "Network Adapters"</li>
</ol>

</ol>

== Ubuntu ==
Some Ubuntu systems are unable to perform the IP lookup based on the hostname.
Follow the instructions [https://askubuntu.com/questions/992388/ubuntu-avahi-daemon-cannot-find-raspberrypi-local/1010785#1010785 here] to connect.

The instructions above were converted into a script. Before running the script, you need to set IPv6 of the Pi's ethernet connection to link-local only, and get the name of the interface using <code>ifconfig</code>.

The script is as follows:
<pre>
set -e
echo "Ensure you've set IPv6 to link local only"
echo "Ensure you know the interface on which the Pi is located"
echo "Use the ifconfig command to get the interface. Often 'usb0'"
echo "Trying to resolve raspberrypi.local"
resolved=`avahi-resolve-host-name raspberrypi.local`
piIP=`echo $resolved | cut -c 19-128`
echo "Please enter in the USB interface"
read interface
echo "Attempting to SSH into pi@$piIP%$interface"
ssh pi@$piIP%$interface
</pre>

Once you've connected, it's suggest you connect to a wifi network to be able to SSH in using "pi@raspberrypi.local", or set a static IP on the USB port and use the same subnet on the network created on the PC when you plug in the Pi.

RaspberryPi:DebuggingConnectivity

2020-09-14T10:01:06Z

CRNKEE002: /* Ubuntu */

[[Category:RaspberryPi]]
= Debugging Connections =

This section is a work in progress. As more common issues are reported by students, this section will be expanded. It's important to note that most connectivity problems come down to an incorrectly configured file, where you may have missed a space, or misspelled something.

= Note for Windows Users =

If you are having trouble accessing the internet from your Pi using the Ethernet Passthrough technique, it’s likely the Windows bridge needs a reset. Change the IPv4 address of your Ethernet port to “Obtain an IP address automatically”, then on your WiFi connection, disable sharing, click okay, and then re-enable sharing. Go back to the IP configuration of your Ethernet post, and double check the IP to see if it’s been assigned 192.168.137.1. If not, you will need to change it using the “Advanced settings” button.

= Ping =
''Ping'' sends a packet to a particular host (in this case the Pi), and measures the time taken for a response from that host.

To use the ping command, open a command prompt window or terminal and type the following:

<pre>$ ping 192.168.137.15</pre>
If that host is unreachable (the Pi hasn’t booted yet or is incorrectly configured), a message will show that the host is unreachable. If everything was correctly configured, you should get

<pre>Reply from 192.168.137.15: bytes=32 time<1ns TTL=64</pre>
This means your Pi and computer are both correctly configured.

'''NB:''' Don’t be surprised if you can’t ping a Windows machine from your Pi. Windows blocks the specific type of packet required for a ping in the firewall.

= WiFi =

See if you can see wireless networks.

<pre>$ iwlist wlan0 scan</pre>
If you cannot connect via WiFi, enter into a shell on the Pi and run:

<pre>$ journalctl -u wpa_supplicant | grep wlan0
$ journalctl -u dhcpcd.service | grep wlan0</pre>
This will output the log files and notify you of any incorrect configurations in wpa_supplicant.

The following command will force the interface to be up (if it can be):

<pre>sudo ifconfig wlan0 up</pre>
If all else fails, reboot and try again. Some services can be restarted without restarting the Pi, for example:

<pre>sudo systemctl restart dhcpcd</pre>
Test wpa_supplicant config by killing the process, and running it in debug mode:

<pre>sudo killall wpa_supplicant
sudo /sbin/wpa_supplicant -d -c/etc/wpa_supplicant/wpa_supplicant.conf -Dnl80211,wext -iwlan0</pre>

= "Failure resolving URLs" or "unknown host" =

If you try to ping a website from the Pi and it fails, but pinging a IP such as 8.8.8.8 works as expected, it is likely an issue with DNS configuration. Open the resolv.conf file:

<pre>$ sudo nano /etc/resolv.conf</pre>
And edit it to read the following:

<pre>nameserver 8.8.8.8
nameserver 192.168.137.1</pre>
8.8.8.8 is the IP of Google’s DNS server. A DNS (Domain Name Service) server is responsible for converting human-readable addressed (for example google.co.za) to something the network architecture can understand (172.217.170.67, in this example).

If you still get this error, try running the following command:

<pre>$ sudo route add default gw 192.168.137.1</pre>
Where the IP supplied is the IP of the computer or router you are connected to.

= SSH'ing Into the Pi 0/0W =
This section assumes you've correctly modified the SD card contents using the correct editor, and are using the correct USB port on the Pi.
== Windows ==
<ol>
<li> Open up device manager by pressing the Windows key and X and selecting "Device Manager" from the drop down</li>
<li>If you have no other USB to Ethernet Gadgets plugged in, and you see this, it means your Pi is connected correctly and you need to double check you've installed Bonjour and are connecting to the correct hostname.
[[File:RNDISWithCorrectDrivers.png|none|left]]
</li>
<li> If the device manager is constantly "flashing" after giving the Pi enough time to boot, it means there isn't enough power delivery to the Pi. This is only really a problem on older systems. To resolve this issue, add an additional connection from the "power" USB port to something that can provide additional current, like a cellphone charger, or even just another USB port.</li>
<li> If under "Universal Serial Bus controllers" you see something like "Unknown USB Device (Device Descriptor Failed)", it means the driver is not installed. <br>
[[File:RNDISDriverNotInstalled.png|none|left]]
To install the driver, you need to do the following:
<ol>
<li>Right click on the "Unknown USB Device" and uninstall the driver.</li>
<li>Unplug the Pi from your computer</li>
<li>Download the RNDIS drivers here: [[Media:Mod-duo-rndis.zip|Windows 10 RNDIS Drivers]] </li>
<li>Extract the contents</li>
<li>Right click on "RNDIS.inf" and select "install"</li>
<li> Plug in the Raspberry Pi again, it should be picked up as a USB Ethernet Device under "Network Adapters"</li>
</ol>

</ol>

== Ubuntu ==
Some Ubuntu systems are unable to perform the IP lookup based on the hostname.
Follow the instructions [https://askubuntu.com/questions/992388/ubuntu-avahi-daemon-cannot-find-raspberrypi-local/1010785#1010785 here] to connect.

Once you've connected, it's suggest you connect to a wifi network to be able to SSH in using "pi@raspberrypi.local", or set a static IP on the USB port and use the same subnet on the network created on the PC when you plug in the Pi.

RaspberryPi:DebuggingConnectivity

2020-09-14T10:00:51Z

CRNKEE002: /* Ubuntu */

[[Category:RaspberryPi]]
= Debugging Connections =

This section is a work in progress. As more common issues are reported by students, this section will be expanded. It's important to note that most connectivity problems come down to an incorrectly configured file, where you may have missed a space, or misspelled something.

= Note for Windows Users =

If you are having trouble accessing the internet from your Pi using the Ethernet Passthrough technique, it’s likely the Windows bridge needs a reset. Change the IPv4 address of your Ethernet port to “Obtain an IP address automatically”, then on your WiFi connection, disable sharing, click okay, and then re-enable sharing. Go back to the IP configuration of your Ethernet post, and double check the IP to see if it’s been assigned 192.168.137.1. If not, you will need to change it using the “Advanced settings” button.

= Ping =
''Ping'' sends a packet to a particular host (in this case the Pi), and measures the time taken for a response from that host.

To use the ping command, open a command prompt window or terminal and type the following:

<pre>$ ping 192.168.137.15</pre>
If that host is unreachable (the Pi hasn’t booted yet or is incorrectly configured), a message will show that the host is unreachable. If everything was correctly configured, you should get

<pre>Reply from 192.168.137.15: bytes=32 time<1ns TTL=64</pre>
This means your Pi and computer are both correctly configured.

'''NB:''' Don’t be surprised if you can’t ping a Windows machine from your Pi. Windows blocks the specific type of packet required for a ping in the firewall.

= WiFi =

See if you can see wireless networks.

<pre>$ iwlist wlan0 scan</pre>
If you cannot connect via WiFi, enter into a shell on the Pi and run:

<pre>$ journalctl -u wpa_supplicant | grep wlan0
$ journalctl -u dhcpcd.service | grep wlan0</pre>
This will output the log files and notify you of any incorrect configurations in wpa_supplicant.

The following command will force the interface to be up (if it can be):

<pre>sudo ifconfig wlan0 up</pre>
If all else fails, reboot and try again. Some services can be restarted without restarting the Pi, for example:

<pre>sudo systemctl restart dhcpcd</pre>
Test wpa_supplicant config by killing the process, and running it in debug mode:

<pre>sudo killall wpa_supplicant
sudo /sbin/wpa_supplicant -d -c/etc/wpa_supplicant/wpa_supplicant.conf -Dnl80211,wext -iwlan0</pre>

= "Failure resolving URLs" or "unknown host" =

If you try to ping a website from the Pi and it fails, but pinging a IP such as 8.8.8.8 works as expected, it is likely an issue with DNS configuration. Open the resolv.conf file:

<pre>$ sudo nano /etc/resolv.conf</pre>
And edit it to read the following:

<pre>nameserver 8.8.8.8
nameserver 192.168.137.1</pre>
8.8.8.8 is the IP of Google’s DNS server. A DNS (Domain Name Service) server is responsible for converting human-readable addressed (for example google.co.za) to something the network architecture can understand (172.217.170.67, in this example).

If you still get this error, try running the following command:

<pre>$ sudo route add default gw 192.168.137.1</pre>
Where the IP supplied is the IP of the computer or router you are connected to.

= SSH'ing Into the Pi 0/0W =
This section assumes you've correctly modified the SD card contents using the correct editor, and are using the correct USB port on the Pi.
== Windows ==
<ol>
<li> Open up device manager by pressing the Windows key and X and selecting "Device Manager" from the drop down</li>
<li>If you have no other USB to Ethernet Gadgets plugged in, and you see this, it means your Pi is connected correctly and you need to double check you've installed Bonjour and are connecting to the correct hostname.
[[File:RNDISWithCorrectDrivers.png|none|left]]
</li>
<li> If the device manager is constantly "flashing" after giving the Pi enough time to boot, it means there isn't enough power delivery to the Pi. This is only really a problem on older systems. To resolve this issue, add an additional connection from the "power" USB port to something that can provide additional current, like a cellphone charger, or even just another USB port.</li>
<li> If under "Universal Serial Bus controllers" you see something like "Unknown USB Device (Device Descriptor Failed)", it means the driver is not installed. <br>
[[File:RNDISDriverNotInstalled.png|none|left]]
To install the driver, you need to do the following:
<ol>
<li>Right click on the "Unknown USB Device" and uninstall the driver.</li>
<li>Unplug the Pi from your computer</li>
<li>Download the RNDIS drivers here: [[Media:Mod-duo-rndis.zip|Windows 10 RNDIS Drivers]] </li>
<li>Extract the contents</li>
<li>Right click on "RNDIS.inf" and select "install"</li>
<li> Plug in the Raspberry Pi again, it should be picked up as a USB Ethernet Device under "Network Adapters"</li>
</ol>

</ol>

== Ubuntu ==
Some Ubuntu systems are unable to perform the IP lookup based on the hostname.
Follow the instructions [https://askubuntu.com/questions/992388/ubuntu-avahi-daemon-cannot-find-raspberrypi-local/1010785#1010785 here] to connect.

Once you've connected, it's suggest you connect to a wifi network to be able to SSH in using "raspberrypi.local", or set a static IP on the USB port and use the same subnet on the network created on the PC when you plug in the Pi.

RaspberryPi:ProgrammingInPython

2020-09-11T09:34:06Z

CRNKEE002: /* I2C */

[[Category:RaspberryPi]]
= Overview =
Most of the content in the guide comes from the documentation, available online [https://sourceforge.net/p/raspberry-gpio-python/wiki/Home/ here].

Python, while not as powerful as C or C++, is quickly becoming a common choice for embedded systems developers due to its ease of use and rapid development times. See [https://spectrum.ieee.org/at-work/innovation/the-2018-top-programming-languages this IEEE article]. For information on programming in C or C++, go to [[RaspberryPi:ProgrammingInC]].

This chapter serves as a short guide for programming in Python on the RPi. You will also find some templates for techniques such as debouncing, or making use of the Raspberry Pi’s multicore architecture by implementing threading.

= The RPI.GPIO Library =

The RPi.GPIO library is the common Python library used on the Raspberry Pi. Documentation for the library can be found here:<br />
https://sourceforge.net/p/raspberry-gpio-python/wiki/Home/

It is included in the environment variables by default, so to use it, you can simply just import it into your Python script:

<syntaxhighlight lang="python">include RPi.GPIO as GPIO</syntaxhighlight>
You need to specify which board mode you’re using. For more information on board modes, see Section [[RaspberryPi:Overview#GPIO_Pins]]. Board modes are specified as follows:

<syntaxhighlight lang="python">GPIO.setmode(GPIO.BOARD)
# or
GPIO.setmode(GPIO.BCM)</syntaxhighlight>
You also need to perform “cleanup” on GPIOs when your application exists. By performing cleanup and resetting all pins to their default modes, you can prevent possible damage to your Raspberry Pi. The cleanup function is called as follows:

<syntaxhighlight lang="python">GPIO.cleanup()</syntaxhighlight>
If your program is meant to run indefinitely, and only close upon an exception, you can wrap it in a try catch, as follows:

<syntaxhighlight lang="python">if __name__ == "__main__":
# Make sure the GPIO is stopped correctly
try:
while True:
main()
except KeyboardInterrupt:
print("Exiting gracefully")
GPIO.cleanup()
except e:
print("Some other error occurred: {}".format(e.message)})
GPIO.cleanup()</syntaxhighlight>

= Basic IO =

Read the documentation, available [https://sourceforge.net/p/raspberry-gpio-python/wiki/Outputs/ here].

== Digital Logic ==

Digital output on the Raspberry Pi is accomplished by writing values to channels. A channel is a pin, which is numbered in the way you’ve configured. Basic configuration of a pin for output is as follows:

<syntaxhighlight lang="python">GPIO.output(<channel>, <Logic>)</syntaxhighlight>
Your logic (high, 3.3V, or low, 0V), can be specified as follows:

<ul>
<li><p>For 3.3V (high) output:</p>
<syntaxhighlight lang="python">
GPIO.output(<channel>, GPIO.HIGH)
GPIO.output(<channel>, 1)
GPIO.output(<channel>, True)
</syntaxhighlight></li>

<li><p>For 0V (low) output:</p>
<syntaxhighlight lang="python">
GPIO.output(<channel>, GPIO.LOW)
GPIO.output(<channel>, 0)
GPIO.output(<channel>, False)
</syntaxhighlight></li></ul>

Channels can also be specified in lists, for example:

<syntaxhighlight lang="python">LEDs = (11,12)
GPIO.output(LEDs, GPIO.HIGH) # Will turn all channels HIGH
GPIO.output(LEDs, (GPIO.HIGH, GPIO.LOW)) # Will the first channel HIGH, and the second LOW</syntaxhighlight>

Note that you can also read the state of the pin/channel that is set as an output by using the <code>input()</code> function. For example, if you wanted to toggle pin 12, you could do something as follows:

<syntaxhighlight lang="python">GPIO.output(12, not GPIO.input(12))</syntaxhighlight>

== Analog ==

The Raspberry Pi does not have any analog input pins. You will need to use something like the [https://cdn-shop.adafruit.com/datasheets/MCP3008.pdf MCP3008] to read analog voltages.

== Inputs ==

=== Digital Read ===

To read the value of a digital pin, you can use the <code>input()</code> function:

<syntaxhighlight lang="python">if GPIO.input(12):
print("Pin 12 HIGH")
else:
print("Pin 12 LOW")</syntaxhighlight>
=== Pull Up/Pull Down Resistors ===

Using pull up and pull down resistors is essential when working with digital logic. Thankfully, the Raspberry Pi has internal pull up and pull down resistors. To make use of these, initialize the pin/channel as follows:

<syntaxhighlight lang="python">GPIO.setup(<channel>, GPIO.IN, pull_up_down=GPIO.PUD_UP)
# or
GPIO.setup(<channel>, GPIO.IN, pull_up_down=GPIO.PUD_DOWN)</syntaxhighlight>
=== Interrupts ===

Very often it is useful to set up an interrupt, for example to trigger an event when a button is pressed. Callback functions are executed on a different thread. If you have multiple callbacks, know that they will be executed sequentially as only one thread exists for interrupts. Interrupts can be implemented as follows:

<syntaxhighlight lang="python"># The bounce time is given in milliseconds.
# If your pin is set to use pull down resistors
# Connect a button between <channel> and 3.3V
GPIO.add_event_detect(<channel>, GPIO.RISING, callback=callback_method(), bouncetime=200)
# If your pin is set to use pull up resistors
# Connect a button between <channel> and GND
GPIO.add_event_detect(<channel>, GPIO.FALLING, callback=callback_method(), bouncetime=200) </syntaxhighlight>
=== Other functions ===

The RPi.GPIO Library offers other functions for interrupts the first is the <code>wait_for_edge()</code> function, which is designed to block execution until an edge is detected. You can detect edges of <code>GPIO.RISING</code>, <code>GPIO.FALLING</code>, or <code>GPIO.BOTH</code>. The timeout is given in milliseconds:

<syntaxhighlight lang="python"># wait for up to 5 seconds for a rising edge
edge = GPIO.wait_for_edge(<channel>, GPIO_RISING, timeout=5000)
if edge is None:
print('Timeout occurred')
else:
print('Edge detected on pin <CHANNEL>')</syntaxhighlight>

Another function is the <code>event_detected()</code> function. From the docs: “The event_detected() function is designed to be used in a loop with other things, but unlike polling it is not going to miss the change in state of an input while the CPU is busy working on other things. This could be useful when using something like Pygame or PyQt where there is a main loop listening and responding to GUI events in a timely basis.”

<syntaxhighlight lang="python">GPIO.add_event_detect(channel, GPIO.RISING) # add rising edge detection on a channel
if GPIO.event_detected(channel):
print('Button pressed')</syntaxhighlight>

= Communication Protocols =

The RPi.GPIO library has no native support for communication protocols. Very often, specific Python libraries are provided on a per-device use case. However, this can become tedious and cause your code to become bloated. See the sections below for relevant libraries for using I2C and SPI directly.

== I2C ==

Ensure you enable I2C in <code>raspi-config</code>.

To use I2C in Python, you can use the <code>smbus</code> library. To do this, we need to install and configure smbus. This is usually done by default, but instructions are included for posterity.

<pre>$ sudo apt-get install i2c-tools
$ sudo apt-get install python-smbus
$ sudo adduser <username> i2c
$ sudo reboot</pre>
Once you connect a device, you can run <code>$gpio i2cdetect</code> to determine if a device is detected on the I2C bus. In the example below, there is an electronic compass (GY-271) connected to the Pi.

[[File:I2cdetect.png|frame|none|alt=|An i2cdetect example]]

To initialize an I2C device, do the following:

<pre>import smbus
i2cdevice = smbus.SMBus(1) # 1 indicates /dev/i2c-1
address = 0x1e #whatever the device is for your i2c device</pre>
To read a byte from the I2C device:

<pre>result = i2cdevice.read_byte_data(address, <register>)</pre>
To write a byte to the I2C device:

<pre>i2cdevice.write_byte_data(address, <register>, <value>)</pre>
=== Methods Available ===

<code>smbus</code> has multiple methods. The documentation for these is quite minimal, but brief descriptions are available [http://wiki.erazor-zone.de/wiki:linux:python:smbus:doc here].

Note: If you're working with EEPROM (specifically 24C32), you may need to read the answer to the questions given [https://www.raspberrypi.org/forums/viewtopic.php?p=1401819&sid=582cace49dad59d93f4e0369047dd89d#p1401819 here].

== SPI ==

Ensure you enable SPI in <code>raspi-config</code>.

You can use SPI in Python by using the <code>spidev</code> library. Documentation is available [https://pypi.org/project/spidev/ here]. Basic usage is as follows:

<pre>import spidev

#Bus is 0 or 1, depending on which SPI bus you've connected to
bus = 0
#Device is the chip select pin. Set to 0 or 1, depending on the connections
device = 1

spi = spidev.SpiDev() #Enable SPI
spi.open(bus, device) #Open connection to a specific bus and device (CS pin)

# Set settings (SPI speed and mode)
spi.max_speed_hz = 500000
spi.mode = 0

to_send = [0x01, 0x02, 0x03] #define what to send
spi.xfer(to_send)

# Close the SPI connection
close()</pre>
=== Settings ===

The following settings are configurable in the <code>spidev</code> library, and can be set as follows:

<pre>spi = spidev.SpiDev() #Enable SPI
spi.<setting> = <value></pre>
List of settings:

* <code>bits_per_word</code>
* <code>cs_high</code>
* <code>loop</code><br />
Set the “SPI_LOOP” flag to enable loopback mode
* <code>no_cs</code><br />
Set the “SPI_NO_CS” flag to disable use of the chip select (although the driver may still own the CS pin)
* <code>lsbfirst</code>
* <code>max_speed_hz</code>
* <code>mode</code><br />
SPI mode as two bit pattern of clock polarity and phase [CPOL/CPHA], min: 0b00 = 0, max: 0b11 = 3
* <code>threewire</code><br />
SI/SO signals shared

=== Methods ===

The following methods are available in the <code>spidev</code> library

<ul>

<li><code>open(bus, device)</code><br>
Connects to the specified SPI device, opening <code>/dev/spidev<bus>.<device></code>
</li>
<li><code>readbytes(n)</code><br>
Read n bytes from SPI device.
</li>
<li><code>writebytes(list of values)</code><br />
Writes a list of values to SPI device.
</li>
<li> <code>writebytes2(list of values)</code><br />
Similar to ‘writebytes‘ but accepts arbitrary large lists. If list size exceeds buffer size (which is read from <code>/sys/module/spidev/parameters/bufsiz</code>), data will be split into smaller chunks and sent in multiple operations. Also, writebytes2 understands [https://docs.python.org/3/c-api/buffer.html buffer protocol] so it can accept numpy byte arrays for example without need to convert them with <code>tolist()</code> first. This offers much better performance where you need to transfer frames to SPI-connected displays for instance.
</li>
<li><code>xfer(list of values[, speed_hz, delay_usec, bits_per_word])</code><br />
Performs an SPI transaction. Chip-select should be released and reactivated between blocks. Delay specifies the delay in usec between blocks.
</li>
<li><code>xfer2(list of values[, speed_hz, delay_usec, bits_per_word])</code><br />
Performs an SPI transaction. Chip-select should be held active between blocks.
</li>
<li><code>xfer3(list of values[, speed_hz, delay_usec, bits_per_word])</code><br />
Similar to xfer2 but accepts arbitrary large lists. If list size exceeds buffer size (which is read from <code>/sys/module/spidev/parameters/bufsiz</code>), data will be split into smaller chunks and sent in multiple operations.
</li>
<li><code>close()</code><br />
Disconnects from the SPI device.
</li>
</ul>

= Using Threads =

[https://realpython.com/intro-to-python-threading/ This guide] serves as the basis for the text below. This manual does not teach everything there is to know about threading in Python, but will give you the basics to be able to utilize threads for simple tasks that may be of use to you in the practicals. It’s strongly recommended you read through that text if you have not yet been exposed to threading concepts.

This text does not cover issues and precautions when working with threads, such as mutex’s and locks, data races, producer/consumer concerns and the likes. However, these are knowledge areas of critical importance, and it is strongly suggested that the reader tries to make an effort to understand these concerns before writing threaded code.

== The Threading Library ==

The Python library <code>threading</code> library offers all the functionality one would expect. Import it in to your code in the standard way:

<pre>import threading</pre>
There are 4 basic things you need to do when creating a thread:

# Initialize it
# Start it
# Let is execute
# “Shut it down” by joining

== Basic Thread Usage ==

For example, if you want to create a separate thread to fetch a sensor value five times, you could do it as follows:

<pre>import threading
import time
import RPi.GPIO as GPIO

def setup():
#Contains all code for initialisation of RPi.GPIO

def fetch_sensor_vals(sensor_pin):
for i in range(5):
GPIO.input(sensor_pin)
time.sleep(2)

if __name__ == "__main__":
setup()
# Create a thread to call the function and pass "12" in as sensor pin
x = threading.Thread(target=fetch_sensor_vals, args=(12,))
print("Starting thread")
x.start()
print("Waiting for the thread to finish")
x.join()
print("Reading finished")</pre>
== Timed Thread Usage ==

Often in embedded systems we want a specific task to run every X time units. There is an option in the Python threading library. It works as follows:

<pre>import threading
import datetime

"""
This function prints the time to the screen every five seconds
"""
def print_time():
YOUR = threading.Timer(5.0, print_time)
YOUR.daemon = True
YOUR.start()
print(datetime.datetime.now())

if __name__ == "__main__":
print_time() # call it once to start the thread

# Tell our program to run indefinitely
while True:
pass</pre>
You will see that in this code example, we have also set the <code>daemon</code> flag of the thread to be be <code>True</code>. A daemon thread will shut down immediately when the program exits. In essence, the daemon thread will run indefinitely in the background until your application exits, and you do not need to worry about calling <code>join()</code>.<ref>It’s important to note that calling t.join() will wait for a thread to finish executing, even if it is a daemon.
</ref>

RaspberryPi:DebuggingConnectivity

2020-09-10T13:37:44Z

CRNKEE002: /* SSH'ing Into the Pi 0/0W */

File:RNDISWithCorrectDrivers.png

2020-09-10T13:32:24Z

CRNKEE002:

The Raspberry Pi 0/0W correctly picked up by Windows.

RaspberryPi:ProgrammingInPython

2020-09-10T10:07:02Z

CRNKEE002: /* Basic IO */

[[Category:RaspberryPi]]
= Overview =
Most of the content in the guide comes from the documentation, available online [https://sourceforge.net/p/raspberry-gpio-python/wiki/Home/ here].

Python, while not as powerful as C or C++, is quickly becoming a common choice for embedded systems developers due to its ease of use and rapid development times. See [https://spectrum.ieee.org/at-work/innovation/the-2018-top-programming-languages this IEEE article]. For information on programming in C or C++, go to [[RaspberryPi:ProgrammingInC]].

This chapter serves as a short guide for programming in Python on the RPi. You will also find some templates for techniques such as debouncing, or making use of the Raspberry Pi’s multicore architecture by implementing threading.

= The RPI.GPIO Library =

The RPi.GPIO library is the common Python library used on the Raspberry Pi. Documentation for the library can be found here:<br />
https://sourceforge.net/p/raspberry-gpio-python/wiki/Home/

It is included in the environment variables by default, so to use it, you can simply just import it into your Python script:

<syntaxhighlight lang="python">include RPi.GPIO as GPIO</syntaxhighlight>
You need to specify which board mode you’re using. For more information on board modes, see Section [[RaspberryPi:Overview#GPIO_Pins]]. Board modes are specified as follows:

<syntaxhighlight lang="python">GPIO.setmode(GPIO.BOARD)
# or
GPIO.setmode(GPIO.BCM)</syntaxhighlight>
You also need to perform “cleanup” on GPIOs when your application exists. By performing cleanup and resetting all pins to their default modes, you can prevent possible damage to your Raspberry Pi. The cleanup function is called as follows:

<syntaxhighlight lang="python">GPIO.cleanup()</syntaxhighlight>
If your program is meant to run indefinitely, and only close upon an exception, you can wrap it in a try catch, as follows:

<syntaxhighlight lang="python">if __name__ == "__main__":
# Make sure the GPIO is stopped correctly
try:
while True:
main()
except KeyboardInterrupt:
print("Exiting gracefully")
GPIO.cleanup()
except e:
print("Some other error occurred: {}".format(e.message)})
GPIO.cleanup()</syntaxhighlight>

= Basic IO =

Read the documentation, available [https://sourceforge.net/p/raspberry-gpio-python/wiki/Outputs/ here].

== Digital Logic ==

Digital output on the Raspberry Pi is accomplished by writing values to channels. A channel is a pin, which is numbered in the way you’ve configured. Basic configuration of a pin for output is as follows:

<syntaxhighlight lang="python">GPIO.output(<channel>, <Logic>)</syntaxhighlight>
Your logic (high, 3.3V, or low, 0V), can be specified as follows:

<ul>
<li><p>For 3.3V (high) output:</p>
<syntaxhighlight lang="python">
GPIO.output(<channel>, GPIO.HIGH)
GPIO.output(<channel>, 1)
GPIO.output(<channel>, True)
</syntaxhighlight></li>

<li><p>For 0V (low) output:</p>
<syntaxhighlight lang="python">
GPIO.output(<channel>, GPIO.LOW)
GPIO.output(<channel>, 0)
GPIO.output(<channel>, False)
</syntaxhighlight></li></ul>

Channels can also be specified in lists, for example:

<syntaxhighlight lang="python">LEDs = (11,12)
GPIO.output(LEDs, GPIO.HIGH) # Will turn all channels HIGH
GPIO.output(LEDs, (GPIO.HIGH, GPIO.LOW)) # Will the first channel HIGH, and the second LOW</syntaxhighlight>

Note that you can also read the state of the pin/channel that is set as an output by using the <code>input()</code> function. For example, if you wanted to toggle pin 12, you could do something as follows:

<syntaxhighlight lang="python">GPIO.output(12, not GPIO.input(12))</syntaxhighlight>

== Analog ==

The Raspberry Pi does not have any analog input pins. You will need to use something like the [https://cdn-shop.adafruit.com/datasheets/MCP3008.pdf MCP3008] to read analog voltages.

== Inputs ==

=== Digital Read ===

To read the value of a digital pin, you can use the <code>input()</code> function:

<syntaxhighlight lang="python">if GPIO.input(12):
print("Pin 12 HIGH")
else:
print("Pin 12 LOW")</syntaxhighlight>
=== Pull Up/Pull Down Resistors ===

Using pull up and pull down resistors is essential when working with digital logic. Thankfully, the Raspberry Pi has internal pull up and pull down resistors. To make use of these, initialize the pin/channel as follows:

<syntaxhighlight lang="python">GPIO.setup(<channel>, GPIO.IN, pull_up_down=GPIO.PUD_UP)
# or
GPIO.setup(<channel>, GPIO.IN, pull_up_down=GPIO.PUD_DOWN)</syntaxhighlight>
=== Interrupts ===

Very often it is useful to set up an interrupt, for example to trigger an event when a button is pressed. Callback functions are executed on a different thread. If you have multiple callbacks, know that they will be executed sequentially as only one thread exists for interrupts. Interrupts can be implemented as follows:

<syntaxhighlight lang="python"># The bounce time is given in milliseconds.
# If your pin is set to use pull down resistors
# Connect a button between <channel> and 3.3V
GPIO.add_event_detect(<channel>, GPIO.RISING, callback=callback_method(), bouncetime=200)
# If your pin is set to use pull up resistors
# Connect a button between <channel> and GND
GPIO.add_event_detect(<channel>, GPIO.FALLING, callback=callback_method(), bouncetime=200) </syntaxhighlight>
=== Other functions ===

The RPi.GPIO Library offers other functions for interrupts the first is the <code>wait_for_edge()</code> function, which is designed to block execution until an edge is detected. You can detect edges of <code>GPIO.RISING</code>, <code>GPIO.FALLING</code>, or <code>GPIO.BOTH</code>. The timeout is given in milliseconds:

<syntaxhighlight lang="python"># wait for up to 5 seconds for a rising edge
edge = GPIO.wait_for_edge(<channel>, GPIO_RISING, timeout=5000)
if edge is None:
print('Timeout occurred')
else:
print('Edge detected on pin <CHANNEL>')</syntaxhighlight>

Another function is the <code>event_detected()</code> function. From the docs: “The event_detected() function is designed to be used in a loop with other things, but unlike polling it is not going to miss the change in state of an input while the CPU is busy working on other things. This could be useful when using something like Pygame or PyQt where there is a main loop listening and responding to GUI events in a timely basis.”

<syntaxhighlight lang="python">GPIO.add_event_detect(channel, GPIO.RISING) # add rising edge detection on a channel
if GPIO.event_detected(channel):
print('Button pressed')</syntaxhighlight>

= Communication Protocols =

The RPi.GPIO library has no native support for communication protocols. Very often, specific Python libraries are provided on a per-device use case. However, this can become tedious and cause your code to become bloated. See the sections below for relevant libraries for using I2C and SPI directly.

== I2C ==

Ensure you enable I2C in <code>raspi-config</code>.

To use I2C in Python, you can use the <code>smbus</code> library. To do this, we need to install and configure smbus. This is usually done by default, but instructions are included for posterity.

<pre>$ sudo apt-get install i2c-tools
$ sudo apt-get install python-smbus
$ sudo adduser <username> i2c
$ sudo reboot</pre>
Once you connect a device, you can run <code>$gpio i2cdetect</code> to determine if a device is detected on the I2C bus. In the example below, there is an electronic compass (GY-271) connected to the Pi.

[[File:I2cdetect.png|frame|none|alt=|An i2cdetect example]]

To initialize an I2C device, do the following:

<pre>import smbus
i2cdevice = smbus.SMBus(1) # 1 indicates /dev/i2c-1
address = 0x1e #whatever the device is for your i2c device</pre>
To read a byte from the I2C device:

<pre>result = i2cdevice.read_byte_data(address, <register>)</pre>
To write a byte to the I2C device:

<pre>i2cdevice.write_byte_data(address, <register>, <value>)</pre>
=== Methods Available ===

<code>smbus</code> has multiple methods. The documentation for these is quite minimal, but brief descriptions are available [http://wiki.erazor-zone.de/wiki:linux:python:smbus:doc here].

== SPI ==

Ensure you enable SPI in <code>raspi-config</code>.

You can use SPI in Python by using the <code>spidev</code> library. Documentation is available [https://pypi.org/project/spidev/ here]. Basic usage is as follows:

<pre>import spidev

#Bus is 0 or 1, depending on which SPI bus you've connected to
bus = 0
#Device is the chip select pin. Set to 0 or 1, depending on the connections
device = 1

spi = spidev.SpiDev() #Enable SPI
spi.open(bus, device) #Open connection to a specific bus and device (CS pin)

# Set settings (SPI speed and mode)
spi.max_speed_hz = 500000
spi.mode = 0

to_send = [0x01, 0x02, 0x03] #define what to send
spi.xfer(to_send)

# Close the SPI connection
close()</pre>
=== Settings ===

The following settings are configurable in the <code>spidev</code> library, and can be set as follows:

<pre>spi = spidev.SpiDev() #Enable SPI
spi.<setting> = <value></pre>
List of settings:

* <code>bits_per_word</code>
* <code>cs_high</code>
* <code>loop</code><br />
Set the “SPI_LOOP” flag to enable loopback mode
* <code>no_cs</code><br />
Set the “SPI_NO_CS” flag to disable use of the chip select (although the driver may still own the CS pin)
* <code>lsbfirst</code>
* <code>max_speed_hz</code>
* <code>mode</code><br />
SPI mode as two bit pattern of clock polarity and phase [CPOL/CPHA], min: 0b00 = 0, max: 0b11 = 3
* <code>threewire</code><br />
SI/SO signals shared

=== Methods ===

The following methods are available in the <code>spidev</code> library

<ul>

<li><code>open(bus, device)</code><br>
Connects to the specified SPI device, opening <code>/dev/spidev<bus>.<device></code>
</li>
<li><code>readbytes(n)</code><br>
Read n bytes from SPI device.
</li>
<li><code>writebytes(list of values)</code><br />
Writes a list of values to SPI device.
</li>
<li> <code>writebytes2(list of values)</code><br />
Similar to ‘writebytes‘ but accepts arbitrary large lists. If list size exceeds buffer size (which is read from <code>/sys/module/spidev/parameters/bufsiz</code>), data will be split into smaller chunks and sent in multiple operations. Also, writebytes2 understands [https://docs.python.org/3/c-api/buffer.html buffer protocol] so it can accept numpy byte arrays for example without need to convert them with <code>tolist()</code> first. This offers much better performance where you need to transfer frames to SPI-connected displays for instance.
</li>
<li><code>xfer(list of values[, speed_hz, delay_usec, bits_per_word])</code><br />
Performs an SPI transaction. Chip-select should be released and reactivated between blocks. Delay specifies the delay in usec between blocks.
</li>
<li><code>xfer2(list of values[, speed_hz, delay_usec, bits_per_word])</code><br />
Performs an SPI transaction. Chip-select should be held active between blocks.
</li>
<li><code>xfer3(list of values[, speed_hz, delay_usec, bits_per_word])</code><br />
Similar to xfer2 but accepts arbitrary large lists. If list size exceeds buffer size (which is read from <code>/sys/module/spidev/parameters/bufsiz</code>), data will be split into smaller chunks and sent in multiple operations.
</li>
<li><code>close()</code><br />
Disconnects from the SPI device.
</li>
</ul>

= Using Threads =

[https://realpython.com/intro-to-python-threading/ This guide] serves as the basis for the text below. This manual does not teach everything there is to know about threading in Python, but will give you the basics to be able to utilize threads for simple tasks that may be of use to you in the practicals. It’s strongly recommended you read through that text if you have not yet been exposed to threading concepts.

This text does not cover issues and precautions when working with threads, such as mutex’s and locks, data races, producer/consumer concerns and the likes. However, these are knowledge areas of critical importance, and it is strongly suggested that the reader tries to make an effort to understand these concerns before writing threaded code.

== The Threading Library ==

The Python library <code>threading</code> library offers all the functionality one would expect. Import it in to your code in the standard way:

<pre>import threading</pre>
There are 4 basic things you need to do when creating a thread:

# Initialize it
# Start it
# Let is execute
# “Shut it down” by joining

== Basic Thread Usage ==

For example, if you want to create a separate thread to fetch a sensor value five times, you could do it as follows:

<pre>import threading
import time
import RPi.GPIO as GPIO

def setup():
#Contains all code for initialisation of RPi.GPIO

def fetch_sensor_vals(sensor_pin):
for i in range(5):
GPIO.input(sensor_pin)
time.sleep(2)

if __name__ == "__main__":
setup()
# Create a thread to call the function and pass "12" in as sensor pin
x = threading.Thread(target=fetch_sensor_vals, args=(12,))
print("Starting thread")
x.start()
print("Waiting for the thread to finish")
x.join()
print("Reading finished")</pre>
== Timed Thread Usage ==

Often in embedded systems we want a specific task to run every X time units. There is an option in the Python threading library. It works as follows:

<pre>import threading
import datetime

"""
This function prints the time to the screen every five seconds
"""
def print_time():
YOUR = threading.Timer(5.0, print_time)
YOUR.daemon = True
YOUR.start()
print(datetime.datetime.now())

if __name__ == "__main__":
print_time() # call it once to start the thread

# Tell our program to run indefinitely
while True:
pass</pre>
You will see that in this code example, we have also set the <code>daemon</code> flag of the thread to be be <code>True</code>. A daemon thread will shut down immediately when the program exits. In essence, the daemon thread will run indefinitely in the background until your application exits, and you do not need to worry about calling <code>join()</code>.<ref>It’s important to note that calling t.join() will wait for a thread to finish executing, even if it is a daemon.
</ref>

RaspberryPi:ProgrammingInPython

2020-09-10T09:59:29Z

CRNKEE002: /* The RPI.GPIO Library */

[[Category:RaspberryPi]]
= Overview =
Most of the content in the guide comes from the documentation, available online [https://sourceforge.net/p/raspberry-gpio-python/wiki/Home/ here].

Python, while not as powerful as C or C++, is quickly becoming a common choice for embedded systems developers due to its ease of use and rapid development times. See [https://spectrum.ieee.org/at-work/innovation/the-2018-top-programming-languages this IEEE article]. For information on programming in C or C++, go to [[RaspberryPi:ProgrammingInC]].

This chapter serves as a short guide for programming in Python on the RPi. You will also find some templates for techniques such as debouncing, or making use of the Raspberry Pi’s multicore architecture by implementing threading.

= The RPI.GPIO Library =

The RPi.GPIO library is the common Python library used on the Raspberry Pi. Documentation for the library can be found here:<br />
https://sourceforge.net/p/raspberry-gpio-python/wiki/Home/

It is included in the environment variables by default, so to use it, you can simply just import it into your Python script:

<syntaxhighlight lang="python">include RPi.GPIO as GPIO</syntaxhighlight>
You need to specify which board mode you’re using. For more information on board modes, see Section [[RaspberryPi:Overview#GPIO_Pins]]. Board modes are specified as follows:

<syntaxhighlight lang="python">GPIO.setmode(GPIO.BOARD)
# or
GPIO.setmode(GPIO.BCM)</syntaxhighlight>
You also need to perform “cleanup” on GPIOs when your application exists. By performing cleanup and resetting all pins to their default modes, you can prevent possible damage to your Raspberry Pi. The cleanup function is called as follows:

<syntaxhighlight lang="python">GPIO.cleanup()</syntaxhighlight>
If your program is meant to run indefinitely, and only close upon an exception, you can wrap it in a try catch, as follows:

<syntaxhighlight lang="python">if __name__ == "__main__":
# Make sure the GPIO is stopped correctly
try:
while True:
main()
except KeyboardInterrupt:
print("Exiting gracefully")
GPIO.cleanup()
except e:
print("Some other error occurred: {}".format(e.message)})
GPIO.cleanup()</syntaxhighlight>

= Basic IO =

Read the documentation, available [https://sourceforge.net/p/raspberry-gpio-python/wiki/Outputs/ here].

== Digital Logic ==

Digital output on the Raspberry Pi is accomplished by writing values to channels. A channel is a pin, which is numbered in the way you’ve configured. Basic configuration of a pin for output is as follows:

<pre>GPIO.output(<channel>, <Logic>)</pre>
Your logic (high, 3.3V, or low, 0V), can be specified as follows:

<ul>
<li><p>For 3.3V (high) output:</p>
<pre>
GPIO.output(<channel>, GPIO.HIGH)
GPIO.output(<channel>, 1)
GPIO.output(<channel>, True)
</pre></li>

<li><p>For 0V (low) output:</p>
<pre>
GPIO.output(<channel>, GPIO.LOW)
GPIO.output(<channel>, 0)
GPIO.output(<channel>, False)
</pre></li></ul>

Channels can also be specified in lists, for example:

<pre>LEDs = (11,12)
GPIO.output(LEDs, GPIO.HIGH) # Will turn all channels HIGH
GPIO.output(LEDs, (GPIO.HIGH, GPIO.LOW)) # Will the first channel HIGH, and the second LOW</pre>
Note that you can also read the state of the pin/channel that is set as an output by using the <code>input()</code> function. For example, if you wanted to toggle pin 12, you could do something as follows:

<pre>GPIO.output(12, not GPIO.input(12))</pre>

== Analog ==

The Raspberry Pi does not have any analog input pins. You will need to use something like the [https://cdn-shop.adafruit.com/datasheets/MCP3008.pdf MCP3008] to read analog voltages.

== Inputs ==

=== Digital Read ===

To read the value of a digital pin, you can use the <code>input()</code> function:

<pre>if GPIO.input(12):
print("Pin 12 HIGH")
else:
print("Pin 12 LOW")</pre>
=== Pull Up/Pull Down Resistors ===

Using pull up and pull down resistors is essential when working with digital logic. Thankfully, the Raspberry Pi has internal pull up and pull down resistors. To make use of these, initialize the pin/channel as follows:

<pre>GPIO.setup(<channel>, GPIO.IN, pull_up_down=GPIO.PUD_UP)
# or
GPIO.setup(<channel>, GPIO.IN, pull_up_down=GPIO.PUD_DOWN)</pre>
=== Interrupts ===

Very often it is useful to set up an interrupt, for example to trigger an event when a button is pressed. Callback functions are executed on a different thread. If you have multiple callbacks, know that they will be executed sequentially as only one thread exists for interrupts. Interrupts can be implemented as follows:

<pre># The bounce time is given in milliseconds.
# If your pin is set to use pull down resistors
# Connect a button between <channel> and 3.3V
GPIO.add_event_detect(<channel>, GPIO.RISING, callback=callback_method(), bouncetime=200)
# If your pin is set to use pull up resistors
# Connect a button between <channel> and GND
GPIO.add_event_detect(<channel>, GPIO.FALLING, callback=callback_method(), bouncetime=200) </pre>
=== Other functions ===

The RPi.GPIO Library offers other functions for interrupts the first is the <code>wait_for_edge()</code> function, which is designed to block execution until an edge is detected. You can detect edges of <code>GPIO.RISING</code>, <code>GPIO.FALLING</code>, or <code>GPIO.BOTH</code>. The timeout is given in milliseconds:

<pre># wait for up to 5 seconds for a rising edge
edge = GPIO.wait_for_edge(<channel>, GPIO_RISING, timeout=5000)
if edge is None:
print('Timeout occurred')
else:
print('Edge detected on pin ', TO)</pre>
Another function is the <code>event_detected()</code> function. From the docs: “The event_detected() function is designed to be used in a loop with other things, but unlike polling it is not going to miss the change in state of an input while the CPU is busy working on other things. This could be useful when using something like Pygame or PyQt where there is a main loop listening and responding to GUI events in a timely basis.”

<pre>GPIO.add_event_detect(channel, GPIO.RISING) # add rising edge detection on a channel
do_something()
if GPIO.event_detected(channel):
print('Button pressed')</pre>

= Communication Protocols =

The RPi.GPIO library has no native support for communication protocols. Very often, specific Python libraries are provided on a per-device use case. However, this can become tedious and cause your code to become bloated. See the sections below for relevant libraries for using I2C and SPI directly.

== I2C ==

Ensure you enable I2C in <code>raspi-config</code>.

To use I2C in Python, you can use the <code>smbus</code> library. To do this, we need to install and configure smbus. This is usually done by default, but instructions are included for posterity.

<pre>$ sudo apt-get install i2c-tools
$ sudo apt-get install python-smbus
$ sudo adduser <username> i2c
$ sudo reboot</pre>
Once you connect a device, you can run <code>$gpio i2cdetect</code> to determine if a device is detected on the I2C bus. In the example below, there is an electronic compass (GY-271) connected to the Pi.

[[File:I2cdetect.png|frame|none|alt=|An i2cdetect example]]

To initialize an I2C device, do the following:

<pre>import smbus
i2cdevice = smbus.SMBus(1) # 1 indicates /dev/i2c-1
address = 0x1e #whatever the device is for your i2c device</pre>
To read a byte from the I2C device:

<pre>result = i2cdevice.read_byte_data(address, <register>)</pre>
To write a byte to the I2C device:

<pre>i2cdevice.write_byte_data(address, <register>, <value>)</pre>
=== Methods Available ===

<code>smbus</code> has multiple methods. The documentation for these is quite minimal, but brief descriptions are available [http://wiki.erazor-zone.de/wiki:linux:python:smbus:doc here].

== SPI ==

Ensure you enable SPI in <code>raspi-config</code>.

You can use SPI in Python by using the <code>spidev</code> library. Documentation is available [https://pypi.org/project/spidev/ here]. Basic usage is as follows:

<pre>import spidev

#Bus is 0 or 1, depending on which SPI bus you've connected to
bus = 0
#Device is the chip select pin. Set to 0 or 1, depending on the connections
device = 1

spi = spidev.SpiDev() #Enable SPI
spi.open(bus, device) #Open connection to a specific bus and device (CS pin)

# Set settings (SPI speed and mode)
spi.max_speed_hz = 500000
spi.mode = 0

to_send = [0x01, 0x02, 0x03] #define what to send
spi.xfer(to_send)

# Close the SPI connection
close()</pre>
=== Settings ===

The following settings are configurable in the <code>spidev</code> library, and can be set as follows:

<pre>spi = spidev.SpiDev() #Enable SPI
spi.<setting> = <value></pre>
List of settings:

* <code>bits_per_word</code>
* <code>cs_high</code>
* <code>loop</code><br />
Set the “SPI_LOOP” flag to enable loopback mode
* <code>no_cs</code><br />
Set the “SPI_NO_CS” flag to disable use of the chip select (although the driver may still own the CS pin)
* <code>lsbfirst</code>
* <code>max_speed_hz</code>
* <code>mode</code><br />
SPI mode as two bit pattern of clock polarity and phase [CPOL/CPHA], min: 0b00 = 0, max: 0b11 = 3
* <code>threewire</code><br />
SI/SO signals shared

=== Methods ===

The following methods are available in the <code>spidev</code> library

<ul>

<li><code>open(bus, device)</code><br>
Connects to the specified SPI device, opening <code>/dev/spidev<bus>.<device></code>
</li>
<li><code>readbytes(n)</code><br>
Read n bytes from SPI device.
</li>
<li><code>writebytes(list of values)</code><br />
Writes a list of values to SPI device.
</li>
<li> <code>writebytes2(list of values)</code><br />
Similar to ‘writebytes‘ but accepts arbitrary large lists. If list size exceeds buffer size (which is read from <code>/sys/module/spidev/parameters/bufsiz</code>), data will be split into smaller chunks and sent in multiple operations. Also, writebytes2 understands [https://docs.python.org/3/c-api/buffer.html buffer protocol] so it can accept numpy byte arrays for example without need to convert them with <code>tolist()</code> first. This offers much better performance where you need to transfer frames to SPI-connected displays for instance.
</li>
<li><code>xfer(list of values[, speed_hz, delay_usec, bits_per_word])</code><br />
Performs an SPI transaction. Chip-select should be released and reactivated between blocks. Delay specifies the delay in usec between blocks.
</li>
<li><code>xfer2(list of values[, speed_hz, delay_usec, bits_per_word])</code><br />
Performs an SPI transaction. Chip-select should be held active between blocks.
</li>
<li><code>xfer3(list of values[, speed_hz, delay_usec, bits_per_word])</code><br />
Similar to xfer2 but accepts arbitrary large lists. If list size exceeds buffer size (which is read from <code>/sys/module/spidev/parameters/bufsiz</code>), data will be split into smaller chunks and sent in multiple operations.
</li>
<li><code>close()</code><br />
Disconnects from the SPI device.
</li>
</ul>

= Using Threads =

[https://realpython.com/intro-to-python-threading/ This guide] serves as the basis for the text below. This manual does not teach everything there is to know about threading in Python, but will give you the basics to be able to utilize threads for simple tasks that may be of use to you in the practicals. It’s strongly recommended you read through that text if you have not yet been exposed to threading concepts.

This text does not cover issues and precautions when working with threads, such as mutex’s and locks, data races, producer/consumer concerns and the likes. However, these are knowledge areas of critical importance, and it is strongly suggested that the reader tries to make an effort to understand these concerns before writing threaded code.

== The Threading Library ==

The Python library <code>threading</code> library offers all the functionality one would expect. Import it in to your code in the standard way:

<pre>import threading</pre>
There are 4 basic things you need to do when creating a thread:

# Initialize it
# Start it
# Let is execute
# “Shut it down” by joining

== Basic Thread Usage ==

For example, if you want to create a separate thread to fetch a sensor value five times, you could do it as follows:

<pre>import threading
import time
import RPi.GPIO as GPIO

def setup():
#Contains all code for initialisation of RPi.GPIO

def fetch_sensor_vals(sensor_pin):
for i in range(5):
GPIO.input(sensor_pin)
time.sleep(2)

if __name__ == "__main__":
setup()
# Create a thread to call the function and pass "12" in as sensor pin
x = threading.Thread(target=fetch_sensor_vals, args=(12,))
print("Starting thread")
x.start()
print("Waiting for the thread to finish")
x.join()
print("Reading finished")</pre>
== Timed Thread Usage ==

Often in embedded systems we want a specific task to run every X time units. There is an option in the Python threading library. It works as follows:

<pre>import threading
import datetime

"""
This function prints the time to the screen every five seconds
"""
def print_time():
YOUR = threading.Timer(5.0, print_time)
YOUR.daemon = True
YOUR.start()
print(datetime.datetime.now())

if __name__ == "__main__":
print_time() # call it once to start the thread

# Tell our program to run indefinitely
while True:
pass</pre>
You will see that in this code example, we have also set the <code>daemon</code> flag of the thread to be be <code>True</code>. A daemon thread will shut down immediately when the program exits. In essence, the daemon thread will run indefinitely in the background until your application exits, and you do not need to worry about calling <code>join()</code>.<ref>It’s important to note that calling t.join() will wait for a thread to finish executing, even if it is a daemon.
</ref>

RaspberryPi:DebuggingConnectivity

2020-09-10T09:06:04Z

CRNKEE002: /* Windows */

[[Category:RaspberryPi]]
= Debugging Connections =

This section is a work in progress. As more common issues are reported by students, this section will be expanded. It's important to note that most connectivity problems come down to an incorrectly configured file, where you may have missed a space, or misspelled something.

= Note for Windows Users =

If you are having trouble accessing the internet from your Pi using the Ethernet Passthrough technique, it’s likely the Windows bridge needs a reset. Change the IPv4 address of your Ethernet port to “Obtain an IP address automatically”, then on your WiFi connection, disable sharing, click okay, and then re-enable sharing. Go back to the IP configuration of your Ethernet post, and double check the IP to see if it’s been assigned 192.168.137.1. If not, you will need to change it using the “Advanced settings” button.

= Ping =
''Ping'' sends a packet to a particular host (in this case the Pi), and measures the time taken for a response from that host.

To use the ping command, open a command prompt window or terminal and type the following:

<pre>$ ping 192.168.137.15</pre>
If that host is unreachable (the Pi hasn’t booted yet or is incorrectly configured), a message will show that the host is unreachable. If everything was correctly configured, you should get

<pre>Reply from 192.168.137.15: bytes=32 time<1ns TTL=64</pre>
This means your Pi and computer are both correctly configured.

'''NB:''' Don’t be surprised if you can’t ping a Windows machine from your Pi. Windows blocks the specific type of packet required for a ping in the firewall.

= WiFi =

See if you can see wireless networks.

<pre>$ iwlist wlan0 scan</pre>
If you cannot connect via WiFi, enter into a shell on the Pi and run:

<pre>$ journalctl -u wpa_supplicant | grep wlan0
$ journalctl -u dhcpcd.service | grep wlan0</pre>
This will output the log files and notify you of any incorrect configurations in wpa_supplicant.

The following command will force the interface to be up (if it can be):

<pre>sudo ifconfig wlan0 up</pre>
If all else fails, reboot and try again. Some services can be restarted without restarting the Pi, for example:

<pre>sudo systemctl restart dhcpcd</pre>
Test wpa_supplicant config by killing the process, and running it in debug mode:

<pre>sudo killall wpa_supplicant
sudo /sbin/wpa_supplicant -d -c/etc/wpa_supplicant/wpa_supplicant.conf -Dnl80211,wext -iwlan0</pre>

= "Failure resolving URLs" or "unknown host" =

If you try to ping a website from the Pi and it fails, but pinging a IP such as 8.8.8.8 works as expected, it is likely an issue with DNS configuration. Open the resolv.conf file:

<pre>$ sudo nano /etc/resolv.conf</pre>
And edit it to read the following:

<pre>nameserver 8.8.8.8
nameserver 192.168.137.1</pre>
8.8.8.8 is the IP of Google’s DNS server. A DNS (Domain Name Service) server is responsible for converting human-readable addressed (for example google.co.za) to something the network architecture can understand (172.217.170.67, in this example).

If you still get this error, try running the following command:

<pre>$ sudo route add default gw 192.168.137.1</pre>
Where the IP supplied is the IP of the computer or router you are connected to.

= SSH'ing Into the Pi 0/0W =
This section assumes you've correctly modified the SD card contents using the correct editor, and are using the correct USB port on the Pi.
== Windows ==
<ol>
<li> Open up device manager by pressing the Windows key and X and selecting "Device Manager" from the drop down</li>
<li>If you have no other USB to Ethernet Gadgets plugged in, and you see this, it means your Pi is connected correctly and you need to double check you've installed Bonjour and are connecting to the correct hostname. PICTURE
</li>
<li> If under "Universal Serial Bus controllers" you see something like "Unknown USB Device (Device Descriptor Failed)", it means the driver is not installed. <br>
[[File:RNDISDriverNotInstalled.png|none|left]]
To install the driver, you need to do the following:
<ol>
<li>Right click on the "Unknown USB Device" and uninstall the driver.</li>
<li>Unplug the Pi from your computer</li>
<li>Download the RNDIS drivers here: [[Media:Mod-duo-rndis.zip|Windows 10 RNDIS Drivers]] </li>
<li>Extract the contents</li>
<li>Right click on "RNDIS.inf" and select "install"</li>
<li> Plug in the Raspberry Pi again, it should be picked up as a USB Ethernet Device under "Network Adapters"</li>
</ol>

</ol>

== Ubuntu ==

RaspberryPi:DebuggingConnectivity

2020-09-10T09:03:03Z

CRNKEE002:

[[Category:RaspberryPi]]
= Debugging Connections =

This section is a work in progress. As more common issues are reported by students, this section will be expanded. It's important to note that most connectivity problems come down to an incorrectly configured file, where you may have missed a space, or misspelled something.

= Note for Windows Users =

If you are having trouble accessing the internet from your Pi using the Ethernet Passthrough technique, it’s likely the Windows bridge needs a reset. Change the IPv4 address of your Ethernet port to “Obtain an IP address automatically”, then on your WiFi connection, disable sharing, click okay, and then re-enable sharing. Go back to the IP configuration of your Ethernet post, and double check the IP to see if it’s been assigned 192.168.137.1. If not, you will need to change it using the “Advanced settings” button.

= Ping =
''Ping'' sends a packet to a particular host (in this case the Pi), and measures the time taken for a response from that host.

To use the ping command, open a command prompt window or terminal and type the following:

<pre>$ ping 192.168.137.15</pre>
If that host is unreachable (the Pi hasn’t booted yet or is incorrectly configured), a message will show that the host is unreachable. If everything was correctly configured, you should get

<pre>Reply from 192.168.137.15: bytes=32 time<1ns TTL=64</pre>
This means your Pi and computer are both correctly configured.

'''NB:''' Don’t be surprised if you can’t ping a Windows machine from your Pi. Windows blocks the specific type of packet required for a ping in the firewall.

= WiFi =

See if you can see wireless networks.

<pre>$ iwlist wlan0 scan</pre>
If you cannot connect via WiFi, enter into a shell on the Pi and run:

<pre>$ journalctl -u wpa_supplicant | grep wlan0
$ journalctl -u dhcpcd.service | grep wlan0</pre>
This will output the log files and notify you of any incorrect configurations in wpa_supplicant.

The following command will force the interface to be up (if it can be):

<pre>sudo ifconfig wlan0 up</pre>
If all else fails, reboot and try again. Some services can be restarted without restarting the Pi, for example:

<pre>sudo systemctl restart dhcpcd</pre>
Test wpa_supplicant config by killing the process, and running it in debug mode:

<pre>sudo killall wpa_supplicant
sudo /sbin/wpa_supplicant -d -c/etc/wpa_supplicant/wpa_supplicant.conf -Dnl80211,wext -iwlan0</pre>

= "Failure resolving URLs" or "unknown host" =

If you try to ping a website from the Pi and it fails, but pinging a IP such as 8.8.8.8 works as expected, it is likely an issue with DNS configuration. Open the resolv.conf file:

<pre>$ sudo nano /etc/resolv.conf</pre>
And edit it to read the following:

<pre>nameserver 8.8.8.8
nameserver 192.168.137.1</pre>
8.8.8.8 is the IP of Google’s DNS server. A DNS (Domain Name Service) server is responsible for converting human-readable addressed (for example google.co.za) to something the network architecture can understand (172.217.170.67, in this example).

If you still get this error, try running the following command:

<pre>$ sudo route add default gw 192.168.137.1</pre>
Where the IP supplied is the IP of the computer or router you are connected to.

= SSH'ing Into the Pi 0/0W =
This section assumes you've correctly modified the SD card contents using the correct editor, and are using the correct USB port on the Pi.
== Windows ==
<ol>
<li> Open up device manager by pressing the Windows key and X and selecting "Device Manager" from the drop down</li>
<li>If you have no other USB to Ethernet Gadgets plugged in, and you see this, it means your Pi is connected correctly and you need to double check you've installed Bonjour and are connecting to the correct hostname. PICTURE
</li>
<li> If you see this, it means the driver is not installed. <br>
[[File:RNDISDriverNotInstalled.png|none|left]]
To install the driver, you need to do the following:
<ol>
<li>Right click on the "Unknown USB Device" and uninstall the driver.</li>
<li>Unplug the Pi from your computer</li>
<li>Download the RNDIS drivers here: [[Media:Mod-duo-rndis.zip|Windows 10 RNDIS Drivers]] </li>
<li>Extract the contents</li>
<li>Right click on "RNDIS.inf" and select "install"</li>
<li> Plug in the Raspberry Pi again, it should be picked up as a USB Ethernet Device under "Network Adapters"</li>
</ol>

</ol>
== Ubuntu ==

File:Mod-duo-rndis.zip

2020-09-10T08:54:18Z

CRNKEE002: RNDIS Drivers for Windows 10, useful for getting the Pi 0W to work.

== Summary ==
RNDIS Drivers for Windows 10, useful for getting the Pi 0W to work.

File:RNDISDriverNotInstalled.png

2020-09-10T08:47:22Z

CRNKEE002:

An image of device manager when Windows fails to install the RNDIS driver for use with the RaspberryPi

Visual Studio Code

2020-09-09T08:31:39Z

CRNKEE002: /* Useful plugins */

[[Category:Software]]
[[Category:IDEs]]
= Overview =
Visual Studio Code is a lightweight code editor with plugins for many different languages and frameworks.

= Installation =
See [https://code.visualstudio.com/docs/setup/setup-overview this link] for details on installation and configuration.

= Useful plugins =
== LaTeX Workshop ==
On Windows:
# Install the James Yu Tex workshop plugin
# Install Miktex-basic
# Install Perl

== Remote Development for the Raspberry Pi ==

Visual Studio Code

2020-09-09T08:30:54Z

CRNKEE002: /* Useful plugins */

RaspberryPi:Networking

2020-09-04T12:13:49Z

CRNKEE002: /* Internet Access over USB */

[[Category:RaspberryPi]]
There are many ways to interface with the Pi. This page will cover types of network connectivity. For more comprehensive, advanced networking details, see [[RaspberryPi:AdvancedConnectivity]].

= A Brief Overview of Networks =

It is useful to have a basic idea of how networks, IP addresses, and subnets work. For this, it it suggested you read [https://support.microsoft.com/en-za/help/164015/understanding-tcp-ip-addressing-and-subnetting-basics this article] from Microsoft.

= Wireless Connectivity =
WiFi connectivity is a useful way of connecting the Pi to the internet as it enables more portability. You can adjust WiFi Connections either before boot, by creating a <code>wpa_cupplicant.conf</code> file on the boot partition, or while the pi is running, either by editing <code>/etc/wpa/wpa_supplicant.conf</code> directly, or using <code>$ sudo raspi-config</code>. Note that the raspi-config method will not work for Eduroam.

== Simple Wifi Connections ==
If the Pi is up and running and you have access to it, you can run <code>$ sudo raspi-config</code> and enable WiFi using that menu, or editing <code>/etc/wpa/wpa_supplicant.conf</code> directly using an editor such as nano. However if you don't have access, you can create a a <code>wpa_supplicant.conf</code> file on the SD card, on the boot partition while it is plugged into another system.

If editing the wpa_supplicant configuration file, the contents should look something like the following:
<pre>
ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
update_config=1
country=ZA

network={
ssid="<Name of your WiFi network>"
psk="<Password for your WiFi network>"
}
</pre>

== Connecting to Eduroam ==
Connecting to Eduroam requires a fair amount of configuration which depends on your operating system. Generally though, edits to wpa_supplicant.conf and dhcpcd.conf are sufficient. Note that there are new releases of Raspberry Pi OS, and it is unknown if the edits for Buster are still required.

<span class="mw-customtoggle-Eduroam" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-Eduroam" class="mw-collapsible mw-collapsed">
=== Raspbian Buster ===
'''Note:''' There have been updates to the Buster code base, and roll back of wpasupplicant might not be required. However this is currently unable to be tested due to the lockdown. If someone has the chance to test, please update this page accordingly.
These instructions come from [https://www.raspberrypi.org/forums/viewtopic.php?p=1501822#p1501822 here].<br />
Unfortunately, when you use bleeding edge technology, you may end up cutting yourself. Raspbian Buster updates <code>wpa_supplicant</code> to a version that doesn’t have support for the authentication method used by Eduroam. So we need to roll back <code>wpa_supplicant</code> to an older version. Ensure your Pi has internet access through a method such as Ethernet passthrough, and run the following:

<pre>$ sudo apt-get remove wpasupplicant</pre>
Edit /etc/apt/sources.list :

<pre>$ sudo nano /etc/apt/sources.list</pre>
And change

<pre>deb http://raspbian.raspberrypi.org/raspbian/ buster main contrib non-free rpi</pre>
to

<pre>deb http://raspbian.raspberrypi.org/raspbian/ stretch main contrib non-free rpi</pre>
Run

<pre>$ sudo apt-get update
$ sudo apt-get install wpasupplicant</pre>
This will install the correct version of <code>wpa_supplicant</code>. Check that '''version 2.4''' is installed by running

<pre>$ wpa_supplicant -v</pre>
Now, change the sources file back.

<pre>$ sudo nano /etc/apt/sources.list</pre>
And edit the contents to contain

<pre>deb http://raspbian.raspberrypi.org/raspbian/ buster main contrib non-free rpi</pre>
Finally, run

<pre>$ sudo apt-get update</pre>
To update sources The correct version of <code>wpa_supplicant</code> should now be installed, and you can configure your Pi for WiFi as you would if you were using Raspbian Stretch as explained in below.

=== Raspbian Stretch ===

This section provides the instructions on how to configure the Pi to use Eduroam. It is possible to do using the GUI through VNC, but we will not cover that here.

<ol>
<li><p>SSH into your Pi.</p></li>
<li><p>Generate a hash for your password. Take note of it as it is needed in a later step</p>
<pre>
$ echo -n your_uct_password_here | iconv -t utf16le | openssl md4
</pre></li>
<li><p>Open /etc/wpa_supplicant/wpa_supplicant.conf</p>
<pre>$ sudo nano /etc/wpa_supplicant/wpa_supplicant.conf</pre></li>
<li><p>Edit it so it looks as follows:</p>
<pre>
ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
update_config=1
country=ZA

network={
ssid="eduroam"
key_mgmt=WPA-EAP
identity="studentnumber@wf.uct.ac.za"
password=hash:generated_hash_from_earlier
}
</pre></li>
<li><p>Save the file</p></li>
<li><p>Open <code>/etc/dhcpcd.conf</code></p>
<pre> $ sudo nano /etc/dhcpcd.conf</pre></li>
<li><p>Make sure the following lines are in the document:</p>
<pre>interface wlan0
metric 200
</pre></li>
<li><p>Reboot your Pi</p></li>
<li><p>WiFi Generally takes a little longer to initialize than Ethernet, so give it time. You can see if it’s ready by running</p>
<pre>$ ifconfig </pre>
<p>And seeing if an IPv4 address (“inet”) has been given.</p></li>
<li><p>Test your configuration by pinging from the WiFi interface:</p>
<pre>$ ping google.com -I wlan0</pre></li></ol>
</div>

= Ethernet Connectivity =
Ethernet is the physical connection made using a CAT 5 or 6 cable - though there are ways that Ethernet can be mimicked over USB (see Details on the Pi 0 and 0W for more information).

There are two sorts of Ethernet Connectivity we will consider. The first is just connecting the Pi to a known Ethernet network. It is simple as it requires no configuration, but it means you will need to use other methods to ensure the network allows SSH traffic and to ensure you can determine the IP of the Pi.

The second is using Ethernet passthrough from your computer to the Raspberry Pi. This leaves the WiFi free to host your own access point, and you can host services such as a Node-Red server or media center on the Pi.

If you're on a private network, connecting your Pi to a router will usually just assign it an IP address and internet connectivity automatically works. If you're on a linux-based system, like Ubuntu, you can use the hostname of the Pi to connect. By default this is "raspberrypi", so you could SSH in using "SSH pi@raspberrypi". However, in most cases, you'll want to know the IP address and assign a static IP address.

== Static IPs ==
Setting a static IP makes it easy to access the Pi and ensures that the IP address of the Pi is always known. In this course, we assign the Pi an IP address of 192.168.137.15. The reason for this is that when using Ethernet Passthrough on Windows, Windows asserts a domain of 192.168.137.x, with the host PC being assigned 192.168.137.1. Keep in mind that all devices will need to be on the same subnet though, so if you're assigning a static IP to be used on your own Ethernet network, you need to know what the subnet of that network is.

If you're connecting your Pi through your desktop, you'll need to assign a static IP to the desktop, too.

== Setting a static IP on your Desktop ==
If you're connecting your Pi through your desktop, you'll need to assign a static IP to the desktop, too. If you're setting a static IP on a Pi that's already connected directly to the network through a router or similar network switch, you can ignore setting a static IP on the computer.

=== Windows ===
<span class="mw-customtoggle-WindowsIP" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-WindowsIP" class="mw-collapsible mw-collapsed">
To change the IP of your Ethernet port on Windows 10, complete the following steps:

* Right click on your network option in Windows taskbar
* Select “Open Network & Internet Settings”, on the lower right hand side of the screen.
* Select “Change Adapted Options”
* Right click on the Ethernet Connection and select “Properties”
* Select “Internet Protocol Version 4 (TCP/IPv4) and click ”Properties"
* Select “Use the following IP address:” and enter in the following options:<br />
- IP Address: 192.168.137.1<br />
- Subnet Mask: 255.255.255.0
* You have successfully changed the IP of the Ethernet card on your computer. It is suggested that you now ensure connectivity by attempting to ping the Pi.

[[File:windowsIPConfig.png|thumb|none|alt=|The IPv4 configuration screen in Windows 10]]
</div>
=== Ubuntu ===
<span class="mw-customtoggle-UbuntuIP" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-UbuntuIP" class="mw-collapsible mw-collapsed">
To change the IP of your Ethernet port on Ubuntu, complete the following steps:

* Click the network interface icon on the status bar and select Wired Settings
* Click the gear button of the interface you’d like to change
* Select the IPv4 Tab, and change the IPv4 method to Manual
* Under “Addresses” enter in the following:<br />
- IP Address: 192.168.137.1<br />
- Subnet Mask: 255.255.255.0
* You can leave Gateway and DNS blank

[[File:Ubuntustaticip.png|thumb|none|alt=|The IPv4 configuration screen in Ubuntu 18.10]]
</div>

== Setting a static IP on the Pi ==
To set a static IP on the Pi, you have multiple options. You can do it before first boot by addling a line to cmdline.txt on the boot partition of the SD card, or once the Pi is running by editing dhcpcd.
Before setting the static IP, ensure you have the correct subdomain, and that you don't assign an IP that another device on the network is using. If you're assinging it a static IP and you have, for example, a router acting as a DHCP server, ensure the IP you assign is outside of DHCP range.

=== From the boot partition ===
<span class="mw-customtoggle-PiStaticBoot" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-PiStaticBoot" class="mw-collapsible mw-collapsed">
<ol>
<li><p>Insert the SD card into your computer and navigate to the BOOT partition</p></li>
<li><p>Open “cmdline.txt” and append the following to the line (don’t create a new line)</p>
<pre> ip=192.168.137.15 </pre>
<p>This tells the Raspberry Pi to configure the Ethernet port to use the IP address 192.168.137.15</p></li>
<li><p>Enable SSH as per Section [sec:SSH].</p></li>
<li><p>You need to configure your PC to use the same subnet as the Pi. To do so, see the information below in the section on Assigning a static IP to the Pi.</p></li></ol>
</div>
=== In dhcpcd (while the Pi is running)===
<span class="mw-customtoggle-PiStaticDHCPCD" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-PiStaticDHCPCD" class="mw-collapsible mw-collapsed">
Once you’ve successfully SSH’d into your Pi, it’s a good idea to configure the networking options in the config files directly. You will need to set a static IP on the computer first if you are SSH'ing through an Ethernet connection.

Use a text editor such as nano to open /etc/dhcpcd.conf as sudo user, and edit it to the following:

<pre># Static IP profile for eth0
profile static_eth0
static ip_address=192.168.137.15/24
static routers=192.168.137.1
static domain_name_servers=192.168.137.1 8.8.8.8

# Ethernet interface configuration
interface eth0
fallback static_eth0

# Wireless configuration
interface wlan0
metric 200</pre>
</div>

== WiFi to Ethernet Passthrough ==
In a situation when you can't or don't want to connect to a WiFi network, but are connected to a computer through an Ethernet port There may be a situation in which you want your Pi to work as an access point rather than using the WiFi interface to provide the Pi with internet access. In this situation, you need to get internet access through the Ethernet port. Before starting, you need to ensure the computer you're using has a static IP assigned. When enabling network sharing on Windows, it automatically assigns 192.168.137.1. Once that's done, complete the following to enable network sharing:

=== Windows ===
<span class="mw-customtoggle-PassthroughWindows" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-PassthroughWindows" class="mw-collapsible mw-collapsed">
# Ensure the Pi is unplugged
# Right click on your network option in Windows taskbar
# Select “Open Network & Internet Settings”, on the lower right hand side of the screen.
# Select “Change Adapted Options”
# Right click on your WiFi network and select “Properties”
# Click the “Sharing” tab, and enable the first checkbox <ref>This setting is what forces us to have to use the subnet 192.168.137.x.</ref>
# Select the Ethernet connection that your Pi will be using in the drop down box (Usually just “Ethernet”, but may be different if there are multiple Ethernet posts on your system)

[[File:Windowspassthrough.png|thumb|none|alt=|Using WiFi to Ethernet passthrough in Windows]]
</div>
=== Ubuntu ===
<span class="mw-customtoggle-PassthroughUbuntu" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-PassthroughUbuntu" class="mw-collapsible mw-collapsed">
# Ensure the Pi is unplugged and turned off.
# Open a terminal and run <code>nm-connection-editor</code>
# Select the wired connection you’d like to share your WiFi to
# Select the IPv4 settings tab
# Under Method, select “Shared to other computers”
# under the IP addresses, click “Add” and enter in an address of 192.168.137.1, and a netmask of 24
# Select “Save”, and close the windows
# Plug in the Pi, start an SSH session and see if you can ping google.co.za

[[File:Nm-connection-editor.png|thumb|none|alt=|nm-connection-editor in Ubuntu 18.10]]
</div>

= Other Connectivity Methods =
There are ways other than WiFi and Ethernet as a means of connecting headlessly (without a keyboard and screen directly attached) to the Pi.

== TTL over USB ==

'''Note:''' The Pi uses 3.3V logic levels. Using a 5V logic module will permanently damage the pins.

This option allows you to use a USB to UART converter such as a FT232R or CP2102. Begin by removing the SD card, and insert it into a computer. Make the following changes on the boot partition:

cmdline.txt: add the following (on the same line)

<pre>console=serial0,115200 </pre>
config.txt

<pre>uart_enable=1
dtoverlay=pi3-disable-bt</pre>

== Using USB connectivity on the Pi 0/0W ==
In order to use this method on Windows you require [https://support.apple.com/kb/DL999?locale=en_US Apple Bonjour Print Services] as well as [https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html PuTTY].

With the SD card plugged into your computer, open up the boot partition and make the following changes:
<ol>
<li>Be sure to enable SSH as described at [[RaspberryPi:Networking#Enabling_SSH]]</li>
<li>At the bottom of config.txt, add the following line
<pre>dtoverlay=dwc2</pre></li>
<li>On the '''same line''' in cmdline.txt, append the following:
<pre> modules-load=dwc2,g_ether</pre></li>
</ol>

Open up a terminal window (or PuTTY if you're on Windows).
After about 90 or so seconds, you should be able to SSH in (assuming you enabled SSH on the Pi) by connecting to <code>raspberrypi.local</code>.
You may (if you're using PuTTY) get a message about keys and hashes and hosts - just click "yes".
You can then log in with the username "pi" and the password "raspberry".

=== Internet Access over USB ===
If you don't have WiFi connectivity, you can send an internet connection from your computer over USB.

In order to provide the Pi with internet access, you need to do the following:
<ol>
<li> Share your computer's connection with the Pi as you have done in the "WiFi to Ethernet Passthrough" section above. You will be sharing your regular connection with an Ethernet connection, as that is how the Pi 0 has been set up. In the test I ran <li>
<li> On the Pi, you need to configure DHCPCD to have usb0 use a static IP of 192.168.137.x. The rest of this wiki has been written with x=15
<li> SSH in using "raspberrypi.local" as the address to connect to </li>
<li> Run <code> sudo nano /etc/dhcpcd.conf</code>, scroll to the bottom, and add the following:
<pre>
interface usb0
static ip_address=192.168.137.15
static router = 192.168.137.1
static domain_name_servers=192.168.137.1 8.8.8.8
</pre></li>
<li> Save and close the file </li>
<li> Run the command <code> sudo route add default gw 192.168.137.1 </code> </li>
<li> Reboot the Pi </li>
<li> SSH in again. You should be able to ssh in using "192.168.137.15" now, as well as "raspberrypi.local" </li>
<li> To test connectivity, try pinging google.com. You should get a valid response back. </li>
</ol>

= Ensuring Connectivity =

Sometimes you may want to debug your connection to the Pi. A fast way to do this is via the ''ping'' command. ''Ping'' sends a packet to a particular host (in this case the Pi), and measures the time taken for a response from that host.

To use the ping command, open a command prompt window or terminal and type the following:

<pre>$ ping 192.168.137.15</pre>
If that host is unreachable (the Pi hasn’t booted yet or is incorrectly configured), a message will show that the host is unreachable. If everything was correctly configured, you should get

<pre>Reply from 192.168.137.15: bytes=32 time<1ns TTL=64</pre>
This means your Pi and computer are both correctly configured. See section [sec:SSH] for configuring your Pi for SSH access.

'''NB:''' Don’t be surprised if you can’t ping a Windows machine from your Pi. Windows blocks the specific type of packet required for a ping in the firewall.

= Networking Protocols=
For a more detailed overview on useful networking protocols, see [[Network Protocols]]
== SSH ==

=== Enabling SSH ===

If you have not connected to your Pi and configured it for SSH, you need to do so. SSH is disabled by default on new installations of Raspbian.

To enable SSH, add it as an enabled service in the <code>raspi-config</code> menu. If you do not have access to the Pi as yet, do the following:

# Insert the SD card into a computer
# Navigate to the BOOT partition
# Create a file called “ssh”. <strong>Note there is no file extension!</strong>
# Your Pi will enable SSH upon next boot

=== Using SSH ===

To use SSH on your Pi, you need to connect to the computer to a network. See Section [sec:NetworkingOnThePi] on various ways that can be done (it is suggested to use Ethernet upon first connection).

Once your Pi is connected to the computer and you have ensured connection (see Section [sec:Connectivity-EnsuringConnectivity]), use can log in to your Pi via SSH. If you are on a Linux-based system, such as Ubuntu or Mac, you should be able to run the following. Note that the default username is “pi” and the default password is “raspberry”.

<pre>$ ssh <username>@192.168.137.15</pre>
If you are on Windows, you may need to use PuTTY. Some instances of windows have SSH in the command line, and you can run the command shown above. But if not, you will need to do the following:

# Open PuTTY
# In the “Hostname” field, enter in “192.168.137.15”
# Click “Open”. A terminal window will be opened. If it is the first time you’re SSH’ing into your Pi on this particular computer, you will be asked about the server fingerprint. Click “Yes” to continue.
# You will be asked for a username and password. The default username is “pi” and the password is “raspberry”.
# You should now successfully connected to your Raspberry Pi via SSH

== VNC ==
To learn about how to install VNC, see
# Ensure the VNC service is enabled on the Pi

#Connect to the Pi through VNC.
# Set your preferred resolution for Raspbian
## In the desktop menu, go to Preferences - Raspberry Pi Configuration and click the “Set Resolution” button.
## Select a more appropriate resolution (1280*720 suggested)
## Select “Okay” and then “Okay”. You will be asked to reboot your Pi, do so.
# Set the VNC resolution
## Through editing /boot/config.txt, uncomment the following lines relating to framebuffer_width and framebuffer_height
## On the desktop on VNC, use the settings. Do this if you have already connected to VNC. This is a little more difficult as it required you to play with windows in order to see the buttons you need.

RaspberryPi:Networking

2020-09-04T12:06:43Z

CRNKEE002: /* Internet Access over USB */

[[Category:RaspberryPi]]
There are many ways to interface with the Pi. This page will cover types of network connectivity. For more comprehensive, advanced networking details, see [[RaspberryPi:AdvancedConnectivity]].

= A Brief Overview of Networks =

It is useful to have a basic idea of how networks, IP addresses, and subnets work. For this, it it suggested you read [https://support.microsoft.com/en-za/help/164015/understanding-tcp-ip-addressing-and-subnetting-basics this article] from Microsoft.

= Wireless Connectivity =
WiFi connectivity is a useful way of connecting the Pi to the internet as it enables more portability. You can adjust WiFi Connections either before boot, by creating a <code>wpa_cupplicant.conf</code> file on the boot partition, or while the pi is running, either by editing <code>/etc/wpa/wpa_supplicant.conf</code> directly, or using <code>$ sudo raspi-config</code>. Note that the raspi-config method will not work for Eduroam.

== Simple Wifi Connections ==
If the Pi is up and running and you have access to it, you can run <code>$ sudo raspi-config</code> and enable WiFi using that menu, or editing <code>/etc/wpa/wpa_supplicant.conf</code> directly using an editor such as nano. However if you don't have access, you can create a a <code>wpa_supplicant.conf</code> file on the SD card, on the boot partition while it is plugged into another system.

If editing the wpa_supplicant configuration file, the contents should look something like the following:
<pre>
ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
update_config=1
country=ZA

network={
ssid="<Name of your WiFi network>"
psk="<Password for your WiFi network>"
}
</pre>

== Connecting to Eduroam ==
Connecting to Eduroam requires a fair amount of configuration which depends on your operating system. Generally though, edits to wpa_supplicant.conf and dhcpcd.conf are sufficient. Note that there are new releases of Raspberry Pi OS, and it is unknown if the edits for Buster are still required.

<span class="mw-customtoggle-Eduroam" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-Eduroam" class="mw-collapsible mw-collapsed">
=== Raspbian Buster ===
'''Note:''' There have been updates to the Buster code base, and roll back of wpasupplicant might not be required. However this is currently unable to be tested due to the lockdown. If someone has the chance to test, please update this page accordingly.
These instructions come from [https://www.raspberrypi.org/forums/viewtopic.php?p=1501822#p1501822 here].<br />
Unfortunately, when you use bleeding edge technology, you may end up cutting yourself. Raspbian Buster updates <code>wpa_supplicant</code> to a version that doesn’t have support for the authentication method used by Eduroam. So we need to roll back <code>wpa_supplicant</code> to an older version. Ensure your Pi has internet access through a method such as Ethernet passthrough, and run the following:

<pre>$ sudo apt-get remove wpasupplicant</pre>
Edit /etc/apt/sources.list :

<pre>$ sudo nano /etc/apt/sources.list</pre>
And change

<pre>deb http://raspbian.raspberrypi.org/raspbian/ buster main contrib non-free rpi</pre>
to

<pre>deb http://raspbian.raspberrypi.org/raspbian/ stretch main contrib non-free rpi</pre>
Run

<pre>$ sudo apt-get update
$ sudo apt-get install wpasupplicant</pre>
This will install the correct version of <code>wpa_supplicant</code>. Check that '''version 2.4''' is installed by running

<pre>$ wpa_supplicant -v</pre>
Now, change the sources file back.

<pre>$ sudo nano /etc/apt/sources.list</pre>
And edit the contents to contain

<pre>deb http://raspbian.raspberrypi.org/raspbian/ buster main contrib non-free rpi</pre>
Finally, run

<pre>$ sudo apt-get update</pre>
To update sources The correct version of <code>wpa_supplicant</code> should now be installed, and you can configure your Pi for WiFi as you would if you were using Raspbian Stretch as explained in below.

=== Raspbian Stretch ===

This section provides the instructions on how to configure the Pi to use Eduroam. It is possible to do using the GUI through VNC, but we will not cover that here.

<ol>
<li><p>SSH into your Pi.</p></li>
<li><p>Generate a hash for your password. Take note of it as it is needed in a later step</p>
<pre>
$ echo -n your_uct_password_here | iconv -t utf16le | openssl md4
</pre></li>
<li><p>Open /etc/wpa_supplicant/wpa_supplicant.conf</p>
<pre>$ sudo nano /etc/wpa_supplicant/wpa_supplicant.conf</pre></li>
<li><p>Edit it so it looks as follows:</p>
<pre>
ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
update_config=1
country=ZA

network={
ssid="eduroam"
key_mgmt=WPA-EAP
identity="studentnumber@wf.uct.ac.za"
password=hash:generated_hash_from_earlier
}
</pre></li>
<li><p>Save the file</p></li>
<li><p>Open <code>/etc/dhcpcd.conf</code></p>
<pre> $ sudo nano /etc/dhcpcd.conf</pre></li>
<li><p>Make sure the following lines are in the document:</p>
<pre>interface wlan0
metric 200
</pre></li>
<li><p>Reboot your Pi</p></li>
<li><p>WiFi Generally takes a little longer to initialize than Ethernet, so give it time. You can see if it’s ready by running</p>
<pre>$ ifconfig </pre>
<p>And seeing if an IPv4 address (“inet”) has been given.</p></li>
<li><p>Test your configuration by pinging from the WiFi interface:</p>
<pre>$ ping google.com -I wlan0</pre></li></ol>
</div>

= Ethernet Connectivity =
Ethernet is the physical connection made using a CAT 5 or 6 cable - though there are ways that Ethernet can be mimicked over USB (see Details on the Pi 0 and 0W for more information).

There are two sorts of Ethernet Connectivity we will consider. The first is just connecting the Pi to a known Ethernet network. It is simple as it requires no configuration, but it means you will need to use other methods to ensure the network allows SSH traffic and to ensure you can determine the IP of the Pi.

The second is using Ethernet passthrough from your computer to the Raspberry Pi. This leaves the WiFi free to host your own access point, and you can host services such as a Node-Red server or media center on the Pi.

If you're on a private network, connecting your Pi to a router will usually just assign it an IP address and internet connectivity automatically works. If you're on a linux-based system, like Ubuntu, you can use the hostname of the Pi to connect. By default this is "raspberrypi", so you could SSH in using "SSH pi@raspberrypi". However, in most cases, you'll want to know the IP address and assign a static IP address.

== Static IPs ==
Setting a static IP makes it easy to access the Pi and ensures that the IP address of the Pi is always known. In this course, we assign the Pi an IP address of 192.168.137.15. The reason for this is that when using Ethernet Passthrough on Windows, Windows asserts a domain of 192.168.137.x, with the host PC being assigned 192.168.137.1. Keep in mind that all devices will need to be on the same subnet though, so if you're assigning a static IP to be used on your own Ethernet network, you need to know what the subnet of that network is.

If you're connecting your Pi through your desktop, you'll need to assign a static IP to the desktop, too.

== Setting a static IP on your Desktop ==
If you're connecting your Pi through your desktop, you'll need to assign a static IP to the desktop, too. If you're setting a static IP on a Pi that's already connected directly to the network through a router or similar network switch, you can ignore setting a static IP on the computer.

=== Windows ===
<span class="mw-customtoggle-WindowsIP" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-WindowsIP" class="mw-collapsible mw-collapsed">
To change the IP of your Ethernet port on Windows 10, complete the following steps:

* Right click on your network option in Windows taskbar
* Select “Open Network & Internet Settings”, on the lower right hand side of the screen.
* Select “Change Adapted Options”
* Right click on the Ethernet Connection and select “Properties”
* Select “Internet Protocol Version 4 (TCP/IPv4) and click ”Properties"
* Select “Use the following IP address:” and enter in the following options:<br />
- IP Address: 192.168.137.1<br />
- Subnet Mask: 255.255.255.0
* You have successfully changed the IP of the Ethernet card on your computer. It is suggested that you now ensure connectivity by attempting to ping the Pi.

[[File:windowsIPConfig.png|thumb|none|alt=|The IPv4 configuration screen in Windows 10]]
</div>
=== Ubuntu ===
<span class="mw-customtoggle-UbuntuIP" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-UbuntuIP" class="mw-collapsible mw-collapsed">
To change the IP of your Ethernet port on Ubuntu, complete the following steps:

* Click the network interface icon on the status bar and select Wired Settings
* Click the gear button of the interface you’d like to change
* Select the IPv4 Tab, and change the IPv4 method to Manual
* Under “Addresses” enter in the following:<br />
- IP Address: 192.168.137.1<br />
- Subnet Mask: 255.255.255.0
* You can leave Gateway and DNS blank

[[File:Ubuntustaticip.png|thumb|none|alt=|The IPv4 configuration screen in Ubuntu 18.10]]
</div>

== Setting a static IP on the Pi ==
To set a static IP on the Pi, you have multiple options. You can do it before first boot by addling a line to cmdline.txt on the boot partition of the SD card, or once the Pi is running by editing dhcpcd.
Before setting the static IP, ensure you have the correct subdomain, and that you don't assign an IP that another device on the network is using. If you're assinging it a static IP and you have, for example, a router acting as a DHCP server, ensure the IP you assign is outside of DHCP range.

=== From the boot partition ===
<span class="mw-customtoggle-PiStaticBoot" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-PiStaticBoot" class="mw-collapsible mw-collapsed">
<ol>
<li><p>Insert the SD card into your computer and navigate to the BOOT partition</p></li>
<li><p>Open “cmdline.txt” and append the following to the line (don’t create a new line)</p>
<pre> ip=192.168.137.15 </pre>
<p>This tells the Raspberry Pi to configure the Ethernet port to use the IP address 192.168.137.15</p></li>
<li><p>Enable SSH as per Section [sec:SSH].</p></li>
<li><p>You need to configure your PC to use the same subnet as the Pi. To do so, see the information below in the section on Assigning a static IP to the Pi.</p></li></ol>
</div>
=== In dhcpcd (while the Pi is running)===
<span class="mw-customtoggle-PiStaticDHCPCD" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-PiStaticDHCPCD" class="mw-collapsible mw-collapsed">
Once you’ve successfully SSH’d into your Pi, it’s a good idea to configure the networking options in the config files directly. You will need to set a static IP on the computer first if you are SSH'ing through an Ethernet connection.

Use a text editor such as nano to open /etc/dhcpcd.conf as sudo user, and edit it to the following:

<pre># Static IP profile for eth0
profile static_eth0
static ip_address=192.168.137.15/24
static routers=192.168.137.1
static domain_name_servers=192.168.137.1 8.8.8.8

# Ethernet interface configuration
interface eth0
fallback static_eth0

# Wireless configuration
interface wlan0
metric 200</pre>
</div>

== WiFi to Ethernet Passthrough ==
In a situation when you can't or don't want to connect to a WiFi network, but are connected to a computer through an Ethernet port There may be a situation in which you want your Pi to work as an access point rather than using the WiFi interface to provide the Pi with internet access. In this situation, you need to get internet access through the Ethernet port. Before starting, you need to ensure the computer you're using has a static IP assigned. When enabling network sharing on Windows, it automatically assigns 192.168.137.1. Once that's done, complete the following to enable network sharing:

=== Windows ===
<span class="mw-customtoggle-PassthroughWindows" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-PassthroughWindows" class="mw-collapsible mw-collapsed">
# Ensure the Pi is unplugged
# Right click on your network option in Windows taskbar
# Select “Open Network & Internet Settings”, on the lower right hand side of the screen.
# Select “Change Adapted Options”
# Right click on your WiFi network and select “Properties”
# Click the “Sharing” tab, and enable the first checkbox <ref>This setting is what forces us to have to use the subnet 192.168.137.x.</ref>
# Select the Ethernet connection that your Pi will be using in the drop down box (Usually just “Ethernet”, but may be different if there are multiple Ethernet posts on your system)

[[File:Windowspassthrough.png|thumb|none|alt=|Using WiFi to Ethernet passthrough in Windows]]
</div>
=== Ubuntu ===
<span class="mw-customtoggle-PassthroughUbuntu" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-PassthroughUbuntu" class="mw-collapsible mw-collapsed">
# Ensure the Pi is unplugged and turned off.
# Open a terminal and run <code>nm-connection-editor</code>
# Select the wired connection you’d like to share your WiFi to
# Select the IPv4 settings tab
# Under Method, select “Shared to other computers”
# under the IP addresses, click “Add” and enter in an address of 192.168.137.1, and a netmask of 24
# Select “Save”, and close the windows
# Plug in the Pi, start an SSH session and see if you can ping google.co.za

[[File:Nm-connection-editor.png|thumb|none|alt=|nm-connection-editor in Ubuntu 18.10]]
</div>

= Other Connectivity Methods =
There are ways other than WiFi and Ethernet as a means of connecting headlessly (without a keyboard and screen directly attached) to the Pi.

== TTL over USB ==

'''Note:''' The Pi uses 3.3V logic levels. Using a 5V logic module will permanently damage the pins.

This option allows you to use a USB to UART converter such as a FT232R or CP2102. Begin by removing the SD card, and insert it into a computer. Make the following changes on the boot partition:

cmdline.txt: add the following (on the same line)

<pre>console=serial0,115200 </pre>
config.txt

<pre>uart_enable=1
dtoverlay=pi3-disable-bt</pre>

== Using USB connectivity on the Pi 0/0W ==
In order to use this method on Windows you require [https://support.apple.com/kb/DL999?locale=en_US Apple Bonjour Print Services] as well as [https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html PuTTY].

With the SD card plugged into your computer, open up the boot partition and make the following changes:
<ol>
<li>Be sure to enable SSH as described at [[RaspberryPi:Networking#Enabling_SSH]]</li>
<li>At the bottom of config.txt, add the following line
<pre>dtoverlay=dwc2</pre></li>
<li>On the '''same line''' in cmdline.txt, append the following:
<pre> modules-load=dwc2,g_ether</pre></li>
</ol>

Open up a terminal window (or PuTTY if you're on Windows).
After about 90 or so seconds, you should be able to SSH in (assuming you enabled SSH on the Pi) by connecting to <code>raspberrypi.local</code>.
You may (if you're using PuTTY) get a message about keys and hashes and hosts - just click "yes".
You can then log in with the username "pi" and the password "raspberry".

=== Internet Access over USB ===
If you don't have WiFi connectivity, you can send an internet connection from your computer over USB.

In order to provide the Pi with internet access, you need to do the following:
<ol>
<li> Share your computer's connection with the Pi as you have done in the "WiFi to Ethernet Passthrough" section above. You will be sharing your regular connection with an Ethernet connection, as that is how the Pi 0 has been set up. In the test I ran <li>
# On the Pi, you need to configure DHCPCD to have usb0 use a static IP of 192.168.137.x. The rest of this wiki has been written with x=15
# SSH in using "raspberrypi.local" as the address to connect to
# Run <code> sudo nano /etc/dhcpcd.conf</code>, scroll to the bottom, and add the following:
<pre>
interface usb0
static ip_address=192.168.137.15
static router = 192.168.137.1
static domain_name_servers=192.168.137.1 8.8.8.8
</pre>
# Save and close the file
# Run the command <code> sudo route add default gw 192.168.137.1 </code>
# Reboot the Pi
# SSH in again. You should be able to ssh in using "192.168.137.15" now, as well as "raspberrypi.local"
# To test connectivity, try pinging google.com. You should get a valid response back.
</ol>

= Ensuring Connectivity =

Sometimes you may want to debug your connection to the Pi. A fast way to do this is via the ''ping'' command. ''Ping'' sends a packet to a particular host (in this case the Pi), and measures the time taken for a response from that host.

To use the ping command, open a command prompt window or terminal and type the following:

<pre>$ ping 192.168.137.15</pre>
If that host is unreachable (the Pi hasn’t booted yet or is incorrectly configured), a message will show that the host is unreachable. If everything was correctly configured, you should get

<pre>Reply from 192.168.137.15: bytes=32 time<1ns TTL=64</pre>
This means your Pi and computer are both correctly configured. See section [sec:SSH] for configuring your Pi for SSH access.

'''NB:''' Don’t be surprised if you can’t ping a Windows machine from your Pi. Windows blocks the specific type of packet required for a ping in the firewall.

= Networking Protocols=
For a more detailed overview on useful networking protocols, see [[Network Protocols]]
== SSH ==

=== Enabling SSH ===

If you have not connected to your Pi and configured it for SSH, you need to do so. SSH is disabled by default on new installations of Raspbian.

To enable SSH, add it as an enabled service in the <code>raspi-config</code> menu. If you do not have access to the Pi as yet, do the following:

# Insert the SD card into a computer
# Navigate to the BOOT partition
# Create a file called “ssh”. <strong>Note there is no file extension!</strong>
# Your Pi will enable SSH upon next boot

=== Using SSH ===

To use SSH on your Pi, you need to connect to the computer to a network. See Section [sec:NetworkingOnThePi] on various ways that can be done (it is suggested to use Ethernet upon first connection).

Once your Pi is connected to the computer and you have ensured connection (see Section [sec:Connectivity-EnsuringConnectivity]), use can log in to your Pi via SSH. If you are on a Linux-based system, such as Ubuntu or Mac, you should be able to run the following. Note that the default username is “pi” and the default password is “raspberry”.

<pre>$ ssh <username>@192.168.137.15</pre>
If you are on Windows, you may need to use PuTTY. Some instances of windows have SSH in the command line, and you can run the command shown above. But if not, you will need to do the following:

# Open PuTTY
# In the “Hostname” field, enter in “192.168.137.15”
# Click “Open”. A terminal window will be opened. If it is the first time you’re SSH’ing into your Pi on this particular computer, you will be asked about the server fingerprint. Click “Yes” to continue.
# You will be asked for a username and password. The default username is “pi” and the password is “raspberry”.
# You should now successfully connected to your Raspberry Pi via SSH

== VNC ==
To learn about how to install VNC, see
# Ensure the VNC service is enabled on the Pi

#Connect to the Pi through VNC.
# Set your preferred resolution for Raspbian
## In the desktop menu, go to Preferences - Raspberry Pi Configuration and click the “Set Resolution” button.
## Select a more appropriate resolution (1280*720 suggested)
## Select “Okay” and then “Okay”. You will be asked to reboot your Pi, do so.
# Set the VNC resolution
## Through editing /boot/config.txt, uncomment the following lines relating to framebuffer_width and framebuffer_height
## On the desktop on VNC, use the settings. Do this if you have already connected to VNC. This is a little more difficult as it required you to play with windows in order to see the buttons you need.

RaspberryPi:Networking

2020-09-04T12:05:46Z

CRNKEE002: /* Using USB connectivity on the Pi 0/0W */

[[Category:RaspberryPi]]
There are many ways to interface with the Pi. This page will cover types of network connectivity. For more comprehensive, advanced networking details, see [[RaspberryPi:AdvancedConnectivity]].

= A Brief Overview of Networks =

It is useful to have a basic idea of how networks, IP addresses, and subnets work. For this, it it suggested you read [https://support.microsoft.com/en-za/help/164015/understanding-tcp-ip-addressing-and-subnetting-basics this article] from Microsoft.

= Wireless Connectivity =
WiFi connectivity is a useful way of connecting the Pi to the internet as it enables more portability. You can adjust WiFi Connections either before boot, by creating a <code>wpa_cupplicant.conf</code> file on the boot partition, or while the pi is running, either by editing <code>/etc/wpa/wpa_supplicant.conf</code> directly, or using <code>$ sudo raspi-config</code>. Note that the raspi-config method will not work for Eduroam.

== Simple Wifi Connections ==
If the Pi is up and running and you have access to it, you can run <code>$ sudo raspi-config</code> and enable WiFi using that menu, or editing <code>/etc/wpa/wpa_supplicant.conf</code> directly using an editor such as nano. However if you don't have access, you can create a a <code>wpa_supplicant.conf</code> file on the SD card, on the boot partition while it is plugged into another system.

If editing the wpa_supplicant configuration file, the contents should look something like the following:
<pre>
ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
update_config=1
country=ZA

network={
ssid="<Name of your WiFi network>"
psk="<Password for your WiFi network>"
}
</pre>

== Connecting to Eduroam ==
Connecting to Eduroam requires a fair amount of configuration which depends on your operating system. Generally though, edits to wpa_supplicant.conf and dhcpcd.conf are sufficient. Note that there are new releases of Raspberry Pi OS, and it is unknown if the edits for Buster are still required.

<span class="mw-customtoggle-Eduroam" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-Eduroam" class="mw-collapsible mw-collapsed">
=== Raspbian Buster ===
'''Note:''' There have been updates to the Buster code base, and roll back of wpasupplicant might not be required. However this is currently unable to be tested due to the lockdown. If someone has the chance to test, please update this page accordingly.
These instructions come from [https://www.raspberrypi.org/forums/viewtopic.php?p=1501822#p1501822 here].<br />
Unfortunately, when you use bleeding edge technology, you may end up cutting yourself. Raspbian Buster updates <code>wpa_supplicant</code> to a version that doesn’t have support for the authentication method used by Eduroam. So we need to roll back <code>wpa_supplicant</code> to an older version. Ensure your Pi has internet access through a method such as Ethernet passthrough, and run the following:

<pre>$ sudo apt-get remove wpasupplicant</pre>
Edit /etc/apt/sources.list :

<pre>$ sudo nano /etc/apt/sources.list</pre>
And change

<pre>deb http://raspbian.raspberrypi.org/raspbian/ buster main contrib non-free rpi</pre>
to

<pre>deb http://raspbian.raspberrypi.org/raspbian/ stretch main contrib non-free rpi</pre>
Run

<pre>$ sudo apt-get update
$ sudo apt-get install wpasupplicant</pre>
This will install the correct version of <code>wpa_supplicant</code>. Check that '''version 2.4''' is installed by running

<pre>$ wpa_supplicant -v</pre>
Now, change the sources file back.

<pre>$ sudo nano /etc/apt/sources.list</pre>
And edit the contents to contain

<pre>deb http://raspbian.raspberrypi.org/raspbian/ buster main contrib non-free rpi</pre>
Finally, run

<pre>$ sudo apt-get update</pre>
To update sources The correct version of <code>wpa_supplicant</code> should now be installed, and you can configure your Pi for WiFi as you would if you were using Raspbian Stretch as explained in below.

=== Raspbian Stretch ===

This section provides the instructions on how to configure the Pi to use Eduroam. It is possible to do using the GUI through VNC, but we will not cover that here.

<ol>
<li><p>SSH into your Pi.</p></li>
<li><p>Generate a hash for your password. Take note of it as it is needed in a later step</p>
<pre>
$ echo -n your_uct_password_here | iconv -t utf16le | openssl md4
</pre></li>
<li><p>Open /etc/wpa_supplicant/wpa_supplicant.conf</p>
<pre>$ sudo nano /etc/wpa_supplicant/wpa_supplicant.conf</pre></li>
<li><p>Edit it so it looks as follows:</p>
<pre>
ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
update_config=1
country=ZA

network={
ssid="eduroam"
key_mgmt=WPA-EAP
identity="studentnumber@wf.uct.ac.za"
password=hash:generated_hash_from_earlier
}
</pre></li>
<li><p>Save the file</p></li>
<li><p>Open <code>/etc/dhcpcd.conf</code></p>
<pre> $ sudo nano /etc/dhcpcd.conf</pre></li>
<li><p>Make sure the following lines are in the document:</p>
<pre>interface wlan0
metric 200
</pre></li>
<li><p>Reboot your Pi</p></li>
<li><p>WiFi Generally takes a little longer to initialize than Ethernet, so give it time. You can see if it’s ready by running</p>
<pre>$ ifconfig </pre>
<p>And seeing if an IPv4 address (“inet”) has been given.</p></li>
<li><p>Test your configuration by pinging from the WiFi interface:</p>
<pre>$ ping google.com -I wlan0</pre></li></ol>
</div>

= Ethernet Connectivity =
Ethernet is the physical connection made using a CAT 5 or 6 cable - though there are ways that Ethernet can be mimicked over USB (see Details on the Pi 0 and 0W for more information).

There are two sorts of Ethernet Connectivity we will consider. The first is just connecting the Pi to a known Ethernet network. It is simple as it requires no configuration, but it means you will need to use other methods to ensure the network allows SSH traffic and to ensure you can determine the IP of the Pi.

The second is using Ethernet passthrough from your computer to the Raspberry Pi. This leaves the WiFi free to host your own access point, and you can host services such as a Node-Red server or media center on the Pi.

If you're on a private network, connecting your Pi to a router will usually just assign it an IP address and internet connectivity automatically works. If you're on a linux-based system, like Ubuntu, you can use the hostname of the Pi to connect. By default this is "raspberrypi", so you could SSH in using "SSH pi@raspberrypi". However, in most cases, you'll want to know the IP address and assign a static IP address.

== Static IPs ==
Setting a static IP makes it easy to access the Pi and ensures that the IP address of the Pi is always known. In this course, we assign the Pi an IP address of 192.168.137.15. The reason for this is that when using Ethernet Passthrough on Windows, Windows asserts a domain of 192.168.137.x, with the host PC being assigned 192.168.137.1. Keep in mind that all devices will need to be on the same subnet though, so if you're assigning a static IP to be used on your own Ethernet network, you need to know what the subnet of that network is.

If you're connecting your Pi through your desktop, you'll need to assign a static IP to the desktop, too.

== Setting a static IP on your Desktop ==
If you're connecting your Pi through your desktop, you'll need to assign a static IP to the desktop, too. If you're setting a static IP on a Pi that's already connected directly to the network through a router or similar network switch, you can ignore setting a static IP on the computer.

=== Windows ===
<span class="mw-customtoggle-WindowsIP" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-WindowsIP" class="mw-collapsible mw-collapsed">
To change the IP of your Ethernet port on Windows 10, complete the following steps:

* Right click on your network option in Windows taskbar
* Select “Open Network & Internet Settings”, on the lower right hand side of the screen.
* Select “Change Adapted Options”
* Right click on the Ethernet Connection and select “Properties”
* Select “Internet Protocol Version 4 (TCP/IPv4) and click ”Properties"
* Select “Use the following IP address:” and enter in the following options:<br />
- IP Address: 192.168.137.1<br />
- Subnet Mask: 255.255.255.0
* You have successfully changed the IP of the Ethernet card on your computer. It is suggested that you now ensure connectivity by attempting to ping the Pi.

[[File:windowsIPConfig.png|thumb|none|alt=|The IPv4 configuration screen in Windows 10]]
</div>
=== Ubuntu ===
<span class="mw-customtoggle-UbuntuIP" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-UbuntuIP" class="mw-collapsible mw-collapsed">
To change the IP of your Ethernet port on Ubuntu, complete the following steps:

* Click the network interface icon on the status bar and select Wired Settings
* Click the gear button of the interface you’d like to change
* Select the IPv4 Tab, and change the IPv4 method to Manual
* Under “Addresses” enter in the following:<br />
- IP Address: 192.168.137.1<br />
- Subnet Mask: 255.255.255.0
* You can leave Gateway and DNS blank

[[File:Ubuntustaticip.png|thumb|none|alt=|The IPv4 configuration screen in Ubuntu 18.10]]
</div>

== Setting a static IP on the Pi ==
To set a static IP on the Pi, you have multiple options. You can do it before first boot by addling a line to cmdline.txt on the boot partition of the SD card, or once the Pi is running by editing dhcpcd.
Before setting the static IP, ensure you have the correct subdomain, and that you don't assign an IP that another device on the network is using. If you're assinging it a static IP and you have, for example, a router acting as a DHCP server, ensure the IP you assign is outside of DHCP range.

=== From the boot partition ===
<span class="mw-customtoggle-PiStaticBoot" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-PiStaticBoot" class="mw-collapsible mw-collapsed">
<ol>
<li><p>Insert the SD card into your computer and navigate to the BOOT partition</p></li>
<li><p>Open “cmdline.txt” and append the following to the line (don’t create a new line)</p>
<pre> ip=192.168.137.15 </pre>
<p>This tells the Raspberry Pi to configure the Ethernet port to use the IP address 192.168.137.15</p></li>
<li><p>Enable SSH as per Section [sec:SSH].</p></li>
<li><p>You need to configure your PC to use the same subnet as the Pi. To do so, see the information below in the section on Assigning a static IP to the Pi.</p></li></ol>
</div>
=== In dhcpcd (while the Pi is running)===
<span class="mw-customtoggle-PiStaticDHCPCD" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-PiStaticDHCPCD" class="mw-collapsible mw-collapsed">
Once you’ve successfully SSH’d into your Pi, it’s a good idea to configure the networking options in the config files directly. You will need to set a static IP on the computer first if you are SSH'ing through an Ethernet connection.

Use a text editor such as nano to open /etc/dhcpcd.conf as sudo user, and edit it to the following:

<pre># Static IP profile for eth0
profile static_eth0
static ip_address=192.168.137.15/24
static routers=192.168.137.1
static domain_name_servers=192.168.137.1 8.8.8.8

# Ethernet interface configuration
interface eth0
fallback static_eth0

# Wireless configuration
interface wlan0
metric 200</pre>
</div>

== WiFi to Ethernet Passthrough ==
In a situation when you can't or don't want to connect to a WiFi network, but are connected to a computer through an Ethernet port There may be a situation in which you want your Pi to work as an access point rather than using the WiFi interface to provide the Pi with internet access. In this situation, you need to get internet access through the Ethernet port. Before starting, you need to ensure the computer you're using has a static IP assigned. When enabling network sharing on Windows, it automatically assigns 192.168.137.1. Once that's done, complete the following to enable network sharing:

=== Windows ===
<span class="mw-customtoggle-PassthroughWindows" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-PassthroughWindows" class="mw-collapsible mw-collapsed">
# Ensure the Pi is unplugged
# Right click on your network option in Windows taskbar
# Select “Open Network & Internet Settings”, on the lower right hand side of the screen.
# Select “Change Adapted Options”
# Right click on your WiFi network and select “Properties”
# Click the “Sharing” tab, and enable the first checkbox <ref>This setting is what forces us to have to use the subnet 192.168.137.x.</ref>
# Select the Ethernet connection that your Pi will be using in the drop down box (Usually just “Ethernet”, but may be different if there are multiple Ethernet posts on your system)

[[File:Windowspassthrough.png|thumb|none|alt=|Using WiFi to Ethernet passthrough in Windows]]
</div>
=== Ubuntu ===
<span class="mw-customtoggle-PassthroughUbuntu" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-PassthroughUbuntu" class="mw-collapsible mw-collapsed">
# Ensure the Pi is unplugged and turned off.
# Open a terminal and run <code>nm-connection-editor</code>
# Select the wired connection you’d like to share your WiFi to
# Select the IPv4 settings tab
# Under Method, select “Shared to other computers”
# under the IP addresses, click “Add” and enter in an address of 192.168.137.1, and a netmask of 24
# Select “Save”, and close the windows
# Plug in the Pi, start an SSH session and see if you can ping google.co.za

[[File:Nm-connection-editor.png|thumb|none|alt=|nm-connection-editor in Ubuntu 18.10]]
</div>

= Other Connectivity Methods =
There are ways other than WiFi and Ethernet as a means of connecting headlessly (without a keyboard and screen directly attached) to the Pi.

== TTL over USB ==

'''Note:''' The Pi uses 3.3V logic levels. Using a 5V logic module will permanently damage the pins.

This option allows you to use a USB to UART converter such as a FT232R or CP2102. Begin by removing the SD card, and insert it into a computer. Make the following changes on the boot partition:

cmdline.txt: add the following (on the same line)

<pre>console=serial0,115200 </pre>
config.txt

<pre>uart_enable=1
dtoverlay=pi3-disable-bt</pre>

== Using USB connectivity on the Pi 0/0W ==
In order to use this method on Windows you require [https://support.apple.com/kb/DL999?locale=en_US Apple Bonjour Print Services] as well as [https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html PuTTY].

With the SD card plugged into your computer, open up the boot partition and make the following changes:
<ol>
<li>Be sure to enable SSH as described at [[RaspberryPi:Networking#Enabling_SSH]]</li>
<li>At the bottom of config.txt, add the following line
<pre>dtoverlay=dwc2</pre></li>
<li>On the '''same line''' in cmdline.txt, append the following:
<pre> modules-load=dwc2,g_ether</pre></li>
</ol>

Open up a terminal window (or PuTTY if you're on Windows).
After about 90 or so seconds, you should be able to SSH in (assuming you enabled SSH on the Pi) by connecting to <code>raspberrypi.local</code>.
You may (if you're using PuTTY) get a message about keys and hashes and hosts - just click "yes".
You can then log in with the username "pi" and the password "raspberry".

=== Internet Access over USB ===
In order to provide the Pi with internet access, you need to do the following:
<ol>
<li> Share your computer's connection with the Pi as you have done in the "WiFi to Ethernet Passthrough" section above. You will be sharing your regular connection with an Ethernet connection, as that is how the Pi 0 has been set up. In the test I ran <li>
# On the Pi, you need to configure DHCPCD to have usb0 use a static IP of 192.168.137.x. The rest of this wiki has been written with x=15
# SSH in using "raspberrypi.local" as the address to connect to
# Run <code> sudo nano /etc/dhcpcd.conf</code>, scroll to the bottom, and add the following:
<pre>
interface usb0
static ip_address=192.168.137.15
static router = 192.168.137.1
static domain_name_servers=192.168.137.1 8.8.8.8
</pre>
# Save and close the file
# Run the command <code> sudo route add default gw 192.168.137.1 </code>
# Reboot the Pi
# SSH in again. You should be able to ssh in using "192.168.137.15" now, as well as "raspberrypi.local"
# To test connectivity, try pinging google.com. You should get a valid response back.
</ol>

= Ensuring Connectivity =

Sometimes you may want to debug your connection to the Pi. A fast way to do this is via the ''ping'' command. ''Ping'' sends a packet to a particular host (in this case the Pi), and measures the time taken for a response from that host.

To use the ping command, open a command prompt window or terminal and type the following:

<pre>$ ping 192.168.137.15</pre>
If that host is unreachable (the Pi hasn’t booted yet or is incorrectly configured), a message will show that the host is unreachable. If everything was correctly configured, you should get

<pre>Reply from 192.168.137.15: bytes=32 time<1ns TTL=64</pre>
This means your Pi and computer are both correctly configured. See section [sec:SSH] for configuring your Pi for SSH access.

'''NB:''' Don’t be surprised if you can’t ping a Windows machine from your Pi. Windows blocks the specific type of packet required for a ping in the firewall.

= Networking Protocols=
For a more detailed overview on useful networking protocols, see [[Network Protocols]]
== SSH ==

=== Enabling SSH ===

If you have not connected to your Pi and configured it for SSH, you need to do so. SSH is disabled by default on new installations of Raspbian.

To enable SSH, add it as an enabled service in the <code>raspi-config</code> menu. If you do not have access to the Pi as yet, do the following:

# Insert the SD card into a computer
# Navigate to the BOOT partition
# Create a file called “ssh”. <strong>Note there is no file extension!</strong>
# Your Pi will enable SSH upon next boot

=== Using SSH ===

To use SSH on your Pi, you need to connect to the computer to a network. See Section [sec:NetworkingOnThePi] on various ways that can be done (it is suggested to use Ethernet upon first connection).

Once your Pi is connected to the computer and you have ensured connection (see Section [sec:Connectivity-EnsuringConnectivity]), use can log in to your Pi via SSH. If you are on a Linux-based system, such as Ubuntu or Mac, you should be able to run the following. Note that the default username is “pi” and the default password is “raspberry”.

<pre>$ ssh <username>@192.168.137.15</pre>
If you are on Windows, you may need to use PuTTY. Some instances of windows have SSH in the command line, and you can run the command shown above. But if not, you will need to do the following:

# Open PuTTY
# In the “Hostname” field, enter in “192.168.137.15”
# Click “Open”. A terminal window will be opened. If it is the first time you’re SSH’ing into your Pi on this particular computer, you will be asked about the server fingerprint. Click “Yes” to continue.
# You will be asked for a username and password. The default username is “pi” and the password is “raspberry”.
# You should now successfully connected to your Raspberry Pi via SSH

== VNC ==
To learn about how to install VNC, see
# Ensure the VNC service is enabled on the Pi

#Connect to the Pi through VNC.
# Set your preferred resolution for Raspbian
## In the desktop menu, go to Preferences - Raspberry Pi Configuration and click the “Set Resolution” button.
## Select a more appropriate resolution (1280*720 suggested)
## Select “Okay” and then “Okay”. You will be asked to reboot your Pi, do so.
# Set the VNC resolution
## Through editing /boot/config.txt, uncomment the following lines relating to framebuffer_width and framebuffer_height
## On the desktop on VNC, use the settings. Do this if you have already connected to VNC. This is a little more difficult as it required you to play with windows in order to see the buttons you need.

RaspberryPi:Installation

2020-09-04T11:10:53Z

CRNKEE002: /* Overview */

[[Category:RaspberryPi]]
= Overview =
In order to use the Pi you need to install an operating system on it and set up networking. You will then configure the networking settings on your Pi to allow you to access the Pi using SSH.

This process will follow headless installation, as we are going to assume most students do not have access to spare screens, keyboards and mouses for the Pi. Headless mode on the Raspberry Pi refers to using it without direct user input and output (essentially no screen, mouse or keyboard connected directly to it).

The instructions below may seem complicated, but configuring any Raspberry Pi consists of the same basic steps:

# Flash the SD Card
# Edit the configs to get headless access
# Complete first boot
# Enable configs for other connectivity

= Prerequisites =
== Software Requirements ==
'''Note''': Recently, the Pi Foundation released an imager tool which can be run from multiple operating systems and also has support for a selection of operating systems which can be installed on the Raspberry Pi. you can downlaod this tool from [https://www.raspberrypi.org/downloads/ here]. It will automatically download the selected operating system for your Raspberry Pi too, or allow you to select one you have already downloaded and have stored on local storage.

If you'd prefer not to use the Pi Foundation imager, you'll need the following tools:
* An operating system image. It's recommended you use [https://www.raspberrypi.org/downloads/raspberry-pi-os/ Raspberry Pi OS]. You can read more about operating systems for the Pi on [http://wiki.ee.uct.ac.za/RaspberryPi:Overview#OperatingSystems this page]
* Something to allow you to SSH in to your Pi. On Windows you can use [http://wiki.ee.uct.ac.za/PuTTY PuTTY] or [http://wiki.ee.uct.ac.za/Windows_Subsystem_for_Linux WSL]
* On Windows, you will need an [https://www.sdcard.org/downloads/formatter\_4/eula\_windows/index.html SD Card Formatter]
* On Windows, you will require software to burn the image. [https://www.balena.io/etcher/ Balena Etcher] is recommended.

== Hardware Requirements ==
{| class="wikitable"
|- style="font-weight:bold;"
! All Pi's
! Pi 0/0W
! Other
|-
| Micro SD Card
| Micro USB cable
| Ethernet Cable
|-
| Micro SD Card Reader
|
| 3A or greater power micro USB power supply
|-
| Computer with USB port
|
|
|}

= Installation =
Using a Raspberry Pi for the first time can be intimidating, but over time (and countless flashing of software) you will realise it's quite easy! In general, it consists of the following steps:
# Install the operating system
# Adjust configuration for the first boot
# Upon first boot, validate settings and update any other configurations

== Using the Pi Imager ==
<ol>
<li>Plug your SD card in to your machine.</li>
<li>Select your image, select the correct SD card, and select "Write". </li>
<li>The tool will process the image and write it to the SD card.</li>
</ol>
== Using seperate tools ==
<ol>
<li> Preparing the SD Card </br>
Plug your SD card in to your machine and format it. On Windows, this can be done using the SD Card Formatter linked in the Software Requirements section. </li>

<li> Burn the image to the SD card </br>
Open Etcher. Select the downloaded zip image, and the SD card, and format. At the end of format, it may read that it failed, but don’t worry. <strong>Ignore the Windows popups about needing to format the SD card.</strong> Upon completion, Windows will try to mount partitions on the SD card that it can’t read. Just press “Cancel” and then “OK” to the dialog boxes that pop up. The boot partition is the only partition we will be dealing with. </li>
</ol>

= Enabling Connectivity =
The form of connectivity you use depends on the Raspberry Pi you are using. However, there are some steps which are applicable to all Raspberry Pis.
Before starting, disconnect and reconnect the SD card to ensure it is mounted correctly.
== SSH ==
<ol>
<li> Open the partition called "boot"
<li> Create a file '''without a file extension''' called "ssh".</li>
<ul>
<li> To show file extensions on Windows, click "View" and then "File name extensions".
</ul>
</ol>

More information on the general use of SSH can be found in [[Network Protocols]].

== Configure Networking ==
Which network connectivity you decide to enable is up to your use case and the the Raspberry Pi model you're using. However, we'll cover the basics for general WiFi, Ethernet over USB for the Pi Zero, and Ethernet on other Pi models. To learn more about connectivity on the Pi, read through [[RaspberryPi:Networking]].
=== General Wifi Connectivity ===
You can enable WiFi connectivity before first boot by adding a wpa_supplicant file to the boot partition.
Simply open the boot partition and create a file called <code>wpa_supplicant.conf</code>. The contents would be the same as described at [[RaspberryPi:Networking]]

If you've already got access to the Pi, you can run <code>sudo raspi-config</code> to configure wifi through command prompts.

For details on connecting the Pi to Eduroam, visit [[RaspberryPi:AdvancedConnectivity]]

=== Static IP for Pi with Ethernet ===
When using an Ethernet connection, it can be beneficial to assign a static IP to the Ethernet port on the Pi. This however requires knowledge of subnets and IP addresses. For information on this, see [[RaspberryPi:AdvancedConnectivity#Static_IPs]]

=== SSH over USB for Pi 0/0W ===
When using a Pi 0 or 0W, using the on-board USB as a connection for SSH is very useful. It means just a single port is required for all access to the Pi, so long as you're not doing anything that requires too much current. To see details on setting up Ethernet over USB on the Raspberry Pi, visit [[RaspberryPi:Networking#Using_USB_connectivity_on_the_Pi_0.2F0W]].

= First Boot =
<li>Boot<br>
Insert the SD Card into the Pi, and power it on.</li>

<li>Ensure Connectivity <br>
Try and ping the Pi's static IP, or view COM Port connections if you are using the Pi Zero Serial option. For example, <br>
<pre>$ ping 192.168.137.15</pre>
You should see a response similar to
<pre> $ 64 bytes from 192.168.137.15: icmp_seq=1 ttl=64 time=0.557 ms</pre>
or
<pre> $ Reply from 192.168.137.15 bytes=32 time=0.5ms TTL=52</pre></li>

<li> SSH In to your Pi <br>
<pre> $ ssh pi@192.168.137.15</pre>
You will be asked to add the machine to known hosts. Select yes. The default password for Raspbian is simply "raspberry".
</li>

<li>Change your password<br>
To change your password, you can simply run <pre>$ passwd </pre></li>

<li>Enable Services <br>
It's a good idea to enable useful services on the Pi.
<ol>
<li>On your Pi, run <pre> $ sudo raspi-config</pre></li>
<li>Use the arrow keys and scroll down to "Interfacing Options"</li>
<li>If not enabled, enable SSH, VNC, SPI, I2C and Serial</li>
<li>Save and exit raspi-config by using the left and right arrow keys to jump to the bottom buttons. Your Pi will reboot.</li>
</ol>
</li>

<li>Expand the Filesystem <br>
The Rasberry Pi Installation may not make use of the full SD card. In order to give yourself as much file space as you have access to, you need to expand the filesystem.
<ol>
<li>SSH into the Pi</li>
<li>Run <pre> $ sudo raspi-config </pre></li>
<li>Use the arrow keys and scroll down to “Advanced Options</li>
<li>Select "Expand Filesystem"</li>
<li>You will be shown a message saying that the root partition has been resized. Select “Ok”, then “Finish” then “Yes” to reboot your Pi.</li>
</ol>
</li>
</ol>

= More detailed Information =
If you need more detailed information on how to configure the SD card when using a different operating system (such as Mac), visit the [https://www.raspberrypi.org/documentation/installation/installing-images/README.md Raspberry Pi Website]

RaspberryPi:Installation

2020-09-04T11:00:58Z

CRNKEE002: /* Hardware Requirements */

[[Category:RaspberryPi]]
= Overview =
In order to use the Pi you need to install an operating system on it and set up networking. You will then configure the networking settings on your Pi to allow you to access the Pi using SSH.

This process will follow headless installation, as we are going to assume most students do not have access to spare screens, keyboards and mouses for the Pi. Headless mode on the Raspberry Pi refers to using it without direct user input and output (essentially no screen, mouse or keyboard connected directly to it).

= Prerequisites =
== Software Requirements ==
'''Note''': Recently, the Pi Foundation released an imager tool which can be run from multiple operating systems and also has support for a selection of operating systems which can be installed on the Raspberry Pi. you can downlaod this tool from [https://www.raspberrypi.org/downloads/ here]. It will automatically download the selected operating system for your Raspberry Pi too, or allow you to select one you have already downloaded and have stored on local storage.

If you'd prefer not to use the Pi Foundation imager, you'll need the following tools:
* An operating system image. It's recommended you use [https://www.raspberrypi.org/downloads/raspberry-pi-os/ Raspberry Pi OS]. You can read more about operating systems for the Pi on [http://wiki.ee.uct.ac.za/RaspberryPi:Overview#OperatingSystems this page]
* Something to allow you to SSH in to your Pi. On Windows you can use [http://wiki.ee.uct.ac.za/PuTTY PuTTY] or [http://wiki.ee.uct.ac.za/Windows_Subsystem_for_Linux WSL]
* On Windows, you will need an [https://www.sdcard.org/downloads/formatter\_4/eula\_windows/index.html SD Card Formatter]
* On Windows, you will require software to burn the image. [https://www.balena.io/etcher/ Balena Etcher] is recommended.

== Hardware Requirements ==
{| class="wikitable"
|- style="font-weight:bold;"
! All Pi's
! Pi 0/0W
! Other
|-
| Micro SD Card
| Micro USB cable
| Ethernet Cable
|-
| Micro SD Card Reader
|
| 3A or greater power micro USB power supply
|-
| Computer with USB port
|
|
|}

= Installation =
Using a Raspberry Pi for the first time can be intimidating, but over time (and countless flashing of software) you will realise it's quite easy! In general, it consists of the following steps:
# Install the operating system
# Adjust configuration for the first boot
# Upon first boot, validate settings and update any other configurations

== Using the Pi Imager ==
<ol>
<li>Plug your SD card in to your machine.</li>
<li>Select your image, select the correct SD card, and select "Write". </li>
<li>The tool will process the image and write it to the SD card.</li>
</ol>
== Using seperate tools ==
<ol>
<li> Preparing the SD Card </br>
Plug your SD card in to your machine and format it. On Windows, this can be done using the SD Card Formatter linked in the Software Requirements section. </li>

<li> Burn the image to the SD card </br>
Open Etcher. Select the downloaded zip image, and the SD card, and format. At the end of format, it may read that it failed, but don’t worry. <strong>Ignore the Windows popups about needing to format the SD card.</strong> Upon completion, Windows will try to mount partitions on the SD card that it can’t read. Just press “Cancel” and then “OK” to the dialog boxes that pop up. The boot partition is the only partition we will be dealing with. </li>
</ol>

= Enabling Connectivity =
The form of connectivity you use depends on the Raspberry Pi you are using. However, there are some steps which are applicable to all Raspberry Pis.
Before starting, disconnect and reconnect the SD card to ensure it is mounted correctly.
== SSH ==
<ol>
<li> Open the partition called "boot"
<li> Create a file '''without a file extension''' called "ssh".</li>
<ul>
<li> To show file extensions on Windows, click "View" and then "File name extensions".
</ul>
</ol>

More information on the general use of SSH can be found in [[Network Protocols]].

== Configure Networking ==
Which network connectivity you decide to enable is up to your use case and the the Raspberry Pi model you're using. However, we'll cover the basics for general WiFi, Ethernet over USB for the Pi Zero, and Ethernet on other Pi models. To learn more about connectivity on the Pi, read through [[RaspberryPi:Networking]].
=== General Wifi Connectivity ===
You can enable WiFi connectivity before first boot by adding a wpa_supplicant file to the boot partition.
Simply open the boot partition and create a file called <code>wpa_supplicant.conf</code>. The contents would be the same as described at [[RaspberryPi:Networking]]

If you've already got access to the Pi, you can run <code>sudo raspi-config</code> to configure wifi through command prompts.

For details on connecting the Pi to Eduroam, visit [[RaspberryPi:AdvancedConnectivity]]

=== Static IP for Pi with Ethernet ===
When using an Ethernet connection, it can be beneficial to assign a static IP to the Ethernet port on the Pi. This however requires knowledge of subnets and IP addresses. For information on this, see [[RaspberryPi:AdvancedConnectivity#Static_IPs]]

=== SSH over USB for Pi 0/0W ===
When using a Pi 0 or 0W, using the on-board USB as a connection for SSH is very useful. It means just a single port is required for all access to the Pi, so long as you're not doing anything that requires too much current. To see details on setting up Ethernet over USB on the Raspberry Pi, visit [[RaspberryPi:Networking#Using_USB_connectivity_on_the_Pi_0.2F0W]].

= First Boot =
<li>Boot<br>
Insert the SD Card into the Pi, and power it on.</li>

<li>Ensure Connectivity <br>
Try and ping the Pi's static IP, or view COM Port connections if you are using the Pi Zero Serial option. For example, <br>
<pre>$ ping 192.168.137.15</pre>
You should see a response similar to
<pre> $ 64 bytes from 192.168.137.15: icmp_seq=1 ttl=64 time=0.557 ms</pre>
or
<pre> $ Reply from 192.168.137.15 bytes=32 time=0.5ms TTL=52</pre></li>

<li> SSH In to your Pi <br>
<pre> $ ssh pi@192.168.137.15</pre>
You will be asked to add the machine to known hosts. Select yes. The default password for Raspbian is simply "raspberry".
</li>

<li>Change your password<br>
To change your password, you can simply run <pre>$ passwd </pre></li>

<li>Enable Services <br>
It's a good idea to enable useful services on the Pi.
<ol>
<li>On your Pi, run <pre> $ sudo raspi-config</pre></li>
<li>Use the arrow keys and scroll down to "Interfacing Options"</li>
<li>If not enabled, enable SSH, VNC, SPI, I2C and Serial</li>
<li>Save and exit raspi-config by using the left and right arrow keys to jump to the bottom buttons. Your Pi will reboot.</li>
</ol>
</li>

<li>Expand the Filesystem <br>
The Rasberry Pi Installation may not make use of the full SD card. In order to give yourself as much file space as you have access to, you need to expand the filesystem.
<ol>
<li>SSH into the Pi</li>
<li>Run <pre> $ sudo raspi-config </pre></li>
<li>Use the arrow keys and scroll down to “Advanced Options</li>
<li>Select "Expand Filesystem"</li>
<li>You will be shown a message saying that the root partition has been resized. Select “Ok”, then “Finish” then “Yes” to reboot your Pi.</li>
</ol>
</li>
</ol>

= More detailed Information =
If you need more detailed information on how to configure the SD card when using a different operating system (such as Mac), visit the [https://www.raspberrypi.org/documentation/installation/installing-images/README.md Raspberry Pi Website]

Unix Shell (Terminal)

2020-09-04T10:55:18Z

CRNKEE002: /* Useful Commands */

[[Category:Software]]
= Overview =
Being able to use the Unix Shell and terminal commands is an invaluable skill, and a requirement for this course. Follow [https://swcarpentry.github.io/shell-novice/ this software carpentry link] for more learning resources.

= Useful Commands =

{| class="wikitable"
|- style="font-weight:bold;"
! Command
! Description
|-
| ls
| List current files and folders in directory
|-
| ls -al
| List details about everything
|-
| pwd
| Print current (working) directory
|-
| cd <directory>
| Move into the specified directory
|-
| cd ..
| Move up one directory
|-
| ifconfig
| Shows details on current network interfaces (requires package net-tools to be installed)
|-
| touch <file>
| Creates a file. For example "touch.txt" will create a file in the directory you are in.
|-
| nano <file>
| Opens the specified file in nano, a text editor
|-
| mkdir <directory>
| Creates a directory
|-
| sudo <command>
| Executes <command> with super user privilages
|-
| man <command>
| Opens the user manual relating to the specified command
|}

[[File:CMDOutput.png|frame|none|An example output of running some commands in the shell on a Raspberry Pi 3b+]]

= Aliases =
Sometimes you may want to run long or complex commands. In this scenario, it can be useful to create an alias. This allows you to rename a command (or chain of commands) to an easier to type or remember command. An alias is a sort of shortcut, and it can be temporary or permanent.

For example, the command <code>vcgencmd measure_temp</code> on a Raspberry Pi will return the core temperature. However, this can be a tricky command to remember. So, let's create an alias.
For a temporary alias, you can just enter in <code>alias temp="vcgencmd measure_temp"</code> on the command line. This will allow you to type "temp" and get the temperature. However, this alias will expire when you end your session (log out). To create a permanent alias, the following is required.

# Open .bash_profile: <code>nano ~/.bash_profile</code>
# Add a line for the alias: <code>alias temp="vcgencmd measure_temp"</code>
# Save and close the file
# Reload .bash_profile: <code>source ~/.bash_profile</code>

RaspberryPi:Installation

2020-09-01T08:51:15Z

CRNKEE002: /* General Wifi Connectivity */

[[Category:RaspberryPi]]
= Overview =
In order to use the Pi you need to install an operating system on it and set up networking. You will then configure the networking settings on your Pi to allow you to access the Pi using SSH.

This process will follow headless installation, as we are going to assume most students do not have access to spare screens, keyboards and mouses for the Pi. Headless mode on the Raspberry Pi refers to using it without direct user input and output (essentially no screen, mouse or keyboard connected directly to it).

= Prerequisites =
== Software Requirements ==
'''Note''': Recently, the Pi Foundation released an imager tool which can be run from multiple operating systems and also has support for a selection of operating systems which can be installed on the Raspberry Pi. you can downlaod this tool from [https://www.raspberrypi.org/downloads/ here]. It will automatically download the selected operating system for your Raspberry Pi too, or allow you to select one you have already downloaded and have stored on local storage.

If you'd prefer not to use the Pi Foundation imager, you'll need the following tools:
* An operating system image. It's recommended you use [https://www.raspberrypi.org/downloads/raspberry-pi-os/ Raspberry Pi OS]. You can read more about operating systems for the Pi on [http://wiki.ee.uct.ac.za/RaspberryPi:Overview#OperatingSystems this page]
* Something to allow you to SSH in to your Pi. On Windows you can use [http://wiki.ee.uct.ac.za/PuTTY PuTTY] or [http://wiki.ee.uct.ac.za/Windows_Subsystem_for_Linux WSL]
* On Windows, you will need an [https://www.sdcard.org/downloads/formatter\_4/eula\_windows/index.html SD Card Formatter]
* On Windows, you will require software to burn the image. [https://www.balena.io/etcher/ Balena Etcher] is recommended.

== Hardware Requirements ==
{| class="wikitable"
|- style="font-weight:bold;"
! All Pi's
! Pi 0/0W
! Other (greater current requirements)
|-
| Micro SD Card
| Micro USB cable
| Ethernet Cable
|-
| Micro SD Card Reader
|
| 3A or greater power micro USB power supply
|-
| Computer with USB port
|
|
|}

= Installation =
Using a Raspberry Pi for the first time can be intimidating, but over time (and countless flashing of software) you will realise it's quite easy! In general, it consists of the following steps:
# Install the operating system
# Adjust configuration for the first boot
# Upon first boot, validate settings and update any other configurations

== Using the Pi Imager ==
<ol>
<li>Plug your SD card in to your machine.</li>
<li>Select your image, select the correct SD card, and select "Write". </li>
<li>The tool will process the image and write it to the SD card.</li>
</ol>
== Using seperate tools ==
<ol>
<li> Preparing the SD Card </br>
Plug your SD card in to your machine and format it. On Windows, this can be done using the SD Card Formatter linked in the Software Requirements section. </li>

<li> Burn the image to the SD card </br>
Open Etcher. Select the downloaded zip image, and the SD card, and format. At the end of format, it may read that it failed, but don’t worry. <strong>Ignore the Windows popups about needing to format the SD card.</strong> Upon completion, Windows will try to mount partitions on the SD card that it can’t read. Just press “Cancel” and then “OK” to the dialog boxes that pop up. The boot partition is the only partition we will be dealing with. </li>
</ol>

= Enabling Connectivity =
The form of connectivity you use depends on the Raspberry Pi you are using. However, there are some steps which are applicable to all Raspberry Pis.
Before starting, disconnect and reconnect the SD card to ensure it is mounted correctly.
== SSH ==
<ol>
<li> Open the partition called "boot"
<li> Create a file '''without a file extension''' called "ssh".</li>
<ul>
<li> To show file extensions on Windows, click "View" and then "File name extensions".
</ul>
</ol>

More information on the general use of SSH can be found in [[Network Protocols]].

== Configure Networking ==
Which network connectivity you decide to enable is up to your use case and the the Raspberry Pi model you're using. However, we'll cover the basics for general WiFi, Ethernet over USB for the Pi Zero, and Ethernet on other Pi models. To learn more about connectivity on the Pi, read through [[RaspberryPi:Networking]].
=== General Wifi Connectivity ===
You can enable WiFi connectivity before first boot by adding a wpa_supplicant file to the boot partition.
Simply open the boot partition and create a file called <code>wpa_supplicant.conf</code>. The contents would be the same as described at [[RaspberryPi:Networking]]

If you've already got access to the Pi, you can run <code>sudo raspi-config</code> to configure wifi through command prompts.

For details on connecting the Pi to Eduroam, visit [[RaspberryPi:AdvancedConnectivity]]

=== Static IP for Pi with Ethernet ===
When using an Ethernet connection, it can be beneficial to assign a static IP to the Ethernet port on the Pi. This however requires knowledge of subnets and IP addresses. For information on this, see [[RaspberryPi:AdvancedConnectivity#Static_IPs]]

=== SSH over USB for Pi 0/0W ===
When using a Pi 0 or 0W, using the on-board USB as a connection for SSH is very useful. It means just a single port is required for all access to the Pi, so long as you're not doing anything that requires too much current. To see details on setting up Ethernet over USB on the Raspberry Pi, visit [[RaspberryPi:Networking#Using_USB_connectivity_on_the_Pi_0.2F0W]].

= First Boot =
<li>Boot<br>
Insert the SD Card into the Pi, and power it on.</li>

<li>Ensure Connectivity <br>
Try and ping the Pi's static IP, or view COM Port connections if you are using the Pi Zero Serial option. For example, <br>
<pre>$ ping 192.168.137.15</pre>
You should see a response similar to
<pre> $ 64 bytes from 192.168.137.15: icmp_seq=1 ttl=64 time=0.557 ms</pre>
or
<pre> $ Reply from 192.168.137.15 bytes=32 time=0.5ms TTL=52</pre></li>

<li> SSH In to your Pi <br>
<pre> $ ssh pi@192.168.137.15</pre>
You will be asked to add the machine to known hosts. Select yes. The default password for Raspbian is simply "raspberry".
</li>

<li>Change your password<br>
To change your password, you can simply run <pre>$ passwd </pre></li>

<li>Enable Services <br>
It's a good idea to enable useful services on the Pi.
<ol>
<li>On your Pi, run <pre> $ sudo raspi-config</pre></li>
<li>Use the arrow keys and scroll down to "Interfacing Options"</li>
<li>If not enabled, enable SSH, VNC, SPI, I2C and Serial</li>
<li>Save and exit raspi-config by using the left and right arrow keys to jump to the bottom buttons. Your Pi will reboot.</li>
</ol>
</li>

<li>Expand the Filesystem <br>
The Rasberry Pi Installation may not make use of the full SD card. In order to give yourself as much file space as you have access to, you need to expand the filesystem.
<ol>
<li>SSH into the Pi</li>
<li>Run <pre> $ sudo raspi-config </pre></li>
<li>Use the arrow keys and scroll down to “Advanced Options</li>
<li>Select "Expand Filesystem"</li>
<li>You will be shown a message saying that the root partition has been resized. Select “Ok”, then “Finish” then “Yes” to reboot your Pi.</li>
</ol>
</li>
</ol>

= More detailed Information =
If you need more detailed information on how to configure the SD card when using a different operating system (such as Mac), visit the [https://www.raspberrypi.org/documentation/installation/installing-images/README.md Raspberry Pi Website]

HDL Simulation

2020-08-28T07:11:05Z

CRNKEE002: /* iVerilog */

[[Category: FPGAs]]
[[Category: Software]]

When creating HDL designs, simulation can be used to verify your logic (behavioral simulation) or ensure you meet timing constraints (timing simulation). This page covers some useful information on writing testbenches, as well simulators that are used in the department (and in some cases, instructions on how to use them). While there are of course many simulators, the ones below are used by academics, staff and researchers in the department.

= Testbenches =
Testbenches in HDL are modules that instantiate other modules.

= Testbenches in Verilog =
Testbenches in Verilog are simply modules that instantiate the DUT, control the inputs, and monitor the outputs accordingly. They usually contain a single DUT, an initial block to set starting conditions, and an always block to run the testbench. The general approach for a DUT is to use registers for inputs and wires for outputs. Of course there is much more to testbenches than that, but that is the short of it.

For example, take a module called ModuleToTest that is meant to display switch values on LEDs:
<pre>
`timescale 1ns / 1ps // Set time and precision

module testbench();

// Define our inputs and outputs
reg clk;
reg [3:0] switches;
wire [7:0] leds;

// Instantiate the device under test
ModuleToTest DUT(clk, switches, leds);

// Set initial conditions
initial
begin
clk <= 1;
switches <= 0;
end

//toggle the clock
always begin
#5 clk = ~clk;
end

endmodule
</pre>

== Verilog Testbench Directives ==
Verilog directives allow you to do things which are not usually possible in hardware, only through simulation. This includes printing data to a screen, loading data from a text file, or stopping the simulation.

For a quick reference list of commands, see [http://www.techsystemsembedded.com/verilog_testbench.php this link].

= Available Simulators =
The following is a collection of some HDL simulators used in the department.
== iVerilog ==
See [http://www.referencedesigner.com/tutorials/verilog/verilog_02.php this link] for a tutorial on iVerilog.

== EDAPlayground ==

== Vivado ==
The Vivado Simulator comes as a part of the Vivado IDE. For details on the Vivado IDE, see [[Xilinx Vivado]]. For details specific to Vivado, you can find a video on simulation [https://www.youtube.com/watch?v=Cb5LRi5scMw here].

Once you begin writing your modules you need to check that they’re working. You can do this through simulation.

Once you’ve synthesized your project, you should be able to click “Run simulation”.

This will only run a simulation of your top module. It is far more useful to create a testbench.

<ol>
<li>Right click "Simulation Sources" and Select "Add new" <br>
In the dialog box, ensure Simulation sources is selected.
</li>

<li>Create it in a new simulation set, and use the checkbox to set it as active<br>
You can toggle which simulation source is active by setting it in the same way you'd set your top level module under design sources - just right click on the simulation source and select "Make active"
</li>

<li>Create a file for your testbench<br>
It's a good idea to name it the same as the module you're testing, followed by a "_tb" to distinguish it. For example, if you're creating a test bench for a clock, you might call the file "clock_tb". This file will appear under "non module sources" in the simulation set until you add some code to it.
</li>

<li>Add basic TB code to the modele<br>
A super simple testbench consists of a generated clock and an instantiation of the module you're testing. Add the simple clock generation code, save the file, and set it as top in the simulation source. See the example above.

</li>

<li>You should now be able to instantiate modules and run behavioral simulations to ensure your design works. You can connect the modules in such a way to minic switches by setting register values and using delay constructs.
</li>

</ol>

RaspberryPi:Installation

2020-08-24T23:52:44Z

CRNKEE002: /* SSH over USB for Pi 0/0W */

[[Category:RaspberryPi]]
= Overview =
In order to use the Pi you need to install an operating system on it and set up networking. You will then configure the networking settings on your Pi to allow you to access the Pi using SSH.

This process will follow headless installation, as we are going to assume most students do not have access to spare screens, keyboards and mouses for the Pi. Headless mode on the Raspberry Pi refers to using it without direct user input and output (essentially no screen, mouse or keyboard connected directly to it).

= Prerequisites =
== Software Requirements ==
'''Note''': Recently, the Pi Foundation released an imager tool which can be run from multiple operating systems and also has support for a selection of operating systems which can be installed on the Raspberry Pi. you can downlaod this tool from [https://www.raspberrypi.org/downloads/ here]. It will automatically download the selected operating system for your Raspberry Pi too, or allow you to select one you have already downloaded and have stored on local storage.

If you'd prefer not to use the Pi Foundation imager, you'll need the following tools:
* An operating system image. It's recommended you use [https://www.raspberrypi.org/downloads/raspberry-pi-os/ Raspberry Pi OS]. You can read more about operating systems for the Pi on [http://wiki.ee.uct.ac.za/RaspberryPi:Overview#OperatingSystems this page]
* Something to allow you to SSH in to your Pi. On Windows you can use [http://wiki.ee.uct.ac.za/PuTTY PuTTY] or [http://wiki.ee.uct.ac.za/Windows_Subsystem_for_Linux WSL]
* On Windows, you will need an [https://www.sdcard.org/downloads/formatter\_4/eula\_windows/index.html SD Card Formatter]
* On Windows, you will require software to burn the image. [https://www.balena.io/etcher/ Balena Etcher] is recommended.

== Hardware Requirements ==
{| class="wikitable"
|- style="font-weight:bold;"
! All Pi's
! Pi 0/0W
! Other (greater current requirements)
|-
| Micro SD Card
| Micro USB cable
| Ethernet Cable
|-
| Micro SD Card Reader
|
| 3A or greater power micro USB power supply
|-
| Computer with USB port
|
|
|}

= Installation =
Using a Raspberry Pi for the first time can be intimidating, but over time (and countless flashing of software) you will realise it's quite easy! In general, it consists of the following steps:
# Install the operating system
# Adjust configuration for the first boot
# Upon first boot, validate settings and update any other configurations

== Using the Pi Imager ==
<ol>
<li>Plug your SD card in to your machine.</li>
<li>Select your image, select the correct SD card, and select "Write". </li>
<li>The tool will process the image and write it to the SD card.</li>
</ol>
== Using seperate tools ==
<ol>
<li> Preparing the SD Card </br>
Plug your SD card in to your machine and format it. On Windows, this can be done using the SD Card Formatter linked in the Software Requirements section. </li>

<li> Burn the image to the SD card </br>
Open Etcher. Select the downloaded zip image, and the SD card, and format. At the end of format, it may read that it failed, but don’t worry. <strong>Ignore the Windows popups about needing to format the SD card.</strong> Upon completion, Windows will try to mount partitions on the SD card that it can’t read. Just press “Cancel” and then “OK” to the dialog boxes that pop up. The boot partition is the only partition we will be dealing with. </li>
</ol>

= Enabling Connectivity =
The form of connectivity you use depends on the Raspberry Pi you are using. However, there are some steps which are applicable to all Raspberry Pis.
Before starting, disconnect and reconnect the SD card to ensure it is mounted correctly.
== SSH ==
<ol>
<li> Open the partition called "boot"
<li> Create a file '''without a file extension''' called "ssh".</li>
<ul>
<li> To show file extensions on Windows, click "View" and then "File name extensions".
</ul>
</ol>

More information on the general use of SSH can be found in [[Network Protocols]].

== Configure Networking ==
Which network connectivity you decide to enable is up to your use case and the the Raspberry Pi model you're using. However, we'll cover the basics for general WiFi, Ethernet over USB for the Pi Zero, and Ethernet on other Pi models. To learn more about connectivity on the Pi, read through [[RaspberryPi:Networking]].
=== General Wifi Connectivity ===
You can enable WiFi connectivity before first boot by adding a wpa_supplicant file to the boot partition.
Simply open the boot partition and create a file called <code>wpa_supplicant.conf</code>. The contents would be the same as described at

For details on connecting the Pi to Eduroam, visit [[RaspberryPi:AdvancedConnectivity]]

=== Static IP for Pi with Ethernet ===
When using an Ethernet connection, it can be beneficial to assign a static IP to the Ethernet port on the Pi. This however requires knowledge of subnets and IP addresses. For information on this, see [[RaspberryPi:AdvancedConnectivity#Static_IPs]]

=== SSH over USB for Pi 0/0W ===
When using a Pi 0 or 0W, using the on-board USB as a connection for SSH is very useful. It means just a single port is required for all access to the Pi, so long as you're not doing anything that requires too much current. To see details on setting up Ethernet over USB on the Raspberry Pi, visit [[RaspberryPi:Networking#Using_USB_connectivity_on_the_Pi_0.2F0W]].

= First Boot =
<li>Boot<br>
Insert the SD Card into the Pi, and power it on.</li>

<li>Ensure Connectivity <br>
Try and ping the Pi's static IP, or view COM Port connections if you are using the Pi Zero Serial option. For example, <br>
<pre>$ ping 192.168.137.15</pre>
You should see a response similar to
<pre> $ 64 bytes from 192.168.137.15: icmp_seq=1 ttl=64 time=0.557 ms</pre>
or
<pre> $ Reply from 192.168.137.15 bytes=32 time=0.5ms TTL=52</pre></li>

<li> SSH In to your Pi <br>
<pre> $ ssh pi@192.168.137.15</pre>
You will be asked to add the machine to known hosts. Select yes. The default password for Raspbian is simply "raspberry".
</li>

<li>Change your password<br>
To change your password, you can simply run <pre>$ passwd </pre></li>

<li>Enable Services <br>
It's a good idea to enable useful services on the Pi.
<ol>
<li>On your Pi, run <pre> $ sudo raspi-config</pre></li>
<li>Use the arrow keys and scroll down to "Interfacing Options"</li>
<li>If not enabled, enable SSH, VNC, SPI, I2C and Serial</li>
<li>Save and exit raspi-config by using the left and right arrow keys to jump to the bottom buttons. Your Pi will reboot.</li>
</ol>
</li>

<li>Expand the Filesystem <br>
The Rasberry Pi Installation may not make use of the full SD card. In order to give yourself as much file space as you have access to, you need to expand the filesystem.
<ol>
<li>SSH into the Pi</li>
<li>Run <pre> $ sudo raspi-config </pre></li>
<li>Use the arrow keys and scroll down to “Advanced Options</li>
<li>Select "Expand Filesystem"</li>
<li>You will be shown a message saying that the root partition has been resized. Select “Ok”, then “Finish” then “Yes” to reboot your Pi.</li>
</ol>
</li>
</ol>

= More detailed Information =
If you need more detailed information on how to configure the SD card when using a different operating system (such as Mac), visit the [https://www.raspberrypi.org/documentation/installation/installing-images/README.md Raspberry Pi Website]

RaspberryPi:Networking

2020-08-20T10:55:08Z

CRNKEE002: /* Using USB connectivity on the Pi 0/0W */

[[Category:RaspberryPi]]
There are many ways to interface with the Pi. This page will cover types of network connectivity. For more comprehensive, advanced networking details, see [[RaspberryPi:AdvancedConnectivity]].

= A Brief Overview of Networks =

It is useful to have a basic idea of how networks, IP addresses, and subnets work. For this, it it suggested you read [https://support.microsoft.com/en-za/help/164015/understanding-tcp-ip-addressing-and-subnetting-basics this article] from Microsoft.

= Wireless Connectivity =
WiFi connectivity is a useful way of connecting the Pi to the internet as it enables more portability. You can adjust WiFi Connections either before boot, by creating a <code>wpa_cupplicant.conf</code> file on the boot partition, or while the pi is running, either by editing <code>/etc/wpa/wpa_supplicant.conf</code> directly, or using <code>$ sudo raspi-config</code>. Note that the raspi-config method will not work for Eduroam.

== Simple Wifi Connections ==
If the Pi is up and running and you have access to it, you can run <code>$ sudo raspi-config</code> and enable WiFi using that menu, or editing <code>/etc/wpa/wpa_supplicant.conf</code> directly using an editor such as nano. However if you don't have access, you can create a a <code>wpa_supplicant.conf</code> file on the SD card, on the boot partition while it is plugged into another system.

If editing the wpa_supplicant configuration file, the contents should look something like the following:
<pre>
ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
update_config=1
country=ZA

network={
ssid="<Name of your WiFi network>"
psk="<Password for your WiFi network>"
}
</pre>

== Connecting to Eduroam ==
Connecting to Eduroam requires a fair amount of configuration which depends on your operating system. Generally though, edits to wpa_supplicant.conf and dhcpcd.conf are sufficient. Note that there are new releases of Raspberry Pi OS, and it is unknown if the edits for Buster are still required.

<span class="mw-customtoggle-Eduroam" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-Eduroam" class="mw-collapsible mw-collapsed">
=== Raspbian Buster ===
'''Note:''' There have been updates to the Buster code base, and roll back of wpasupplicant might not be required. However this is currently unable to be tested due to the lockdown. If someone has the chance to test, please update this page accordingly.
These instructions come from [https://www.raspberrypi.org/forums/viewtopic.php?p=1501822#p1501822 here].<br />
Unfortunately, when you use bleeding edge technology, you may end up cutting yourself. Raspbian Buster updates <code>wpa_supplicant</code> to a version that doesn’t have support for the authentication method used by Eduroam. So we need to roll back <code>wpa_supplicant</code> to an older version. Ensure your Pi has internet access through a method such as Ethernet passthrough, and run the following:

<pre>$ sudo apt-get remove wpasupplicant</pre>
Edit /etc/apt/sources.list :

<pre>$ sudo nano /etc/apt/sources.list</pre>
And change

<pre>deb http://raspbian.raspberrypi.org/raspbian/ buster main contrib non-free rpi</pre>
to

<pre>deb http://raspbian.raspberrypi.org/raspbian/ stretch main contrib non-free rpi</pre>
Run

<pre>$ sudo apt-get update
$ sudo apt-get install wpasupplicant</pre>
This will install the correct version of <code>wpa_supplicant</code>. Check that '''version 2.4''' is installed by running

<pre>$ wpa_supplicant -v</pre>
Now, change the sources file back.

<pre>$ sudo nano /etc/apt/sources.list</pre>
And edit the contents to contain

<pre>deb http://raspbian.raspberrypi.org/raspbian/ buster main contrib non-free rpi</pre>
Finally, run

<pre>$ sudo apt-get update</pre>
To update sources The correct version of <code>wpa_supplicant</code> should now be installed, and you can configure your Pi for WiFi as you would if you were using Raspbian Stretch as explained in below.

=== Raspbian Stretch ===

This section provides the instructions on how to configure the Pi to use Eduroam. It is possible to do using the GUI through VNC, but we will not cover that here.

<ol>
<li><p>SSH into your Pi.</p></li>
<li><p>Generate a hash for your password. Take note of it as it is needed in a later step</p>
<pre>
$ echo -n your_uct_password_here | iconv -t utf16le | openssl md4
</pre></li>
<li><p>Open /etc/wpa_supplicant/wpa_supplicant.conf</p>
<pre>$ sudo nano /etc/wpa_supplicant/wpa_supplicant.conf</pre></li>
<li><p>Edit it so it looks as follows:</p>
<pre>
ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
update_config=1
country=ZA

network={
ssid="eduroam"
key_mgmt=WPA-EAP
identity="studentnumber@wf.uct.ac.za"
password=hash:generated_hash_from_earlier
}
</pre></li>
<li><p>Save the file</p></li>
<li><p>Open <code>/etc/dhcpcd.conf</code></p>
<pre> $ sudo nano /etc/dhcpcd.conf</pre></li>
<li><p>Make sure the following lines are in the document:</p>
<pre>interface wlan0
metric 200
</pre></li>
<li><p>Reboot your Pi</p></li>
<li><p>WiFi Generally takes a little longer to initialize than Ethernet, so give it time. You can see if it’s ready by running</p>
<pre>$ ifconfig </pre>
<p>And seeing if an IPv4 address (“inet”) has been given.</p></li>
<li><p>Test your configuration by pinging from the WiFi interface:</p>
<pre>$ ping google.com -I wlan0</pre></li></ol>
</div>

= Ethernet Connectivity =
Ethernet is the physical connection made using a CAT 5 or 6 cable - though there are ways that Ethernet can be mimicked over USB (see Details on the Pi 0 and 0W for more information).

There are two sorts of Ethernet Connectivity we will consider. The first is just connecting the Pi to a known Ethernet network. It is simple as it requires no configuration, but it means you will need to use other methods to ensure the network allows SSH traffic and to ensure you can determine the IP of the Pi.

The second is using Ethernet passthrough from your computer to the Raspberry Pi. This leaves the WiFi free to host your own access point, and you can host services such as a Node-Red server or media center on the Pi.

If you're on a private network, connecting your Pi to a router will usually just assign it an IP address and internet connectivity automatically works. If you're on a linux-based system, like Ubuntu, you can use the hostname of the Pi to connect. By default this is "raspberrypi", so you could SSH in using "SSH pi@raspberrypi". However, in most cases, you'll want to know the IP address and assign a static IP address.

== Static IPs ==
Setting a static IP makes it easy to access the Pi and ensures that the IP address of the Pi is always known. In this course, we assign the Pi an IP address of 192.168.137.15. The reason for this is that when using Ethernet Passthrough on Windows, Windows asserts a domain of 192.168.137.x, with the host PC being assigned 192.168.137.1. Keep in mind that all devices will need to be on the same subnet though, so if you're assigning a static IP to be used on your own Ethernet network, you need to know what the subnet of that network is.

If you're connecting your Pi through your desktop, you'll need to assign a static IP to the desktop, too.

== Setting a static IP on your Desktop ==
If you're connecting your Pi through your desktop, you'll need to assign a static IP to the desktop, too. If you're setting a static IP on a Pi that's already connected directly to the network through a router or similar network switch, you can ignore setting a static IP on the computer.

=== Windows ===
<span class="mw-customtoggle-WindowsIP" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-WindowsIP" class="mw-collapsible mw-collapsed">
To change the IP of your Ethernet port on Windows 10, complete the following steps:

* Right click on your network option in Windows taskbar
* Select “Open Network & Internet Settings”, on the lower right hand side of the screen.
* Select “Change Adapted Options”
* Right click on the Ethernet Connection and select “Properties”
* Select “Internet Protocol Version 4 (TCP/IPv4) and click ”Properties"
* Select “Use the following IP address:” and enter in the following options:<br />
- IP Address: 192.168.137.1<br />
- Subnet Mask: 255.255.255.0
* You have successfully changed the IP of the Ethernet card on your computer. It is suggested that you now ensure connectivity by attempting to ping the Pi.

[[File:windowsIPConfig.png|thumb|none|alt=|The IPv4 configuration screen in Windows 10]]
</div>
=== Ubuntu ===
<span class="mw-customtoggle-UbuntuIP" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-UbuntuIP" class="mw-collapsible mw-collapsed">
To change the IP of your Ethernet port on Ubuntu, complete the following steps:

* Click the network interface icon on the status bar and select Wired Settings
* Click the gear button of the interface you’d like to change
* Select the IPv4 Tab, and change the IPv4 method to Manual
* Under “Addresses” enter in the following:<br />
- IP Address: 192.168.137.1<br />
- Subnet Mask: 255.255.255.0
* You can leave Gateway and DNS blank

[[File:Ubuntustaticip.png|thumb|none|alt=|The IPv4 configuration screen in Ubuntu 18.10]]
</div>

== Setting a static IP on the Pi ==
To set a static IP on the Pi, you have multiple options. You can do it before first boot by addling a line to cmdline.txt on the boot partition of the SD card, or once the Pi is running by editing dhcpcd.
Before setting the static IP, ensure you have the correct subdomain, and that you don't assign an IP that another device on the network is using. If you're assinging it a static IP and you have, for example, a router acting as a DHCP server, ensure the IP you assign is outside of DHCP range.

=== From the boot partition ===
<span class="mw-customtoggle-PiStaticBoot" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-PiStaticBoot" class="mw-collapsible mw-collapsed">
<ol>
<li><p>Insert the SD card into your computer and navigate to the BOOT partition</p></li>
<li><p>Open “cmdline.txt” and append the following to the line (don’t create a new line)</p>
<pre> ip=192.168.137.15 </pre>
<p>This tells the Raspberry Pi to configure the Ethernet port to use the IP address 192.168.137.15</p></li>
<li><p>Enable SSH as per Section [sec:SSH].</p></li>
<li><p>You need to configure your PC to use the same subnet as the Pi. To do so, see the information below in the section on Assigning a static IP to the Pi.</p></li></ol>
</div>
=== In dhcpcd (while the Pi is running)===
<span class="mw-customtoggle-PiStaticDHCPCD" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-PiStaticDHCPCD" class="mw-collapsible mw-collapsed">
Once you’ve successfully SSH’d into your Pi, it’s a good idea to configure the networking options in the config files directly. You will need to set a static IP on the computer first if you are SSH'ing through an Ethernet connection.

Use a text editor such as nano to open /etc/dhcpcd.conf as sudo user, and edit it to the following:

<pre># Static IP profile for eth0
profile static_eth0
static ip_address=192.168.137.15/24
static routers=192.168.137.1
static domain_name_servers=192.168.137.1 8.8.8.8

# Ethernet interface configuration
interface eth0
fallback static_eth0

# Wireless configuration
interface wlan0
metric 200</pre>
</div>

== WiFi to Ethernet Passthrough ==
In a situation when you can't or don't want to connect to a WiFi network, but are connected to a computer through an Ethernet port There may be a situation in which you want your Pi to work as an access point rather than using the WiFi interface to provide the Pi with internet access. In this situation, you need to get internet access through the Ethernet port. Before starting, you need to ensure the computer you're using has a static IP assigned. When enabling network sharing on Windows, it automatically assigns 192.168.137.1. Once that's done, complete the following to enable network sharing:

=== Windows ===
<span class="mw-customtoggle-PassthroughWindows" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-PassthroughWindows" class="mw-collapsible mw-collapsed">
# Ensure the Pi is unplugged
# Right click on your network option in Windows taskbar
# Select “Open Network & Internet Settings”, on the lower right hand side of the screen.
# Select “Change Adapted Options”
# Right click on your WiFi network and select “Properties”
# Click the “Sharing” tab, and enable the first checkbox <ref>This setting is what forces us to have to use the subnet 192.168.137.x.</ref>
# Select the Ethernet connection that your Pi will be using in the drop down box (Usually just “Ethernet”, but may be different if there are multiple Ethernet posts on your system)

[[File:Windowspassthrough.png|thumb|none|alt=|Using WiFi to Ethernet passthrough in Windows]]
</div>
=== Ubuntu ===
<span class="mw-customtoggle-PassthroughUbuntu" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-PassthroughUbuntu" class="mw-collapsible mw-collapsed">
# Ensure the Pi is unplugged and turned off.
# Open a terminal and run <code>nm-connection-editor</code>
# Select the wired connection you’d like to share your WiFi to
# Select the IPv4 settings tab
# Under Method, select “Shared to other computers”
# under the IP addresses, click “Add” and enter in an address of 192.168.137.1, and a netmask of 24
# Select “Save”, and close the windows
# Plug in the Pi, start an SSH session and see if you can ping google.co.za

[[File:Nm-connection-editor.png|thumb|none|alt=|nm-connection-editor in Ubuntu 18.10]]
</div>

= Other Connectivity Methods =
There are ways other than WiFi and Ethernet as a means of connecting headlessly (without a keyboard and screen directly attached) to the Pi.

== TTL over USB ==

'''Note:''' The Pi uses 3.3V logic levels. Using a 5V logic module will permanently damage the pins.

This option allows you to use a USB to UART converter such as a FT232R or CP2102. Begin by removing the SD card, and insert it into a computer. Make the following changes on the boot partition:

cmdline.txt: add the following (on the same line)

<pre>console=serial0,115200 </pre>
config.txt

<pre>uart_enable=1
dtoverlay=pi3-disable-bt</pre>

== Using USB connectivity on the Pi 0/0W ==
In order to use this method on Windows you require [https://support.apple.com/kb/DL999?locale=en_US Apple Bonjour Print Services] as well as [https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html PuTTY].

With the SD card plugged into your computer, open up the boot partition and make the following changes:
<ol>
<li>Be sure to enable SSH as described at [[RaspberryPi:Networking#Enabling_SSH]]</li>
<li>At the bottom of config.txt, add the following line
<pre>dtoverlay=dwc2</pre></li>
<li>On the '''same line''' in cmdline.txt, append the following:
<pre> modules-load=dwc2,g_ether</pre></li>
</ol>

Open up a terminal window (or PuTTY if you're on Windows).
After about 90 or so seconds, you should be able to SSH in (assuming you enabled SSH on the Pi) by connecting to <code>raspberrypi.local</code>.
You may (if you're using PuTTY) get a message about keys and hashes and hosts - just click "yes".
You can then log in with the username "pi" and the password "raspberry".

= Ensuring Connectivity =

Sometimes you may want to debug your connection to the Pi. A fast way to do this is via the ''ping'' command. ''Ping'' sends a packet to a particular host (in this case the Pi), and measures the time taken for a response from that host.

To use the ping command, open a command prompt window or terminal and type the following:

<pre>$ ping 192.168.137.15</pre>
If that host is unreachable (the Pi hasn’t booted yet or is incorrectly configured), a message will show that the host is unreachable. If everything was correctly configured, you should get

<pre>Reply from 192.168.137.15: bytes=32 time<1ns TTL=64</pre>
This means your Pi and computer are both correctly configured. See section [sec:SSH] for configuring your Pi for SSH access.

'''NB:''' Don’t be surprised if you can’t ping a Windows machine from your Pi. Windows blocks the specific type of packet required for a ping in the firewall.

= Networking Protocols=
For a more detailed overview on useful networking protocols, see [[Network Protocols]]
== SSH ==

=== Enabling SSH ===

If you have not connected to your Pi and configured it for SSH, you need to do so. SSH is disabled by default on new installations of Raspbian.

To enable SSH, add it as an enabled service in the <code>raspi-config</code> menu. If you do not have access to the Pi as yet, do the following:

# Insert the SD card into a computer
# Navigate to the BOOT partition
# Create a file called “ssh”. <strong>Note there is no file extension!</strong>
# Your Pi will enable SSH upon next boot

=== Using SSH ===

To use SSH on your Pi, you need to connect to the computer to a network. See Section [sec:NetworkingOnThePi] on various ways that can be done (it is suggested to use Ethernet upon first connection).

Once your Pi is connected to the computer and you have ensured connection (see Section [sec:Connectivity-EnsuringConnectivity]), use can log in to your Pi via SSH. If you are on a Linux-based system, such as Ubuntu or Mac, you should be able to run the following. Note that the default username is “pi” and the default password is “raspberry”.

<pre>$ ssh <username>@192.168.137.15</pre>
If you are on Windows, you may need to use PuTTY. Some instances of windows have SSH in the command line, and you can run the command shown above. But if not, you will need to do the following:

# Open PuTTY
# In the “Hostname” field, enter in “192.168.137.15”
# Click “Open”. A terminal window will be opened. If it is the first time you’re SSH’ing into your Pi on this particular computer, you will be asked about the server fingerprint. Click “Yes” to continue.
# You will be asked for a username and password. The default username is “pi” and the password is “raspberry”.
# You should now successfully connected to your Raspberry Pi via SSH

== VNC ==
To learn about how to install VNC, see
# Ensure the VNC service is enabled on the Pi

#Connect to the Pi through VNC.
# Set your preferred resolution for Raspbian
## In the desktop menu, go to Preferences - Raspberry Pi Configuration and click the “Set Resolution” button.
## Select a more appropriate resolution (1280*720 suggested)
## Select “Okay” and then “Okay”. You will be asked to reboot your Pi, do so.
# Set the VNC resolution
## Through editing /boot/config.txt, uncomment the following lines relating to framebuffer_width and framebuffer_height
## On the desktop on VNC, use the settings. Do this if you have already connected to VNC. This is a little more difficult as it required you to play with windows in order to see the buttons you need.

HDL Simulation

2020-08-20T10:39:10Z

CRNKEE002: /* Available Simulators */

[[Category: FPGAs]]
[[Category: Software]]

When creating HDL designs, simulation can be used to verify your logic (behavioral simulation) or ensure you meet timing constraints (timing simulation). This page covers some useful information on writing testbenches, as well simulators that are used in the department (and in some cases, instructions on how to use them). While there are of course many simulators, the ones below are used by academics, staff and researchers in the department.

= Testbenches =
Testbenches in HDL are modules that instantiate other modules.

= Testbenches in Verilog =
Testbenches in Verilog are simply modules that instantiate the DUT, control the inputs, and monitor the outputs accordingly. They usually contain a single DUT, an initial block to set starting conditions, and an always block to run the testbench. The general approach for a DUT is to use registers for inputs and wires for outputs. Of course there is much more to testbenches than that, but that is the short of it.

For example, take a module called ModuleToTest that is meant to display switch values on LEDs:
<pre>
`timescale 1ns / 1ps // Set time and precision

module testbench();

// Define our inputs and outputs
reg clk;
reg [3:0] switches;
wire [7:0] leds;

// Instantiate the device under test
ModuleToTest DUT(clk, switches, leds);

// Set initial conditions
initial
begin
clk <= 1;
switches <= 0;
end

//toggle the clock
always begin
#5 clk = ~clk;
end

endmodule
</pre>

== Verilog Testbench Directives ==
Verilog directives allow you to do things which are not usually possible in hardware, only through simulation. This includes printing data to a screen, loading data from a text file, or stopping the simulation.

For a quick reference list of commands, see [http://www.techsystemsembedded.com/verilog_testbench.php this link].

= Available Simulators =
The following is a collection of some HDL simulators used in the department.
== iVerilog ==

== EDAPlayground ==

== Vivado ==
The Vivado Simulator comes as a part of the Vivado IDE. For details on the Vivado IDE, see [[Xilinx Vivado]]. For details specific to Vivado, you can find a video on simulation [https://www.youtube.com/watch?v=Cb5LRi5scMw here].

Once you begin writing your modules you need to check that they’re working. You can do this through simulation.

Once you’ve synthesized your project, you should be able to click “Run simulation”.

This will only run a simulation of your top module. It is far more useful to create a testbench.

<ol>
<li>Right click "Simulation Sources" and Select "Add new" <br>
In the dialog box, ensure Simulation sources is selected.
</li>

<li>Create it in a new simulation set, and use the checkbox to set it as active<br>
You can toggle which simulation source is active by setting it in the same way you'd set your top level module under design sources - just right click on the simulation source and select "Make active"
</li>

<li>Create a file for your testbench<br>
It's a good idea to name it the same as the module you're testing, followed by a "_tb" to distinguish it. For example, if you're creating a test bench for a clock, you might call the file "clock_tb". This file will appear under "non module sources" in the simulation set until you add some code to it.
</li>

<li>Add basic TB code to the modele<br>
A super simple testbench consists of a generated clock and an instantiation of the module you're testing. Add the simple clock generation code, save the file, and set it as top in the simulation source. See the example above.

</li>

<li>You should now be able to instantiate modules and run behavioral simulations to ensure your design works. You can connect the modules in such a way to minic switches by setting register values and using delay constructs.
</li>

</ol>

HDL - FAQs

2020-08-19T07:53:50Z

CRNKEE002:

[[Category:FPGAs]]
As with any skill, the only way to improve and to grasp concepts is to practice. This page details some perspectives on writing HDL. They are mostly perspective based, and the way you conceptualize creating hardware may be different. In the same way that there are often many approaches to solving problems, there are many ways to implement solutions in hardware. However, they don't all work, and some are definitely better than others. The hope is that this page helps you to be able to better grasp writing HDL and how your thinking needs to change in order to understand how to solve the problems you're given.

= How is HDL Different from Writing Software? =
Hardware Descriptor Languages (HDLs - most commonly VHDL or Verilog) is fundamentally different from the programming languages you’re used to.

With writing software, you’re describing how to solve a problem. When writing HDL, you’re describing how hardware works. Ideally your description should be the description to a solution.

When writing HDL you need to think about HOW the code translates to hardware. I find it helpful to think of my project as a breadboard, modules as IC’s, registers as, well, registers in the module, wires as connections between modules, and inputs/outputs as pins on the IC. Output registers are just registers tied directly to an “output pin”. It isn’t a perfect analogy of course - sometimes it makes more sense to think of the current module you’re in as the primary breadboard (but in that case I just imagine I’m designing the IC).

= Why isn't this loop working as I expect? =
You can’t directly translate the constructs you’re used to in software to programming constructs in hardware. A good example is for loops. You may be tempted to use a for loop as a delay, but a for loop in hardware operates rather differently to a for loop in software. Think about how you might implement a for loop as you understand it – the easiest to do is have a register, incrementally increase that register’s value, and then perform your operation once that register reaches the desired value. Nandland (a great resource for all things FPGA) has a nice discussion on for loops in HDL (https://www.nandland.com/vhdl/examples/example-for-loop.html) but for the most part there’s no need to use a for loop, or any kind of loop for that matter.

= Why is my code taking a long time to compile? =
“Compile” isn’t technically correct here – it’s synthesizing, converting to a netlist, and then creating a bitstream. But we all know what each other means, so I suppose it’s okay. This is usually quite a time consuming process, which is why testbenches and simulation are such a great and easy way of testing code changes before trying to run it on the board.

Single core performance is really the biggest factor in synthesis. There is use for multicore, but a lot of the synthesis -> bitstream generation is mostly sequential (I’ve been told that the Altera/Intel tools only see about a 10% improvement when moving to the multicore/multi-threaded implementation of the synthesis tools). That probably makes a difference when creating projects that take hours to synthesize, but, for practicals and most applications, high performance PCs won’t really make all that much of a difference as most modern CPUs have similar enough single-core throughput (assuming a modern architecture).

Memory (RAM) is also a big contributing factor, but according to https://www.xilinx.com/products/design-tools/vivado/memory.html the XC7A100T (the FPGA found on the Nexys A7) uses at MOST 3GB of RAM. An implementation of a simple wall clock display only requires about 700-800mb

[https://xkcd.com/303/ Always relevant XKCD]

HDL - FAQs

2020-08-19T07:53:07Z

CRNKEE002:

As with any skill, the only way to improve and to grasp concepts is to practice. This page details some perspectives on writing HDL. They are mostly perspective based, and the way you conceptualize creating hardware may be different. In the same way that there are often many approaches to solving problems, there are many ways to implement solutions in hardware. However, they don't all work, and some are definitely better than others. The hope is that this page helps you to be able to better grasp writing HDL and how your thinking needs to change in order to understand how to solve the problems you're given.

= How is HDL Different from Writing Software? =
Hardware Descriptor Languages (HDLs - most commonly VHDL or Verilog) is fundamentally different from the programming languages you’re used to.

With writing software, you’re describing how to solve a problem. When writing HDL, you’re describing how hardware works. Ideally your description should be the description to a solution.

When writing HDL you need to think about HOW the code translates to hardware. I find it helpful to think of my project as a breadboard, modules as IC’s, registers as, well, registers in the module, wires as connections between modules, and inputs/outputs as pins on the IC. Output registers are just registers tied directly to an “output pin”. It isn’t a perfect analogy of course - sometimes it makes more sense to think of the current module you’re in as the primary breadboard (but in that case I just imagine I’m designing the IC).

= Why isn't this loop working as I expect? =
You can’t directly translate the constructs you’re used to in software to programming constructs in hardware. A good example is for loops. You may be tempted to use a for loop as a delay, but a for loop in hardware operates rather differently to a for loop in software. Think about how you might implement a for loop as you understand it – the easiest to do is have a register, incrementally increase that register’s value, and then perform your operation once that register reaches the desired value. Nandland (a great resource for all things FPGA) has a nice discussion on for loops in HDL (https://www.nandland.com/vhdl/examples/example-for-loop.html) but for the most part there’s no need to use a for loop, or any kind of loop for that matter.

= Why is my code taking a long time to compile? =
“Compile” isn’t technically correct here – it’s synthesizing, converting to a netlist, and then creating a bitstream. But we all know what each other means, so I suppose it’s okay. This is usually quite a time consuming process, which is why testbenches and simulation are such a great and easy way of testing code changes before trying to run it on the board.

Single core performance is really the biggest factor in synthesis. There is use for multicore, but a lot of the synthesis -> bitstream generation is mostly sequential (I’ve been told that the Altera/Intel tools only see about a 10% improvement when moving to the multicore/multi-threaded implementation of the synthesis tools). That probably makes a difference when creating projects that take hours to synthesize, but, for practicals and most applications, high performance PCs won’t really make all that much of a difference as most modern CPUs have similar enough single-core throughput (assuming a modern architecture).

Memory (RAM) is also a big contributing factor, but according to https://www.xilinx.com/products/design-tools/vivado/memory.html the XC7A100T (the FPGA found on the Nexys A7) uses at MOST 3GB of RAM. An implementation of a simple wall clock display only requires about 700-800mb

[https://xkcd.com/303/ Always relevant XKCD]

HDL - FAQs

2020-08-19T07:52:35Z

CRNKEE002:

As with any skill, the only way to improve and to grasp concepts is to practice. This page details some perspectives on writing HDL. They are mostly perspective based, and the way you conceptualize creating hardware may be different. In the same way that there are often many approaches to solving problems, there are many ways to implement solutions in hardware. However, they don't all work, and some are definitely better than others. The hope is that this page helps you to be able

= How is HDL Different from Writing Software? =
Hardware Descriptor Languages (HDLs - most commonly VHDL or Verilog) is fundamentally different from the programming languages you’re used to.

With writing software, you’re describing how to solve a problem. When writing HDL, you’re describing how hardware works. Ideally your description should be the description to a solution.

When writing HDL you need to think about HOW the code translates to hardware. I find it helpful to think of my project as a breadboard, modules as IC’s, registers as, well, registers in the module, wires as connections between modules, and inputs/outputs as pins on the IC. Output registers are just registers tied directly to an “output pin”. It isn’t a perfect analogy of course - sometimes it makes more sense to think of the current module you’re in as the primary breadboard (but in that case I just imagine I’m designing the IC).

= Why isn't this loop working as I expect? =
You can’t directly translate the constructs you’re used to in software to programming constructs in hardware. A good example is for loops. You may be tempted to use a for loop as a delay, but a for loop in hardware operates rather differently to a for loop in software. Think about how you might implement a for loop as you understand it – the easiest to do is have a register, incrementally increase that register’s value, and then perform your operation once that register reaches the desired value. Nandland (a great resource for all things FPGA) has a nice discussion on for loops in HDL (https://www.nandland.com/vhdl/examples/example-for-loop.html) but for the most part there’s no need to use a for loop, or any kind of loop for that matter.

= Why is my code taking a long time to compile? =
“Compile” isn’t technically correct here – it’s synthesizing, converting to a netlist, and then creating a bitstream. But we all know what each other means, so I suppose it’s okay. This is usually quite a time consuming process, which is why testbenches and simulation are such a great and easy way of testing code changes before trying to run it on the board.

Single core performance is really the biggest factor in synthesis. There is use for multicore, but a lot of the synthesis -> bitstream generation is mostly sequential (I’ve been told that the Altera/Intel tools only see about a 10% improvement when moving to the multicore/multi-threaded implementation of the synthesis tools). That probably makes a difference when creating projects that take hours to synthesize, but, for practicals and most applications, high performance PCs won’t really make all that much of a difference as most modern CPUs have similar enough single-core throughput (assuming a modern architecture).

Memory (RAM) is also a big contributing factor, but according to https://www.xilinx.com/products/design-tools/vivado/memory.html the XC7A100T (the FPGA found on the Nexys A7) uses at MOST 3GB of RAM. An implementation of a simple wall clock display only requires about 700-800mb

[https://xkcd.com/303/ Always relevant XKCD]

HDL - FAQs

2020-08-19T07:52:05Z

CRNKEE002: Created page with "=HDL= As with any skill, the only way to improve and to grasp concepts is to practice. This page details some perspectives on writing HDL. They are mostly perspective based, a..."

=HDL=
As with any skill, the only way to improve and to grasp concepts is to practice. This page details some perspectives on writing HDL. They are mostly perspective based, and the way you conceptualize creating hardware may be different. In the same way that there are often many approaches to solving problems, there are many ways to implement solutions in hardware. However, they don't all work, and some are definitely better than others. The hope is that this page helps you to be able

= How is HDL Different from Writing Software? =
Hardware Descriptor Languages (HDLs - most commonly VHDL or Verilog) is fundamentally different from the programming languages you’re used to.

With writing software, you’re describing how to solve a problem. When writing HDL, you’re describing how hardware works. Ideally your description should be the description to a solution.

When writing HDL you need to think about HOW the code translates to hardware. I find it helpful to think of my project as a breadboard, modules as IC’s, registers as, well, registers in the module, wires as connections between modules, and inputs/outputs as pins on the IC. Output registers are just registers tied directly to an “output pin”. It isn’t a perfect analogy of course - sometimes it makes more sense to think of the current module you’re in as the primary breadboard (but in that case I just imagine I’m designing the IC).

= Why isn't this loop working as I expect? =
You can’t directly translate the constructs you’re used to in software to programming constructs in hardware. A good example is for loops. You may be tempted to use a for loop as a delay, but a for loop in hardware operates rather differently to a for loop in software. Think about how you might implement a for loop as you understand it – the easiest to do is have a register, incrementally increase that register’s value, and then perform your operation once that register reaches the desired value. Nandland (a great resource for all things FPGA) has a nice discussion on for loops in HDL (https://www.nandland.com/vhdl/examples/example-for-loop.html) but for the most part there’s no need to use a for loop, or any kind of loop for that matter.

= Why is my code taking a long time to compile? =
“Compile” isn’t technically correct here – it’s synthesizing, converting to a netlist, and then creating a bitstream. But we all know what each other means, so I suppose it’s okay. This is usually quite a time consuming process, which is why testbenches and simulation are such a great and easy way of testing code changes before trying to run it on the board.

Single core performance is really the biggest factor in synthesis. There is use for multicore, but a lot of the synthesis -> bitstream generation is mostly sequential (I’ve been told that the Altera/Intel tools only see about a 10% improvement when moving to the multicore/multi-threaded implementation of the synthesis tools). That probably makes a difference when creating projects that take hours to synthesize, but, for practicals and most applications, high performance PCs won’t really make all that much of a difference as most modern CPUs have similar enough single-core throughput (assuming a modern architecture).

Memory (RAM) is also a big contributing factor, but according to https://www.xilinx.com/products/design-tools/vivado/memory.html the XC7A100T (the FPGA found on the Nexys A7) uses at MOST 3GB of RAM. An implementation of a simple wall clock display only requires about 700-800mb

[https://xkcd.com/303/ Always relevant XKCD]

RaspberryPi:AdvancedConnectivity

2020-08-18T12:20:59Z

CRNKEE002: /* Providing your Pi with wireless Internet Access */

[[Category:RaspberryPi]]
= Overview =
This page covers advanced connectivity options that you can use on the Raspberry Pi. While not always required, they can simplify and streamline the way you work with the Raspberry Pi.

For issues with connectivity, visit [[RaspberryPi:DebuggingConnectivity]]

= Configuring the Pi to Act as an Access Point =

If you are hosting a server on the Raspberry Pi, or perhaps want to create a WiFi network for guests to connect to, the Pi can act as an access point. This guide comes from https://www.raspberrypi.org/documentation/configuration/wireless/access-point.md and https://frillip.com/using-your-raspberry-pi-3-as-a-wifi-access-point-with-hostapd/ and will work with a Pi that has an Ethernet Port (though it it possible to mimic an Ethernet port on a Pi 0W over USB. A Pi 0 doesn't have WiFi so this wouldn't serve any purpose).

Note that this WiFi connection will not provide internet access by bridging the Ethernet port (that’s something else entirely), but it works well for hosting services on the Pi, such as a Node-Red server.

<span class="mw-customtoggle-AP" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-AP" class="mw-collapsible mw-collapsed">
<ol>
<li><p>SSH into the Pi, update, and reboot to ensure updates have taken place</p>
<pre>$ sudo apt-get update
$ sudo apt-get dist-upgrade
$ sudo reboot</pre></li>
<li><p>Wait for the Pi to reboot, and reconnect via SSH. Install hostapd and dnsmasq</p>
<pre>$ sudo apt-get install hostapd dnsmasq</pre></li>
<li><p>Configure a static IP in dhcpcd</p>
<pre>$ sudo nano /etc/dhcpcd.conf</pre>
<p>Adjust the contents so that the wireless interface is described as follows:</p>
<pre>interface wlan0
static ip_address=192.168.4.1/24
nohook wpa_supplicant</pre>
<p>Save and close that file, and restart the dhcp service</p>
<pre>$ sudo systemctl restart dhcpcd</pre></li>
<li><p>Run the following commands to create save the original dnsmasq, and create a new file which will be edited:</p>
<pre>$ sudo mv /etc/dnsmasq.conf /etc/dnsmasq.conf.orig
$ sudo nano /etc/dnsmasq.conf</pre>
<p>Place the following in the now open file:</p>
<pre>interface=wlan0
listen-address=192.168.4.1
dhcp-range=192.168.4.2,192.168.4.180,255.255.255.0,24h
server=8.8.8.8
domain-needed
bogus-priv</pre>
<p>Save and close the file</p></li>
<li><p>Restart the dnsmasq service</p>
<pre>$ sudo systemctl reload dnsmasq</pre></li>
<li><p>Configure hostapd. Open up the configuration file:</p>
<pre>sudo nano /etc/hostapd/hostapd.conf</pre>
<p>Place the following configuration in the file. Some assumptions are made about the technical aspects of it, but these are beyond the scope of this course. Note that network name and password '''do not''' have quotes around them.</p>
<pre>interface=wlan0
driver=nl80211
ssid=TestNetwork
hw_mode=g
channel=7
ieee80211n=1
wmm_enabled=1
macaddr_acl=0
auth_algs=1
ignore_broadcast_ssid=0
wpa=2
wpa_passphrase=TestNetwork
wpa_key_mgmt=WPA-PSK
wpa_pairwise=TKIP
rsn_pairwise=CCMP</pre>
<p>Save and close the file</p></li>
<li><p>Next, the system needs to know where to find this configuration file. Open the configuration file:</p>
<pre>$ sudo nano /etc/default/hostapd</pre>
<p>Find the line with “#DAEMON_CONF” and replace it with:</p>
<pre>DAEMON_CONF="/etc/hostapd/hostapd.conf"</pre>
<p>Save and close this file.</p></li>
<li><p>Now enable and start hostapd:</p>
<pre>$ sudo systemctl unmask hostapd
$ sudo systemctl enable hostapd
$ sudo systemctl start hostapd</pre></li>
<li><p>Add routing and masquerade by opening sysctl:</p>
<pre>$ sudo nano /etc/sysctl.conf</pre>
<p>And uncomment this line by removing the preceding # symbol:</p>
<pre>net.ipv4.ip_forward=1</pre>
<p>Save and close the file</p></li>
<li><p>Add a masquerade, and save the iptables rule:</p>
<pre>$ sudo iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE
$ sudo sh -c "iptables-save > /etc/iptables.ipv4.nat"</pre></li>
<li><p>Edit /etc/rc.local and add this just above “exit 0” to install these rules on boot.</p>
<pre>$ sudo nano /etc/rc.local</pre>
<p>Place the following just above “exit 0” to install these rules on boot</p>
<pre>iptables-restore < /etc/iptables.ipv4.nat</pre></li></ol>
</div>

RaspberryPi:AdvancedConnectivity

2020-08-18T12:20:51Z

CRNKEE002:

[[Category:RaspberryPi]]
= Overview =
This page covers advanced connectivity options that you can use on the Raspberry Pi. While not always required, they can simplify and streamline the way you work with the Raspberry Pi.

For issues with connectivity, visit [[RaspberryPi:DebuggingConnectivity]]

= Providing your Pi with wireless Internet Access =

There are three possible methods of this that will be presented, each with it’s own advantages and disadvantages.

The third involves connecting to a wireless network. We provide examples for private networks, and Eduroam. Note that if connected using Eduroam, some services may be limited based on ICTS policy, but, for the most part, everything should accessible

= Configuring the Pi to Act as an Access Point =

If you are hosting a server on the Raspberry Pi, or perhaps want to create a WiFi network for guests to connect to, the Pi can act as an access point. This guide comes from https://www.raspberrypi.org/documentation/configuration/wireless/access-point.md and https://frillip.com/using-your-raspberry-pi-3-as-a-wifi-access-point-with-hostapd/ and will work with a Pi that has an Ethernet Port (though it it possible to mimic an Ethernet port on a Pi 0W over USB. A Pi 0 doesn't have WiFi so this wouldn't serve any purpose).

Note that this WiFi connection will not provide internet access by bridging the Ethernet port (that’s something else entirely), but it works well for hosting services on the Pi, such as a Node-Red server.

<span class="mw-customtoggle-AP" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-AP" class="mw-collapsible mw-collapsed">
<ol>
<li><p>SSH into the Pi, update, and reboot to ensure updates have taken place</p>
<pre>$ sudo apt-get update
$ sudo apt-get dist-upgrade
$ sudo reboot</pre></li>
<li><p>Wait for the Pi to reboot, and reconnect via SSH. Install hostapd and dnsmasq</p>
<pre>$ sudo apt-get install hostapd dnsmasq</pre></li>
<li><p>Configure a static IP in dhcpcd</p>
<pre>$ sudo nano /etc/dhcpcd.conf</pre>
<p>Adjust the contents so that the wireless interface is described as follows:</p>
<pre>interface wlan0
static ip_address=192.168.4.1/24
nohook wpa_supplicant</pre>
<p>Save and close that file, and restart the dhcp service</p>
<pre>$ sudo systemctl restart dhcpcd</pre></li>
<li><p>Run the following commands to create save the original dnsmasq, and create a new file which will be edited:</p>
<pre>$ sudo mv /etc/dnsmasq.conf /etc/dnsmasq.conf.orig
$ sudo nano /etc/dnsmasq.conf</pre>
<p>Place the following in the now open file:</p>
<pre>interface=wlan0
listen-address=192.168.4.1
dhcp-range=192.168.4.2,192.168.4.180,255.255.255.0,24h
server=8.8.8.8
domain-needed
bogus-priv</pre>
<p>Save and close the file</p></li>
<li><p>Restart the dnsmasq service</p>
<pre>$ sudo systemctl reload dnsmasq</pre></li>
<li><p>Configure hostapd. Open up the configuration file:</p>
<pre>sudo nano /etc/hostapd/hostapd.conf</pre>
<p>Place the following configuration in the file. Some assumptions are made about the technical aspects of it, but these are beyond the scope of this course. Note that network name and password '''do not''' have quotes around them.</p>
<pre>interface=wlan0
driver=nl80211
ssid=TestNetwork
hw_mode=g
channel=7
ieee80211n=1
wmm_enabled=1
macaddr_acl=0
auth_algs=1
ignore_broadcast_ssid=0
wpa=2
wpa_passphrase=TestNetwork
wpa_key_mgmt=WPA-PSK
wpa_pairwise=TKIP
rsn_pairwise=CCMP</pre>
<p>Save and close the file</p></li>
<li><p>Next, the system needs to know where to find this configuration file. Open the configuration file:</p>
<pre>$ sudo nano /etc/default/hostapd</pre>
<p>Find the line with “#DAEMON_CONF” and replace it with:</p>
<pre>DAEMON_CONF="/etc/hostapd/hostapd.conf"</pre>
<p>Save and close this file.</p></li>
<li><p>Now enable and start hostapd:</p>
<pre>$ sudo systemctl unmask hostapd
$ sudo systemctl enable hostapd
$ sudo systemctl start hostapd</pre></li>
<li><p>Add routing and masquerade by opening sysctl:</p>
<pre>$ sudo nano /etc/sysctl.conf</pre>
<p>And uncomment this line by removing the preceding # symbol:</p>
<pre>net.ipv4.ip_forward=1</pre>
<p>Save and close the file</p></li>
<li><p>Add a masquerade, and save the iptables rule:</p>
<pre>$ sudo iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE
$ sudo sh -c "iptables-save > /etc/iptables.ipv4.nat"</pre></li>
<li><p>Edit /etc/rc.local and add this just above “exit 0” to install these rules on boot.</p>
<pre>$ sudo nano /etc/rc.local</pre>
<p>Place the following just above “exit 0” to install these rules on boot</p>
<pre>iptables-restore < /etc/iptables.ipv4.nat</pre></li></ol>
</div>

RaspberryPi:Networking

2020-08-18T12:19:03Z

CRNKEE002: /* Ethernet Connectivity */

[[Category:RaspberryPi]]
There are many ways to interface with the Pi. This page will cover types of network connectivity. For more comprehensive, advanced networking details, see [[RaspberryPi:AdvancedConnectivity]].

= A Brief Overview of Networks =

It is useful to have a basic idea of how networks, IP addresses, and subnets work. For this, it it suggested you read [https://support.microsoft.com/en-za/help/164015/understanding-tcp-ip-addressing-and-subnetting-basics this article] from Microsoft.

= Wireless Connectivity =
WiFi connectivity is a useful way of connecting the Pi to the internet as it enables more portability. You can adjust WiFi Connections either before boot, by creating a <code>wpa_cupplicant.conf</code> file on the boot partition, or while the pi is running, either by editing <code>/etc/wpa/wpa_supplicant.conf</code> directly, or using <code>$ sudo raspi-config</code>. Note that the raspi-config method will not work for Eduroam.

== Simple Wifi Connections ==
If the Pi is up and running and you have access to it, you can run <code>$ sudo raspi-config</code> and enable WiFi using that menu, or editing <code>/etc/wpa/wpa_supplicant.conf</code> directly using an editor such as nano. However if you don't have access, you can create a a <code>wpa_supplicant.conf</code> file on the SD card, on the boot partition while it is plugged into another system.

If editing the wpa_supplicant configuration file, the contents should look something like the following:
<pre>
ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
update_config=1
country=ZA

network={
ssid="<Name of your WiFi network>"
psk="<Password for your WiFi network>"
}
</pre>

== Connecting to Eduroam ==
Connecting to Eduroam requires a fair amount of configuration which depends on your operating system. Generally though, edits to wpa_supplicant.conf and dhcpcd.conf are sufficient. Note that there are new releases of Raspberry Pi OS, and it is unknown if the edits for Buster are still required.

<span class="mw-customtoggle-Eduroam" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-Eduroam" class="mw-collapsible mw-collapsed">
=== Raspbian Buster ===
'''Note:''' There have been updates to the Buster code base, and roll back of wpasupplicant might not be required. However this is currently unable to be tested due to the lockdown. If someone has the chance to test, please update this page accordingly.
These instructions come from [https://www.raspberrypi.org/forums/viewtopic.php?p=1501822#p1501822 here].<br />
Unfortunately, when you use bleeding edge technology, you may end up cutting yourself. Raspbian Buster updates <code>wpa_supplicant</code> to a version that doesn’t have support for the authentication method used by Eduroam. So we need to roll back <code>wpa_supplicant</code> to an older version. Ensure your Pi has internet access through a method such as Ethernet passthrough, and run the following:

<pre>$ sudo apt-get remove wpasupplicant</pre>
Edit /etc/apt/sources.list :

<pre>$ sudo nano /etc/apt/sources.list</pre>
And change

<pre>deb http://raspbian.raspberrypi.org/raspbian/ buster main contrib non-free rpi</pre>
to

<pre>deb http://raspbian.raspberrypi.org/raspbian/ stretch main contrib non-free rpi</pre>
Run

<pre>$ sudo apt-get update
$ sudo apt-get install wpasupplicant</pre>
This will install the correct version of <code>wpa_supplicant</code>. Check that '''version 2.4''' is installed by running

<pre>$ wpa_supplicant -v</pre>
Now, change the sources file back.

<pre>$ sudo nano /etc/apt/sources.list</pre>
And edit the contents to contain

<pre>deb http://raspbian.raspberrypi.org/raspbian/ buster main contrib non-free rpi</pre>
Finally, run

<pre>$ sudo apt-get update</pre>
To update sources The correct version of <code>wpa_supplicant</code> should now be installed, and you can configure your Pi for WiFi as you would if you were using Raspbian Stretch as explained in below.

=== Raspbian Stretch ===

This section provides the instructions on how to configure the Pi to use Eduroam. It is possible to do using the GUI through VNC, but we will not cover that here.

<ol>
<li><p>SSH into your Pi.</p></li>
<li><p>Generate a hash for your password. Take note of it as it is needed in a later step</p>
<pre>
$ echo -n your_uct_password_here | iconv -t utf16le | openssl md4
</pre></li>
<li><p>Open /etc/wpa_supplicant/wpa_supplicant.conf</p>
<pre>$ sudo nano /etc/wpa_supplicant/wpa_supplicant.conf</pre></li>
<li><p>Edit it so it looks as follows:</p>
<pre>
ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
update_config=1
country=ZA

network={
ssid="eduroam"
key_mgmt=WPA-EAP
identity="studentnumber@wf.uct.ac.za"
password=hash:generated_hash_from_earlier
}
</pre></li>
<li><p>Save the file</p></li>
<li><p>Open <code>/etc/dhcpcd.conf</code></p>
<pre> $ sudo nano /etc/dhcpcd.conf</pre></li>
<li><p>Make sure the following lines are in the document:</p>
<pre>interface wlan0
metric 200
</pre></li>
<li><p>Reboot your Pi</p></li>
<li><p>WiFi Generally takes a little longer to initialize than Ethernet, so give it time. You can see if it’s ready by running</p>
<pre>$ ifconfig </pre>
<p>And seeing if an IPv4 address (“inet”) has been given.</p></li>
<li><p>Test your configuration by pinging from the WiFi interface:</p>
<pre>$ ping google.com -I wlan0</pre></li></ol>
</div>

= Ethernet Connectivity =
Ethernet is the physical connection made using a CAT 5 or 6 cable - though there are ways that Ethernet can be mimicked over USB (see Details on the Pi 0 and 0W for more information).

There are two sorts of Ethernet Connectivity we will consider. The first is just connecting the Pi to a known Ethernet network. It is simple as it requires no configuration, but it means you will need to use other methods to ensure the network allows SSH traffic and to ensure you can determine the IP of the Pi.

The second is using Ethernet passthrough from your computer to the Raspberry Pi. This leaves the WiFi free to host your own access point, and you can host services such as a Node-Red server or media center on the Pi.

If you're on a private network, connecting your Pi to a router will usually just assign it an IP address and internet connectivity automatically works. If you're on a linux-based system, like Ubuntu, you can use the hostname of the Pi to connect. By default this is "raspberrypi", so you could SSH in using "SSH pi@raspberrypi". However, in most cases, you'll want to know the IP address and assign a static IP address.

== Static IPs ==
Setting a static IP makes it easy to access the Pi and ensures that the IP address of the Pi is always known. In this course, we assign the Pi an IP address of 192.168.137.15. The reason for this is that when using Ethernet Passthrough on Windows, Windows asserts a domain of 192.168.137.x, with the host PC being assigned 192.168.137.1. Keep in mind that all devices will need to be on the same subnet though, so if you're assigning a static IP to be used on your own Ethernet network, you need to know what the subnet of that network is.

If you're connecting your Pi through your desktop, you'll need to assign a static IP to the desktop, too.

== Setting a static IP on your Desktop ==
If you're connecting your Pi through your desktop, you'll need to assign a static IP to the desktop, too. If you're setting a static IP on a Pi that's already connected directly to the network through a router or similar network switch, you can ignore setting a static IP on the computer.

=== Windows ===
<span class="mw-customtoggle-WindowsIP" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-WindowsIP" class="mw-collapsible mw-collapsed">
To change the IP of your Ethernet port on Windows 10, complete the following steps:

* Right click on your network option in Windows taskbar
* Select “Open Network & Internet Settings”, on the lower right hand side of the screen.
* Select “Change Adapted Options”
* Right click on the Ethernet Connection and select “Properties”
* Select “Internet Protocol Version 4 (TCP/IPv4) and click ”Properties"
* Select “Use the following IP address:” and enter in the following options:<br />
- IP Address: 192.168.137.1<br />
- Subnet Mask: 255.255.255.0
* You have successfully changed the IP of the Ethernet card on your computer. It is suggested that you now ensure connectivity by attempting to ping the Pi.

[[File:windowsIPConfig.png|thumb|none|alt=|The IPv4 configuration screen in Windows 10]]
</div>
=== Ubuntu ===
<span class="mw-customtoggle-UbuntuIP" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-UbuntuIP" class="mw-collapsible mw-collapsed">
To change the IP of your Ethernet port on Ubuntu, complete the following steps:

* Click the network interface icon on the status bar and select Wired Settings
* Click the gear button of the interface you’d like to change
* Select the IPv4 Tab, and change the IPv4 method to Manual
* Under “Addresses” enter in the following:<br />
- IP Address: 192.168.137.1<br />
- Subnet Mask: 255.255.255.0
* You can leave Gateway and DNS blank

[[File:Ubuntustaticip.png|thumb|none|alt=|The IPv4 configuration screen in Ubuntu 18.10]]
</div>

== Setting a static IP on the Pi ==
To set a static IP on the Pi, you have multiple options. You can do it before first boot by addling a line to cmdline.txt on the boot partition of the SD card, or once the Pi is running by editing dhcpcd.
Before setting the static IP, ensure you have the correct subdomain, and that you don't assign an IP that another device on the network is using. If you're assinging it a static IP and you have, for example, a router acting as a DHCP server, ensure the IP you assign is outside of DHCP range.

=== From the boot partition ===
<span class="mw-customtoggle-PiStaticBoot" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-PiStaticBoot" class="mw-collapsible mw-collapsed">
<ol>
<li><p>Insert the SD card into your computer and navigate to the BOOT partition</p></li>
<li><p>Open “cmdline.txt” and append the following to the line (don’t create a new line)</p>
<pre> ip=192.168.137.15 </pre>
<p>This tells the Raspberry Pi to configure the Ethernet port to use the IP address 192.168.137.15</p></li>
<li><p>Enable SSH as per Section [sec:SSH].</p></li>
<li><p>You need to configure your PC to use the same subnet as the Pi. To do so, see the information below in the section on Assigning a static IP to the Pi.</p></li></ol>
</div>
=== In dhcpcd (while the Pi is running)===
<span class="mw-customtoggle-PiStaticDHCPCD" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-PiStaticDHCPCD" class="mw-collapsible mw-collapsed">
Once you’ve successfully SSH’d into your Pi, it’s a good idea to configure the networking options in the config files directly. You will need to set a static IP on the computer first if you are SSH'ing through an Ethernet connection.

Use a text editor such as nano to open /etc/dhcpcd.conf as sudo user, and edit it to the following:

<pre># Static IP profile for eth0
profile static_eth0
static ip_address=192.168.137.15/24
static routers=192.168.137.1
static domain_name_servers=192.168.137.1 8.8.8.8

# Ethernet interface configuration
interface eth0
fallback static_eth0

# Wireless configuration
interface wlan0
metric 200</pre>
</div>

== WiFi to Ethernet Passthrough ==
In a situation when you can't or don't want to connect to a WiFi network, but are connected to a computer through an Ethernet port There may be a situation in which you want your Pi to work as an access point rather than using the WiFi interface to provide the Pi with internet access. In this situation, you need to get internet access through the Ethernet port. Before starting, you need to ensure the computer you're using has a static IP assigned. When enabling network sharing on Windows, it automatically assigns 192.168.137.1. Once that's done, complete the following to enable network sharing:

=== Windows ===
<span class="mw-customtoggle-PassthroughWindows" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-PassthroughWindows" class="mw-collapsible mw-collapsed">
# Ensure the Pi is unplugged
# Right click on your network option in Windows taskbar
# Select “Open Network & Internet Settings”, on the lower right hand side of the screen.
# Select “Change Adapted Options”
# Right click on your WiFi network and select “Properties”
# Click the “Sharing” tab, and enable the first checkbox <ref>This setting is what forces us to have to use the subnet 192.168.137.x.</ref>
# Select the Ethernet connection that your Pi will be using in the drop down box (Usually just “Ethernet”, but may be different if there are multiple Ethernet posts on your system)

[[File:Windowspassthrough.png|thumb|none|alt=|Using WiFi to Ethernet passthrough in Windows]]
</div>
=== Ubuntu ===
<span class="mw-customtoggle-PassthroughUbuntu" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-PassthroughUbuntu" class="mw-collapsible mw-collapsed">
# Ensure the Pi is unplugged and turned off.
# Open a terminal and run <code>nm-connection-editor</code>
# Select the wired connection you’d like to share your WiFi to
# Select the IPv4 settings tab
# Under Method, select “Shared to other computers”
# under the IP addresses, click “Add” and enter in an address of 192.168.137.1, and a netmask of 24
# Select “Save”, and close the windows
# Plug in the Pi, start an SSH session and see if you can ping google.co.za

[[File:Nm-connection-editor.png|thumb|none|alt=|nm-connection-editor in Ubuntu 18.10]]
</div>

= Other Connectivity Methods =
There are ways other than WiFi and Ethernet as a means of connecting headlessly (without a keyboard and screen directly attached) to the Pi.

== TTL over USB ==

'''Note:''' The Pi uses 3.3V logic levels. Using a 5V logic module will permanently damage the pins.

This option allows you to use a USB to UART converter such as a FT232R or CP2102. Begin by removing the SD card, and insert it into a computer. Make the following changes on the boot partition:

cmdline.txt: add the following (on the same line)

<pre>console=serial0,115200 </pre>
config.txt

<pre>uart_enable=1
dtoverlay=pi3-disable-bt</pre>

== Using USB connectivity on the Pi 0/0W ==

= Ensuring Connectivity =

Sometimes you may want to debug your connection to the Pi. A fast way to do this is via the ''ping'' command. ''Ping'' sends a packet to a particular host (in this case the Pi), and measures the time taken for a response from that host.

To use the ping command, open a command prompt window or terminal and type the following:

<pre>$ ping 192.168.137.15</pre>
If that host is unreachable (the Pi hasn’t booted yet or is incorrectly configured), a message will show that the host is unreachable. If everything was correctly configured, you should get

<pre>Reply from 192.168.137.15: bytes=32 time<1ns TTL=64</pre>
This means your Pi and computer are both correctly configured. See section [sec:SSH] for configuring your Pi for SSH access.

'''NB:''' Don’t be surprised if you can’t ping a Windows machine from your Pi. Windows blocks the specific type of packet required for a ping in the firewall.

= Networking Protocols=
For a more detailed overview on useful networking protocols, see [[Network Protocols]]
== SSH ==

=== Enabling SSH ===

If you have not connected to your Pi and configured it for SSH, you need to do so. SSH is disabled by default on new installations of Raspbian.

To enable SSH, add it as an enabled service in the <code>raspi-config</code> menu. If you do not have access to the Pi as yet, do the following:

# Insert the SD card into a computer
# Navigate to the BOOT partition
# Create a file called “ssh”. <strong>Note there is no file extension!</strong>
# Your Pi will enable SSH upon next boot

=== Using SSH ===

To use SSH on your Pi, you need to connect to the computer to a network. See Section [sec:NetworkingOnThePi] on various ways that can be done (it is suggested to use Ethernet upon first connection).

Once your Pi is connected to the computer and you have ensured connection (see Section [sec:Connectivity-EnsuringConnectivity]), use can log in to your Pi via SSH. If you are on a Linux-based system, such as Ubuntu or Mac, you should be able to run the following. Note that the default username is “pi” and the default password is “raspberry”.

<pre>$ ssh <username>@192.168.137.15</pre>
If you are on Windows, you may need to use PuTTY. Some instances of windows have SSH in the command line, and you can run the command shown above. But if not, you will need to do the following:

# Open PuTTY
# In the “Hostname” field, enter in “192.168.137.15”
# Click “Open”. A terminal window will be opened. If it is the first time you’re SSH’ing into your Pi on this particular computer, you will be asked about the server fingerprint. Click “Yes” to continue.
# You will be asked for a username and password. The default username is “pi” and the password is “raspberry”.
# You should now successfully connected to your Raspberry Pi via SSH

== VNC ==
To learn about how to install VNC, see
# Ensure the VNC service is enabled on the Pi

#Connect to the Pi through VNC.
# Set your preferred resolution for Raspbian
## In the desktop menu, go to Preferences - Raspberry Pi Configuration and click the “Set Resolution” button.
## Select a more appropriate resolution (1280*720 suggested)
## Select “Okay” and then “Okay”. You will be asked to reboot your Pi, do so.
# Set the VNC resolution
## Through editing /boot/config.txt, uncomment the following lines relating to framebuffer_width and framebuffer_height
## On the desktop on VNC, use the settings. Do this if you have already connected to VNC. This is a little more difficult as it required you to play with windows in order to see the buttons you need.

RaspberryPi:Networking

2020-08-18T12:11:52Z

CRNKEE002: /* Using USB connectivity on the Pi 0/ 0W */

[[Category:RaspberryPi]]
There are many ways to interface with the Pi. This page will cover types of network connectivity. For more comprehensive, advanced networking details, see [[RaspberryPi:AdvancedConnectivity]].

= A Brief Overview of Networks =

It is useful to have a basic idea of how networks, IP addresses, and subnets work. For this, it it suggested you read [https://support.microsoft.com/en-za/help/164015/understanding-tcp-ip-addressing-and-subnetting-basics this article] from Microsoft.

= Wireless Connectivity =
WiFi connectivity is a useful way of connecting the Pi to the internet as it enables more portability. You can adjust WiFi Connections either before boot, by creating a <code>wpa_cupplicant.conf</code> file on the boot partition, or while the pi is running, either by editing <code>/etc/wpa/wpa_supplicant.conf</code> directly, or using <code>$ sudo raspi-config</code>. Note that the raspi-config method will not work for Eduroam.

== Simple Wifi Connections ==
If the Pi is up and running and you have access to it, you can run <code>$ sudo raspi-config</code> and enable WiFi using that menu, or editing <code>/etc/wpa/wpa_supplicant.conf</code> directly using an editor such as nano. However if you don't have access, you can create a a <code>wpa_supplicant.conf</code> file on the SD card, on the boot partition while it is plugged into another system.

If editing the wpa_supplicant configuration file, the contents should look something like the following:
<pre>
ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
update_config=1
country=ZA

network={
ssid="<Name of your WiFi network>"
psk="<Password for your WiFi network>"
}
</pre>

== Connecting to Eduroam ==
Connecting to Eduroam requires a fair amount of configuration which depends on your operating system. Generally though, edits to wpa_supplicant.conf and dhcpcd.conf are sufficient. Note that there are new releases of Raspberry Pi OS, and it is unknown if the edits for Buster are still required.

<span class="mw-customtoggle-Eduroam" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-Eduroam" class="mw-collapsible mw-collapsed">
=== Raspbian Buster ===
'''Note:''' There have been updates to the Buster code base, and roll back of wpasupplicant might not be required. However this is currently unable to be tested due to the lockdown. If someone has the chance to test, please update this page accordingly.
These instructions come from [https://www.raspberrypi.org/forums/viewtopic.php?p=1501822#p1501822 here].<br />
Unfortunately, when you use bleeding edge technology, you may end up cutting yourself. Raspbian Buster updates <code>wpa_supplicant</code> to a version that doesn’t have support for the authentication method used by Eduroam. So we need to roll back <code>wpa_supplicant</code> to an older version. Ensure your Pi has internet access through a method such as Ethernet passthrough, and run the following:

<pre>$ sudo apt-get remove wpasupplicant</pre>
Edit /etc/apt/sources.list :

<pre>$ sudo nano /etc/apt/sources.list</pre>
And change

<pre>deb http://raspbian.raspberrypi.org/raspbian/ buster main contrib non-free rpi</pre>
to

<pre>deb http://raspbian.raspberrypi.org/raspbian/ stretch main contrib non-free rpi</pre>
Run

<pre>$ sudo apt-get update
$ sudo apt-get install wpasupplicant</pre>
This will install the correct version of <code>wpa_supplicant</code>. Check that '''version 2.4''' is installed by running

<pre>$ wpa_supplicant -v</pre>
Now, change the sources file back.

<pre>$ sudo nano /etc/apt/sources.list</pre>
And edit the contents to contain

<pre>deb http://raspbian.raspberrypi.org/raspbian/ buster main contrib non-free rpi</pre>
Finally, run

<pre>$ sudo apt-get update</pre>
To update sources The correct version of <code>wpa_supplicant</code> should now be installed, and you can configure your Pi for WiFi as you would if you were using Raspbian Stretch as explained in below.

=== Raspbian Stretch ===

This section provides the instructions on how to configure the Pi to use Eduroam. It is possible to do using the GUI through VNC, but we will not cover that here.

<ol>
<li><p>SSH into your Pi.</p></li>
<li><p>Generate a hash for your password. Take note of it as it is needed in a later step</p>
<pre>
$ echo -n your_uct_password_here | iconv -t utf16le | openssl md4
</pre></li>
<li><p>Open /etc/wpa_supplicant/wpa_supplicant.conf</p>
<pre>$ sudo nano /etc/wpa_supplicant/wpa_supplicant.conf</pre></li>
<li><p>Edit it so it looks as follows:</p>
<pre>
ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
update_config=1
country=ZA

network={
ssid="eduroam"
key_mgmt=WPA-EAP
identity="studentnumber@wf.uct.ac.za"
password=hash:generated_hash_from_earlier
}
</pre></li>
<li><p>Save the file</p></li>
<li><p>Open <code>/etc/dhcpcd.conf</code></p>
<pre> $ sudo nano /etc/dhcpcd.conf</pre></li>
<li><p>Make sure the following lines are in the document:</p>
<pre>interface wlan0
metric 200
</pre></li>
<li><p>Reboot your Pi</p></li>
<li><p>WiFi Generally takes a little longer to initialize than Ethernet, so give it time. You can see if it’s ready by running</p>
<pre>$ ifconfig </pre>
<p>And seeing if an IPv4 address (“inet”) has been given.</p></li>
<li><p>Test your configuration by pinging from the WiFi interface:</p>
<pre>$ ping google.com -I wlan0</pre></li></ol>
</div>

= Ethernet Connectivity =
Ethernet is the physical connection made using a CAT 5 or 6 cable - though there are ways that Ethernet can be mimicked over USB (see Details on the Pi 0 and 0W for more information).

If you're on a private network, connecting your Pi will usually just assign it an IP address and internet connectivity automatically works. If you're on a linux-based system, like Ubuntu, you can use the hostname of the Pi to connect. By default this is "raspberrypi", so you could SSH in using "SSH pi@raspberrypi". However, in most cases, you'll want to know the IP address and assign a static IP address.

== Static IPs ==
Setting a static IP makes it easy to access the Pi and ensures that the IP address of the Pi is always known. In this course, we assign the Pi an IP address of 192.168.137.15. The reason for this is that when using Ethernet Passthrough on Windows, Windows asserts a domain of 192.168.137.x, with the host PC being assigned 192.168.137.1. Keep in mind that all devices will need to be on the same subnet though, so if you're assigning a static IP to be used on your own Ethernet network, you need to know what the subnet of that network is.

If you're connecting your Pi through your desktop, you'll need to assign a static IP to the desktop, too.

== Setting a static IP on your Desktop ==
If you're connecting your Pi through your desktop, you'll need to assign a static IP to the desktop, too. If you're setting a static IP on a Pi that's already connected directly to the network through a router or similar network switch, you can ignore setting a static IP on the computer.

=== Windows ===
<span class="mw-customtoggle-WindowsIP" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-WindowsIP" class="mw-collapsible mw-collapsed">
To change the IP of your Ethernet port on Windows 10, complete the following steps:

* Right click on your network option in Windows taskbar
* Select “Open Network & Internet Settings”, on the lower right hand side of the screen.
* Select “Change Adapted Options”
* Right click on the Ethernet Connection and select “Properties”
* Select “Internet Protocol Version 4 (TCP/IPv4) and click ”Properties"
* Select “Use the following IP address:” and enter in the following options:<br />
- IP Address: 192.168.137.1<br />
- Subnet Mask: 255.255.255.0
* You have successfully changed the IP of the Ethernet card on your computer. It is suggested that you now ensure connectivity by attempting to ping the Pi.

[[File:windowsIPConfig.png|thumb|none|alt=|The IPv4 configuration screen in Windows 10]]
</div>
=== Ubuntu ===
<span class="mw-customtoggle-UbuntuIP" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-UbuntuIP" class="mw-collapsible mw-collapsed">
To change the IP of your Ethernet port on Ubuntu, complete the following steps:

* Click the network interface icon on the status bar and select Wired Settings
* Click the gear button of the interface you’d like to change
* Select the IPv4 Tab, and change the IPv4 method to Manual
* Under “Addresses” enter in the following:<br />
- IP Address: 192.168.137.1<br />
- Subnet Mask: 255.255.255.0
* You can leave Gateway and DNS blank

[[File:Ubuntustaticip.png|thumb|none|alt=|The IPv4 configuration screen in Ubuntu 18.10]]
</div>

== Setting a static IP on the Pi ==
To set a static IP on the Pi, you have multiple options. You can do it before first boot by addling a line to cmdline.txt on the boot partition of the SD card, or once the Pi is running by editing dhcpcd.
Before setting the static IP, ensure you have the correct subdomain, and that you don't assign an IP that another device on the network is using. If you're assinging it a static IP and you have, for example, a router acting as a DHCP server, ensure the IP you assign is outside of DHCP range.

=== From the boot partition ===
<span class="mw-customtoggle-PiStaticBoot" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-PiStaticBoot" class="mw-collapsible mw-collapsed">
<ol>
<li><p>Insert the SD card into your computer and navigate to the BOOT partition</p></li>
<li><p>Open “cmdline.txt” and append the following to the line (don’t create a new line)</p>
<pre> ip=192.168.137.15 </pre>
<p>This tells the Raspberry Pi to configure the Ethernet port to use the IP address 192.168.137.15</p></li>
<li><p>Enable SSH as per Section [sec:SSH].</p></li>
<li><p>You need to configure your PC to use the same subnet as the Pi. To do so, see the information below in the section on Assigning a static IP to the Pi.</p></li></ol>
</div>
=== In dhcpcd (while the Pi is running)===
<span class="mw-customtoggle-PiStaticDHCPCD" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-PiStaticDHCPCD" class="mw-collapsible mw-collapsed">
Once you’ve successfully SSH’d into your Pi, it’s a good idea to configure the networking options in the config files directly. You will need to set a static IP on the computer first if you are SSH'ing through an Ethernet connection.

Use a text editor such as nano to open /etc/dhcpcd.conf as sudo user, and edit it to the following:

<pre># Static IP profile for eth0
profile static_eth0
static ip_address=192.168.137.15/24
static routers=192.168.137.1
static domain_name_servers=192.168.137.1 8.8.8.8

# Ethernet interface configuration
interface eth0
fallback static_eth0

# Wireless configuration
interface wlan0
metric 200</pre>
</div>

== WiFi to Ethernet Passthrough ==
In a situation when you can't or don't want to connect to a WiFi network, but are connected to a computer through an Ethernet port There may be a situation in which you want your Pi to work as an access point rather than using the WiFi interface to provide the Pi with internet access. In this situation, you need to get internet access through the Ethernet port. Before starting, you need to ensure the computer you're using has a static IP assigned. When enabling network sharing on Windows, it automatically assigns 192.168.137.1. Once that's done, complete the following to enable network sharing:

=== Windows ===
<span class="mw-customtoggle-PassthroughWindows" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-PassthroughWindows" class="mw-collapsible mw-collapsed">
# Ensure the Pi is unplugged
# Right click on your network option in Windows taskbar
# Select “Open Network & Internet Settings”, on the lower right hand side of the screen.
# Select “Change Adapted Options”
# Right click on your WiFi network and select “Properties”
# Click the “Sharing” tab, and enable the first checkbox <ref>This setting is what forces us to have to use the subnet 192.168.137.x.</ref>
# Select the Ethernet connection that your Pi will be using in the drop down box (Usually just “Ethernet”, but may be different if there are multiple Ethernet posts on your system)

[[File:Windowspassthrough.png|thumb|none|alt=|Using WiFi to Ethernet passthrough in Windows]]
</div>
=== Ubuntu ===
<span class="mw-customtoggle-PassthroughUbuntu" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-PassthroughUbuntu" class="mw-collapsible mw-collapsed">
# Ensure the Pi is unplugged and turned off.
# Open a terminal and run <code>nm-connection-editor</code>
# Select the wired connection you’d like to share your WiFi to
# Select the IPv4 settings tab
# Under Method, select “Shared to other computers”
# under the IP addresses, click “Add” and enter in an address of 192.168.137.1, and a netmask of 24
# Select “Save”, and close the windows
# Plug in the Pi, start an SSH session and see if you can ping google.co.za

[[File:Nm-connection-editor.png|thumb|none|alt=|nm-connection-editor in Ubuntu 18.10]]
</div>

= Other Connectivity Methods =
There are ways other than WiFi and Ethernet as a means of connecting headlessly (without a keyboard and screen directly attached) to the Pi.

== TTL over USB ==

'''Note:''' The Pi uses 3.3V logic levels. Using a 5V logic module will permanently damage the pins.

This option allows you to use a USB to UART converter such as a FT232R or CP2102. Begin by removing the SD card, and insert it into a computer. Make the following changes on the boot partition:

cmdline.txt: add the following (on the same line)

<pre>console=serial0,115200 </pre>
config.txt

<pre>uart_enable=1
dtoverlay=pi3-disable-bt</pre>

== Using USB connectivity on the Pi 0/0W ==

= Ensuring Connectivity =

Sometimes you may want to debug your connection to the Pi. A fast way to do this is via the ''ping'' command. ''Ping'' sends a packet to a particular host (in this case the Pi), and measures the time taken for a response from that host.

To use the ping command, open a command prompt window or terminal and type the following:

<pre>$ ping 192.168.137.15</pre>
If that host is unreachable (the Pi hasn’t booted yet or is incorrectly configured), a message will show that the host is unreachable. If everything was correctly configured, you should get

<pre>Reply from 192.168.137.15: bytes=32 time<1ns TTL=64</pre>
This means your Pi and computer are both correctly configured. See section [sec:SSH] for configuring your Pi for SSH access.

'''NB:''' Don’t be surprised if you can’t ping a Windows machine from your Pi. Windows blocks the specific type of packet required for a ping in the firewall.

= Networking Protocols=
For a more detailed overview on useful networking protocols, see [[Network Protocols]]
== SSH ==

=== Enabling SSH ===

If you have not connected to your Pi and configured it for SSH, you need to do so. SSH is disabled by default on new installations of Raspbian.

To enable SSH, add it as an enabled service in the <code>raspi-config</code> menu. If you do not have access to the Pi as yet, do the following:

# Insert the SD card into a computer
# Navigate to the BOOT partition
# Create a file called “ssh”. <strong>Note there is no file extension!</strong>
# Your Pi will enable SSH upon next boot

=== Using SSH ===

To use SSH on your Pi, you need to connect to the computer to a network. See Section [sec:NetworkingOnThePi] on various ways that can be done (it is suggested to use Ethernet upon first connection).

Once your Pi is connected to the computer and you have ensured connection (see Section [sec:Connectivity-EnsuringConnectivity]), use can log in to your Pi via SSH. If you are on a Linux-based system, such as Ubuntu or Mac, you should be able to run the following. Note that the default username is “pi” and the default password is “raspberry”.

<pre>$ ssh <username>@192.168.137.15</pre>
If you are on Windows, you may need to use PuTTY. Some instances of windows have SSH in the command line, and you can run the command shown above. But if not, you will need to do the following:

# Open PuTTY
# In the “Hostname” field, enter in “192.168.137.15”
# Click “Open”. A terminal window will be opened. If it is the first time you’re SSH’ing into your Pi on this particular computer, you will be asked about the server fingerprint. Click “Yes” to continue.
# You will be asked for a username and password. The default username is “pi” and the password is “raspberry”.
# You should now successfully connected to your Raspberry Pi via SSH

== VNC ==
To learn about how to install VNC, see
# Ensure the VNC service is enabled on the Pi

#Connect to the Pi through VNC.
# Set your preferred resolution for Raspbian
## In the desktop menu, go to Preferences - Raspberry Pi Configuration and click the “Set Resolution” button.
## Select a more appropriate resolution (1280*720 suggested)
## Select “Okay” and then “Okay”. You will be asked to reboot your Pi, do so.
# Set the VNC resolution
## Through editing /boot/config.txt, uncomment the following lines relating to framebuffer_width and framebuffer_height
## On the desktop on VNC, use the settings. Do this if you have already connected to VNC. This is a little more difficult as it required you to play with windows in order to see the buttons you need.

RaspberryPi:Networking

2020-08-18T12:11:21Z

CRNKEE002: /* Other Connectivity Methods */

[[Category:RaspberryPi]]
There are many ways to interface with the Pi. This page will cover types of network connectivity. For more comprehensive, advanced networking details, see [[RaspberryPi:AdvancedConnectivity]].

= A Brief Overview of Networks =

It is useful to have a basic idea of how networks, IP addresses, and subnets work. For this, it it suggested you read [https://support.microsoft.com/en-za/help/164015/understanding-tcp-ip-addressing-and-subnetting-basics this article] from Microsoft.

= Wireless Connectivity =
WiFi connectivity is a useful way of connecting the Pi to the internet as it enables more portability. You can adjust WiFi Connections either before boot, by creating a <code>wpa_cupplicant.conf</code> file on the boot partition, or while the pi is running, either by editing <code>/etc/wpa/wpa_supplicant.conf</code> directly, or using <code>$ sudo raspi-config</code>. Note that the raspi-config method will not work for Eduroam.

== Simple Wifi Connections ==
If the Pi is up and running and you have access to it, you can run <code>$ sudo raspi-config</code> and enable WiFi using that menu, or editing <code>/etc/wpa/wpa_supplicant.conf</code> directly using an editor such as nano. However if you don't have access, you can create a a <code>wpa_supplicant.conf</code> file on the SD card, on the boot partition while it is plugged into another system.

If editing the wpa_supplicant configuration file, the contents should look something like the following:
<pre>
ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
update_config=1
country=ZA

network={
ssid="<Name of your WiFi network>"
psk="<Password for your WiFi network>"
}
</pre>

== Connecting to Eduroam ==
Connecting to Eduroam requires a fair amount of configuration which depends on your operating system. Generally though, edits to wpa_supplicant.conf and dhcpcd.conf are sufficient. Note that there are new releases of Raspberry Pi OS, and it is unknown if the edits for Buster are still required.

<span class="mw-customtoggle-Eduroam" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-Eduroam" class="mw-collapsible mw-collapsed">
=== Raspbian Buster ===
'''Note:''' There have been updates to the Buster code base, and roll back of wpasupplicant might not be required. However this is currently unable to be tested due to the lockdown. If someone has the chance to test, please update this page accordingly.
These instructions come from [https://www.raspberrypi.org/forums/viewtopic.php?p=1501822#p1501822 here].<br />
Unfortunately, when you use bleeding edge technology, you may end up cutting yourself. Raspbian Buster updates <code>wpa_supplicant</code> to a version that doesn’t have support for the authentication method used by Eduroam. So we need to roll back <code>wpa_supplicant</code> to an older version. Ensure your Pi has internet access through a method such as Ethernet passthrough, and run the following:

<pre>$ sudo apt-get remove wpasupplicant</pre>
Edit /etc/apt/sources.list :

<pre>$ sudo nano /etc/apt/sources.list</pre>
And change

<pre>deb http://raspbian.raspberrypi.org/raspbian/ buster main contrib non-free rpi</pre>
to

<pre>deb http://raspbian.raspberrypi.org/raspbian/ stretch main contrib non-free rpi</pre>
Run

<pre>$ sudo apt-get update
$ sudo apt-get install wpasupplicant</pre>
This will install the correct version of <code>wpa_supplicant</code>. Check that '''version 2.4''' is installed by running

<pre>$ wpa_supplicant -v</pre>
Now, change the sources file back.

<pre>$ sudo nano /etc/apt/sources.list</pre>
And edit the contents to contain

<pre>deb http://raspbian.raspberrypi.org/raspbian/ buster main contrib non-free rpi</pre>
Finally, run

<pre>$ sudo apt-get update</pre>
To update sources The correct version of <code>wpa_supplicant</code> should now be installed, and you can configure your Pi for WiFi as you would if you were using Raspbian Stretch as explained in below.

=== Raspbian Stretch ===

This section provides the instructions on how to configure the Pi to use Eduroam. It is possible to do using the GUI through VNC, but we will not cover that here.

<ol>
<li><p>SSH into your Pi.</p></li>
<li><p>Generate a hash for your password. Take note of it as it is needed in a later step</p>
<pre>
$ echo -n your_uct_password_here | iconv -t utf16le | openssl md4
</pre></li>
<li><p>Open /etc/wpa_supplicant/wpa_supplicant.conf</p>
<pre>$ sudo nano /etc/wpa_supplicant/wpa_supplicant.conf</pre></li>
<li><p>Edit it so it looks as follows:</p>
<pre>
ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
update_config=1
country=ZA

network={
ssid="eduroam"
key_mgmt=WPA-EAP
identity="studentnumber@wf.uct.ac.za"
password=hash:generated_hash_from_earlier
}
</pre></li>
<li><p>Save the file</p></li>
<li><p>Open <code>/etc/dhcpcd.conf</code></p>
<pre> $ sudo nano /etc/dhcpcd.conf</pre></li>
<li><p>Make sure the following lines are in the document:</p>
<pre>interface wlan0
metric 200
</pre></li>
<li><p>Reboot your Pi</p></li>
<li><p>WiFi Generally takes a little longer to initialize than Ethernet, so give it time. You can see if it’s ready by running</p>
<pre>$ ifconfig </pre>
<p>And seeing if an IPv4 address (“inet”) has been given.</p></li>
<li><p>Test your configuration by pinging from the WiFi interface:</p>
<pre>$ ping google.com -I wlan0</pre></li></ol>
</div>

= Ethernet Connectivity =
Ethernet is the physical connection made using a CAT 5 or 6 cable - though there are ways that Ethernet can be mimicked over USB (see Details on the Pi 0 and 0W for more information).

If you're on a private network, connecting your Pi will usually just assign it an IP address and internet connectivity automatically works. If you're on a linux-based system, like Ubuntu, you can use the hostname of the Pi to connect. By default this is "raspberrypi", so you could SSH in using "SSH pi@raspberrypi". However, in most cases, you'll want to know the IP address and assign a static IP address.

== Static IPs ==
Setting a static IP makes it easy to access the Pi and ensures that the IP address of the Pi is always known. In this course, we assign the Pi an IP address of 192.168.137.15. The reason for this is that when using Ethernet Passthrough on Windows, Windows asserts a domain of 192.168.137.x, with the host PC being assigned 192.168.137.1. Keep in mind that all devices will need to be on the same subnet though, so if you're assigning a static IP to be used on your own Ethernet network, you need to know what the subnet of that network is.

If you're connecting your Pi through your desktop, you'll need to assign a static IP to the desktop, too.

== Setting a static IP on your Desktop ==
If you're connecting your Pi through your desktop, you'll need to assign a static IP to the desktop, too. If you're setting a static IP on a Pi that's already connected directly to the network through a router or similar network switch, you can ignore setting a static IP on the computer.

=== Windows ===
<span class="mw-customtoggle-WindowsIP" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-WindowsIP" class="mw-collapsible mw-collapsed">
To change the IP of your Ethernet port on Windows 10, complete the following steps:

* Right click on your network option in Windows taskbar
* Select “Open Network & Internet Settings”, on the lower right hand side of the screen.
* Select “Change Adapted Options”
* Right click on the Ethernet Connection and select “Properties”
* Select “Internet Protocol Version 4 (TCP/IPv4) and click ”Properties"
* Select “Use the following IP address:” and enter in the following options:<br />
- IP Address: 192.168.137.1<br />
- Subnet Mask: 255.255.255.0
* You have successfully changed the IP of the Ethernet card on your computer. It is suggested that you now ensure connectivity by attempting to ping the Pi.

[[File:windowsIPConfig.png|thumb|none|alt=|The IPv4 configuration screen in Windows 10]]
</div>
=== Ubuntu ===
<span class="mw-customtoggle-UbuntuIP" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-UbuntuIP" class="mw-collapsible mw-collapsed">
To change the IP of your Ethernet port on Ubuntu, complete the following steps:

* Click the network interface icon on the status bar and select Wired Settings
* Click the gear button of the interface you’d like to change
* Select the IPv4 Tab, and change the IPv4 method to Manual
* Under “Addresses” enter in the following:<br />
- IP Address: 192.168.137.1<br />
- Subnet Mask: 255.255.255.0
* You can leave Gateway and DNS blank

[[File:Ubuntustaticip.png|thumb|none|alt=|The IPv4 configuration screen in Ubuntu 18.10]]
</div>

== Setting a static IP on the Pi ==
To set a static IP on the Pi, you have multiple options. You can do it before first boot by addling a line to cmdline.txt on the boot partition of the SD card, or once the Pi is running by editing dhcpcd.
Before setting the static IP, ensure you have the correct subdomain, and that you don't assign an IP that another device on the network is using. If you're assinging it a static IP and you have, for example, a router acting as a DHCP server, ensure the IP you assign is outside of DHCP range.

=== From the boot partition ===
<span class="mw-customtoggle-PiStaticBoot" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-PiStaticBoot" class="mw-collapsible mw-collapsed">
<ol>
<li><p>Insert the SD card into your computer and navigate to the BOOT partition</p></li>
<li><p>Open “cmdline.txt” and append the following to the line (don’t create a new line)</p>
<pre> ip=192.168.137.15 </pre>
<p>This tells the Raspberry Pi to configure the Ethernet port to use the IP address 192.168.137.15</p></li>
<li><p>Enable SSH as per Section [sec:SSH].</p></li>
<li><p>You need to configure your PC to use the same subnet as the Pi. To do so, see the information below in the section on Assigning a static IP to the Pi.</p></li></ol>
</div>
=== In dhcpcd (while the Pi is running)===
<span class="mw-customtoggle-PiStaticDHCPCD" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-PiStaticDHCPCD" class="mw-collapsible mw-collapsed">
Once you’ve successfully SSH’d into your Pi, it’s a good idea to configure the networking options in the config files directly. You will need to set a static IP on the computer first if you are SSH'ing through an Ethernet connection.

Use a text editor such as nano to open /etc/dhcpcd.conf as sudo user, and edit it to the following:

<pre># Static IP profile for eth0
profile static_eth0
static ip_address=192.168.137.15/24
static routers=192.168.137.1
static domain_name_servers=192.168.137.1 8.8.8.8

# Ethernet interface configuration
interface eth0
fallback static_eth0

# Wireless configuration
interface wlan0
metric 200</pre>
</div>

== WiFi to Ethernet Passthrough ==
In a situation when you can't or don't want to connect to a WiFi network, but are connected to a computer through an Ethernet port There may be a situation in which you want your Pi to work as an access point rather than using the WiFi interface to provide the Pi with internet access. In this situation, you need to get internet access through the Ethernet port. Before starting, you need to ensure the computer you're using has a static IP assigned. When enabling network sharing on Windows, it automatically assigns 192.168.137.1. Once that's done, complete the following to enable network sharing:

=== Windows ===
<span class="mw-customtoggle-PassthroughWindows" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-PassthroughWindows" class="mw-collapsible mw-collapsed">
# Ensure the Pi is unplugged
# Right click on your network option in Windows taskbar
# Select “Open Network & Internet Settings”, on the lower right hand side of the screen.
# Select “Change Adapted Options”
# Right click on your WiFi network and select “Properties”
# Click the “Sharing” tab, and enable the first checkbox <ref>This setting is what forces us to have to use the subnet 192.168.137.x.</ref>
# Select the Ethernet connection that your Pi will be using in the drop down box (Usually just “Ethernet”, but may be different if there are multiple Ethernet posts on your system)

[[File:Windowspassthrough.png|thumb|none|alt=|Using WiFi to Ethernet passthrough in Windows]]
</div>
=== Ubuntu ===
<span class="mw-customtoggle-PassthroughUbuntu" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-PassthroughUbuntu" class="mw-collapsible mw-collapsed">
# Ensure the Pi is unplugged and turned off.
# Open a terminal and run <code>nm-connection-editor</code>
# Select the wired connection you’d like to share your WiFi to
# Select the IPv4 settings tab
# Under Method, select “Shared to other computers”
# under the IP addresses, click “Add” and enter in an address of 192.168.137.1, and a netmask of 24
# Select “Save”, and close the windows
# Plug in the Pi, start an SSH session and see if you can ping google.co.za

[[File:Nm-connection-editor.png|thumb|none|alt=|nm-connection-editor in Ubuntu 18.10]]
</div>

= Other Connectivity Methods =
There are ways other than WiFi and Ethernet as a means of connecting headlessly (without a keyboard and screen directly attached) to the Pi.

== TTL over USB ==

'''Note:''' The Pi uses 3.3V logic levels. Using a 5V logic module will permanently damage the pins.

This option allows you to use a USB to UART converter such as a FT232R or CP2102. Begin by removing the SD card, and insert it into a computer. Make the following changes on the boot partition:

cmdline.txt: add the following (on the same line)

<pre>console=serial0,115200 </pre>
config.txt

<pre>uart_enable=1
dtoverlay=pi3-disable-bt</pre>

== Using USB connectivity on the Pi 0/ 0W ==

= Ensuring Connectivity =

Sometimes you may want to debug your connection to the Pi. A fast way to do this is via the ''ping'' command. ''Ping'' sends a packet to a particular host (in this case the Pi), and measures the time taken for a response from that host.

To use the ping command, open a command prompt window or terminal and type the following:

<pre>$ ping 192.168.137.15</pre>
If that host is unreachable (the Pi hasn’t booted yet or is incorrectly configured), a message will show that the host is unreachable. If everything was correctly configured, you should get

<pre>Reply from 192.168.137.15: bytes=32 time<1ns TTL=64</pre>
This means your Pi and computer are both correctly configured. See section [sec:SSH] for configuring your Pi for SSH access.

'''NB:''' Don’t be surprised if you can’t ping a Windows machine from your Pi. Windows blocks the specific type of packet required for a ping in the firewall.

= Networking Protocols=
For a more detailed overview on useful networking protocols, see [[Network Protocols]]
== SSH ==

=== Enabling SSH ===

If you have not connected to your Pi and configured it for SSH, you need to do so. SSH is disabled by default on new installations of Raspbian.

To enable SSH, add it as an enabled service in the <code>raspi-config</code> menu. If you do not have access to the Pi as yet, do the following:

# Insert the SD card into a computer
# Navigate to the BOOT partition
# Create a file called “ssh”. <strong>Note there is no file extension!</strong>
# Your Pi will enable SSH upon next boot

=== Using SSH ===

To use SSH on your Pi, you need to connect to the computer to a network. See Section [sec:NetworkingOnThePi] on various ways that can be done (it is suggested to use Ethernet upon first connection).

Once your Pi is connected to the computer and you have ensured connection (see Section [sec:Connectivity-EnsuringConnectivity]), use can log in to your Pi via SSH. If you are on a Linux-based system, such as Ubuntu or Mac, you should be able to run the following. Note that the default username is “pi” and the default password is “raspberry”.

<pre>$ ssh <username>@192.168.137.15</pre>
If you are on Windows, you may need to use PuTTY. Some instances of windows have SSH in the command line, and you can run the command shown above. But if not, you will need to do the following:

# Open PuTTY
# In the “Hostname” field, enter in “192.168.137.15”
# Click “Open”. A terminal window will be opened. If it is the first time you’re SSH’ing into your Pi on this particular computer, you will be asked about the server fingerprint. Click “Yes” to continue.
# You will be asked for a username and password. The default username is “pi” and the password is “raspberry”.
# You should now successfully connected to your Raspberry Pi via SSH

== VNC ==
To learn about how to install VNC, see
# Ensure the VNC service is enabled on the Pi

#Connect to the Pi through VNC.
# Set your preferred resolution for Raspbian
## In the desktop menu, go to Preferences - Raspberry Pi Configuration and click the “Set Resolution” button.
## Select a more appropriate resolution (1280*720 suggested)
## Select “Okay” and then “Okay”. You will be asked to reboot your Pi, do so.
# Set the VNC resolution
## Through editing /boot/config.txt, uncomment the following lines relating to framebuffer_width and framebuffer_height
## On the desktop on VNC, use the settings. Do this if you have already connected to VNC. This is a little more difficult as it required you to play with windows in order to see the buttons you need.

RaspberryPi:Networking

2020-08-18T12:10:45Z

CRNKEE002:

[[Category:RaspberryPi]]
There are many ways to interface with the Pi. This page will cover types of network connectivity. For more comprehensive, advanced networking details, see [[RaspberryPi:AdvancedConnectivity]].

= A Brief Overview of Networks =

It is useful to have a basic idea of how networks, IP addresses, and subnets work. For this, it it suggested you read [https://support.microsoft.com/en-za/help/164015/understanding-tcp-ip-addressing-and-subnetting-basics this article] from Microsoft.

= Wireless Connectivity =
WiFi connectivity is a useful way of connecting the Pi to the internet as it enables more portability. You can adjust WiFi Connections either before boot, by creating a <code>wpa_cupplicant.conf</code> file on the boot partition, or while the pi is running, either by editing <code>/etc/wpa/wpa_supplicant.conf</code> directly, or using <code>$ sudo raspi-config</code>. Note that the raspi-config method will not work for Eduroam.

== Simple Wifi Connections ==
If the Pi is up and running and you have access to it, you can run <code>$ sudo raspi-config</code> and enable WiFi using that menu, or editing <code>/etc/wpa/wpa_supplicant.conf</code> directly using an editor such as nano. However if you don't have access, you can create a a <code>wpa_supplicant.conf</code> file on the SD card, on the boot partition while it is plugged into another system.

If editing the wpa_supplicant configuration file, the contents should look something like the following:
<pre>
ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
update_config=1
country=ZA

network={
ssid="<Name of your WiFi network>"
psk="<Password for your WiFi network>"
}
</pre>

== Connecting to Eduroam ==
Connecting to Eduroam requires a fair amount of configuration which depends on your operating system. Generally though, edits to wpa_supplicant.conf and dhcpcd.conf are sufficient. Note that there are new releases of Raspberry Pi OS, and it is unknown if the edits for Buster are still required.

<span class="mw-customtoggle-Eduroam" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-Eduroam" class="mw-collapsible mw-collapsed">
=== Raspbian Buster ===
'''Note:''' There have been updates to the Buster code base, and roll back of wpasupplicant might not be required. However this is currently unable to be tested due to the lockdown. If someone has the chance to test, please update this page accordingly.
These instructions come from [https://www.raspberrypi.org/forums/viewtopic.php?p=1501822#p1501822 here].<br />
Unfortunately, when you use bleeding edge technology, you may end up cutting yourself. Raspbian Buster updates <code>wpa_supplicant</code> to a version that doesn’t have support for the authentication method used by Eduroam. So we need to roll back <code>wpa_supplicant</code> to an older version. Ensure your Pi has internet access through a method such as Ethernet passthrough, and run the following:

<pre>$ sudo apt-get remove wpasupplicant</pre>
Edit /etc/apt/sources.list :

<pre>$ sudo nano /etc/apt/sources.list</pre>
And change

<pre>deb http://raspbian.raspberrypi.org/raspbian/ buster main contrib non-free rpi</pre>
to

<pre>deb http://raspbian.raspberrypi.org/raspbian/ stretch main contrib non-free rpi</pre>
Run

<pre>$ sudo apt-get update
$ sudo apt-get install wpasupplicant</pre>
This will install the correct version of <code>wpa_supplicant</code>. Check that '''version 2.4''' is installed by running

<pre>$ wpa_supplicant -v</pre>
Now, change the sources file back.

<pre>$ sudo nano /etc/apt/sources.list</pre>
And edit the contents to contain

<pre>deb http://raspbian.raspberrypi.org/raspbian/ buster main contrib non-free rpi</pre>
Finally, run

<pre>$ sudo apt-get update</pre>
To update sources The correct version of <code>wpa_supplicant</code> should now be installed, and you can configure your Pi for WiFi as you would if you were using Raspbian Stretch as explained in below.

=== Raspbian Stretch ===

This section provides the instructions on how to configure the Pi to use Eduroam. It is possible to do using the GUI through VNC, but we will not cover that here.

<ol>
<li><p>SSH into your Pi.</p></li>
<li><p>Generate a hash for your password. Take note of it as it is needed in a later step</p>
<pre>
$ echo -n your_uct_password_here | iconv -t utf16le | openssl md4
</pre></li>
<li><p>Open /etc/wpa_supplicant/wpa_supplicant.conf</p>
<pre>$ sudo nano /etc/wpa_supplicant/wpa_supplicant.conf</pre></li>
<li><p>Edit it so it looks as follows:</p>
<pre>
ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
update_config=1
country=ZA

network={
ssid="eduroam"
key_mgmt=WPA-EAP
identity="studentnumber@wf.uct.ac.za"
password=hash:generated_hash_from_earlier
}
</pre></li>
<li><p>Save the file</p></li>
<li><p>Open <code>/etc/dhcpcd.conf</code></p>
<pre> $ sudo nano /etc/dhcpcd.conf</pre></li>
<li><p>Make sure the following lines are in the document:</p>
<pre>interface wlan0
metric 200
</pre></li>
<li><p>Reboot your Pi</p></li>
<li><p>WiFi Generally takes a little longer to initialize than Ethernet, so give it time. You can see if it’s ready by running</p>
<pre>$ ifconfig </pre>
<p>And seeing if an IPv4 address (“inet”) has been given.</p></li>
<li><p>Test your configuration by pinging from the WiFi interface:</p>
<pre>$ ping google.com -I wlan0</pre></li></ol>
</div>

= Ethernet Connectivity =
Ethernet is the physical connection made using a CAT 5 or 6 cable - though there are ways that Ethernet can be mimicked over USB (see Details on the Pi 0 and 0W for more information).

If you're on a private network, connecting your Pi will usually just assign it an IP address and internet connectivity automatically works. If you're on a linux-based system, like Ubuntu, you can use the hostname of the Pi to connect. By default this is "raspberrypi", so you could SSH in using "SSH pi@raspberrypi". However, in most cases, you'll want to know the IP address and assign a static IP address.

== Static IPs ==
Setting a static IP makes it easy to access the Pi and ensures that the IP address of the Pi is always known. In this course, we assign the Pi an IP address of 192.168.137.15. The reason for this is that when using Ethernet Passthrough on Windows, Windows asserts a domain of 192.168.137.x, with the host PC being assigned 192.168.137.1. Keep in mind that all devices will need to be on the same subnet though, so if you're assigning a static IP to be used on your own Ethernet network, you need to know what the subnet of that network is.

If you're connecting your Pi through your desktop, you'll need to assign a static IP to the desktop, too.

== Setting a static IP on your Desktop ==
If you're connecting your Pi through your desktop, you'll need to assign a static IP to the desktop, too. If you're setting a static IP on a Pi that's already connected directly to the network through a router or similar network switch, you can ignore setting a static IP on the computer.

=== Windows ===
<span class="mw-customtoggle-WindowsIP" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-WindowsIP" class="mw-collapsible mw-collapsed">
To change the IP of your Ethernet port on Windows 10, complete the following steps:

* Right click on your network option in Windows taskbar
* Select “Open Network & Internet Settings”, on the lower right hand side of the screen.
* Select “Change Adapted Options”
* Right click on the Ethernet Connection and select “Properties”
* Select “Internet Protocol Version 4 (TCP/IPv4) and click ”Properties"
* Select “Use the following IP address:” and enter in the following options:<br />
- IP Address: 192.168.137.1<br />
- Subnet Mask: 255.255.255.0
* You have successfully changed the IP of the Ethernet card on your computer. It is suggested that you now ensure connectivity by attempting to ping the Pi.

[[File:windowsIPConfig.png|thumb|none|alt=|The IPv4 configuration screen in Windows 10]]
</div>
=== Ubuntu ===
<span class="mw-customtoggle-UbuntuIP" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-UbuntuIP" class="mw-collapsible mw-collapsed">
To change the IP of your Ethernet port on Ubuntu, complete the following steps:

* Click the network interface icon on the status bar and select Wired Settings
* Click the gear button of the interface you’d like to change
* Select the IPv4 Tab, and change the IPv4 method to Manual
* Under “Addresses” enter in the following:<br />
- IP Address: 192.168.137.1<br />
- Subnet Mask: 255.255.255.0
* You can leave Gateway and DNS blank

[[File:Ubuntustaticip.png|thumb|none|alt=|The IPv4 configuration screen in Ubuntu 18.10]]
</div>

== Setting a static IP on the Pi ==
To set a static IP on the Pi, you have multiple options. You can do it before first boot by addling a line to cmdline.txt on the boot partition of the SD card, or once the Pi is running by editing dhcpcd.
Before setting the static IP, ensure you have the correct subdomain, and that you don't assign an IP that another device on the network is using. If you're assinging it a static IP and you have, for example, a router acting as a DHCP server, ensure the IP you assign is outside of DHCP range.

=== From the boot partition ===
<span class="mw-customtoggle-PiStaticBoot" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-PiStaticBoot" class="mw-collapsible mw-collapsed">
<ol>
<li><p>Insert the SD card into your computer and navigate to the BOOT partition</p></li>
<li><p>Open “cmdline.txt” and append the following to the line (don’t create a new line)</p>
<pre> ip=192.168.137.15 </pre>
<p>This tells the Raspberry Pi to configure the Ethernet port to use the IP address 192.168.137.15</p></li>
<li><p>Enable SSH as per Section [sec:SSH].</p></li>
<li><p>You need to configure your PC to use the same subnet as the Pi. To do so, see the information below in the section on Assigning a static IP to the Pi.</p></li></ol>
</div>
=== In dhcpcd (while the Pi is running)===
<span class="mw-customtoggle-PiStaticDHCPCD" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-PiStaticDHCPCD" class="mw-collapsible mw-collapsed">
Once you’ve successfully SSH’d into your Pi, it’s a good idea to configure the networking options in the config files directly. You will need to set a static IP on the computer first if you are SSH'ing through an Ethernet connection.

Use a text editor such as nano to open /etc/dhcpcd.conf as sudo user, and edit it to the following:

<pre># Static IP profile for eth0
profile static_eth0
static ip_address=192.168.137.15/24
static routers=192.168.137.1
static domain_name_servers=192.168.137.1 8.8.8.8

# Ethernet interface configuration
interface eth0
fallback static_eth0

# Wireless configuration
interface wlan0
metric 200</pre>
</div>

== WiFi to Ethernet Passthrough ==
In a situation when you can't or don't want to connect to a WiFi network, but are connected to a computer through an Ethernet port There may be a situation in which you want your Pi to work as an access point rather than using the WiFi interface to provide the Pi with internet access. In this situation, you need to get internet access through the Ethernet port. Before starting, you need to ensure the computer you're using has a static IP assigned. When enabling network sharing on Windows, it automatically assigns 192.168.137.1. Once that's done, complete the following to enable network sharing:

=== Windows ===
<span class="mw-customtoggle-PassthroughWindows" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-PassthroughWindows" class="mw-collapsible mw-collapsed">
# Ensure the Pi is unplugged
# Right click on your network option in Windows taskbar
# Select “Open Network & Internet Settings”, on the lower right hand side of the screen.
# Select “Change Adapted Options”
# Right click on your WiFi network and select “Properties”
# Click the “Sharing” tab, and enable the first checkbox <ref>This setting is what forces us to have to use the subnet 192.168.137.x.</ref>
# Select the Ethernet connection that your Pi will be using in the drop down box (Usually just “Ethernet”, but may be different if there are multiple Ethernet posts on your system)

[[File:Windowspassthrough.png|thumb|none|alt=|Using WiFi to Ethernet passthrough in Windows]]
</div>
=== Ubuntu ===
<span class="mw-customtoggle-PassthroughUbuntu" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-PassthroughUbuntu" class="mw-collapsible mw-collapsed">
# Ensure the Pi is unplugged and turned off.
# Open a terminal and run <code>nm-connection-editor</code>
# Select the wired connection you’d like to share your WiFi to
# Select the IPv4 settings tab
# Under Method, select “Shared to other computers”
# under the IP addresses, click “Add” and enter in an address of 192.168.137.1, and a netmask of 24
# Select “Save”, and close the windows
# Plug in the Pi, start an SSH session and see if you can ping google.co.za

[[File:Nm-connection-editor.png|thumb|none|alt=|nm-connection-editor in Ubuntu 18.10]]
</div>

= Other Connectivity Methods =
There are ways other than WiFi and Ethernet as a means of connecting headlessly (without a keyboard and screen directly attached) to the Pi.

= Ensuring Connectivity =

Sometimes you may want to debug your connection to the Pi. A fast way to do this is via the ''ping'' command. ''Ping'' sends a packet to a particular host (in this case the Pi), and measures the time taken for a response from that host.

To use the ping command, open a command prompt window or terminal and type the following:

<pre>$ ping 192.168.137.15</pre>
If that host is unreachable (the Pi hasn’t booted yet or is incorrectly configured), a message will show that the host is unreachable. If everything was correctly configured, you should get

<pre>Reply from 192.168.137.15: bytes=32 time<1ns TTL=64</pre>
This means your Pi and computer are both correctly configured. See section [sec:SSH] for configuring your Pi for SSH access.

'''NB:''' Don’t be surprised if you can’t ping a Windows machine from your Pi. Windows blocks the specific type of packet required for a ping in the firewall.

= Networking Protocols=
For a more detailed overview on useful networking protocols, see [[Network Protocols]]
== SSH ==

=== Enabling SSH ===

If you have not connected to your Pi and configured it for SSH, you need to do so. SSH is disabled by default on new installations of Raspbian.

To enable SSH, add it as an enabled service in the <code>raspi-config</code> menu. If you do not have access to the Pi as yet, do the following:

# Insert the SD card into a computer
# Navigate to the BOOT partition
# Create a file called “ssh”. <strong>Note there is no file extension!</strong>
# Your Pi will enable SSH upon next boot

=== Using SSH ===

To use SSH on your Pi, you need to connect to the computer to a network. See Section [sec:NetworkingOnThePi] on various ways that can be done (it is suggested to use Ethernet upon first connection).

Once your Pi is connected to the computer and you have ensured connection (see Section [sec:Connectivity-EnsuringConnectivity]), use can log in to your Pi via SSH. If you are on a Linux-based system, such as Ubuntu or Mac, you should be able to run the following. Note that the default username is “pi” and the default password is “raspberry”.

<pre>$ ssh <username>@192.168.137.15</pre>
If you are on Windows, you may need to use PuTTY. Some instances of windows have SSH in the command line, and you can run the command shown above. But if not, you will need to do the following:

# Open PuTTY
# In the “Hostname” field, enter in “192.168.137.15”
# Click “Open”. A terminal window will be opened. If it is the first time you’re SSH’ing into your Pi on this particular computer, you will be asked about the server fingerprint. Click “Yes” to continue.
# You will be asked for a username and password. The default username is “pi” and the password is “raspberry”.
# You should now successfully connected to your Raspberry Pi via SSH

== VNC ==
To learn about how to install VNC, see
# Ensure the VNC service is enabled on the Pi

#Connect to the Pi through VNC.
# Set your preferred resolution for Raspbian
## In the desktop menu, go to Preferences - Raspberry Pi Configuration and click the “Set Resolution” button.
## Select a more appropriate resolution (1280*720 suggested)
## Select “Okay” and then “Okay”. You will be asked to reboot your Pi, do so.
# Set the VNC resolution
## Through editing /boot/config.txt, uncomment the following lines relating to framebuffer_width and framebuffer_height
## On the desktop on VNC, use the settings. Do this if you have already connected to VNC. This is a little more difficult as it required you to play with windows in order to see the buttons you need.

RaspberryPi:Networking

2020-08-18T12:06:52Z

CRNKEE002: /* Setting a static IP on the Pi */

[[Category:RaspberryPi]]
There are many ways to interface with the Pi. This page will cover types of network connectivity. For more comprehensive, advanced networking details, see [[RaspberryPi:AdvancedConnectivity]].

= A Brief Overview of Networks =

It is useful to have a basic idea of how networks, IP addresses, and subnets work. For this, it it suggested you read [https://support.microsoft.com/en-za/help/164015/understanding-tcp-ip-addressing-and-subnetting-basics this article] from Microsoft.

= Wireless Connectivity =
WiFi connectivity is a useful way of connecting the Pi to the internet as it enables more portability. You can adjust WiFi Connections either before boot, by creating a <code>wpa_cupplicant.conf</code> file on the boot partition, or while the pi is running, either by editing <code>/etc/wpa/wpa_supplicant.conf</code> directly, or using <code>$ sudo raspi-config</code>. Note that the raspi-config method will not work for Eduroam.

== Simple Wifi Connections ==
If the Pi is up and running and you have access to it, you can run <code>$ sudo raspi-config</code> and enable WiFi using that menu, or editing <code>/etc/wpa/wpa_supplicant.conf</code> directly using an editor such as nano. However if you don't have access, you can create a a <code>wpa_supplicant.conf</code> file on the SD card, on the boot partition while it is plugged into another system.

If editing the wpa_supplicant configuration file, the contents should look something like the following:
<pre>
ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
update_config=1
country=ZA

network={
ssid="<Name of your WiFi network>"
psk="<Password for your WiFi network>"
}
</pre>

== Connecting to Eduroam ==
Connecting to Eduroam requires a fair amount of configuration which depends on your operating system. Generally though, edits to wpa_supplicant.conf and dhcpcd.conf are sufficient. Note that there are new releases of Raspberry Pi OS, and it is unknown if the edits for Buster are still required.

<span class="mw-customtoggle-Eduroam" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-Eduroam" class="mw-collapsible mw-collapsed">
=== Raspbian Buster ===
'''Note:''' There have been updates to the Buster code base, and roll back of wpasupplicant might not be required. However this is currently unable to be tested due to the lockdown. If someone has the chance to test, please update this page accordingly.
These instructions come from [https://www.raspberrypi.org/forums/viewtopic.php?p=1501822#p1501822 here].<br />
Unfortunately, when you use bleeding edge technology, you may end up cutting yourself. Raspbian Buster updates <code>wpa_supplicant</code> to a version that doesn’t have support for the authentication method used by Eduroam. So we need to roll back <code>wpa_supplicant</code> to an older version. Ensure your Pi has internet access through a method such as Ethernet passthrough, and run the following:

<pre>$ sudo apt-get remove wpasupplicant</pre>
Edit /etc/apt/sources.list :

<pre>$ sudo nano /etc/apt/sources.list</pre>
And change

<pre>deb http://raspbian.raspberrypi.org/raspbian/ buster main contrib non-free rpi</pre>
to

<pre>deb http://raspbian.raspberrypi.org/raspbian/ stretch main contrib non-free rpi</pre>
Run

<pre>$ sudo apt-get update
$ sudo apt-get install wpasupplicant</pre>
This will install the correct version of <code>wpa_supplicant</code>. Check that '''version 2.4''' is installed by running

<pre>$ wpa_supplicant -v</pre>
Now, change the sources file back.

<pre>$ sudo nano /etc/apt/sources.list</pre>
And edit the contents to contain

<pre>deb http://raspbian.raspberrypi.org/raspbian/ buster main contrib non-free rpi</pre>
Finally, run

<pre>$ sudo apt-get update</pre>
To update sources The correct version of <code>wpa_supplicant</code> should now be installed, and you can configure your Pi for WiFi as you would if you were using Raspbian Stretch as explained in below.

=== Raspbian Stretch ===

This section provides the instructions on how to configure the Pi to use Eduroam. It is possible to do using the GUI through VNC, but we will not cover that here.

<ol>
<li><p>SSH into your Pi.</p></li>
<li><p>Generate a hash for your password. Take note of it as it is needed in a later step</p>
<pre>
$ echo -n your_uct_password_here | iconv -t utf16le | openssl md4
</pre></li>
<li><p>Open /etc/wpa_supplicant/wpa_supplicant.conf</p>
<pre>$ sudo nano /etc/wpa_supplicant/wpa_supplicant.conf</pre></li>
<li><p>Edit it so it looks as follows:</p>
<pre>
ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
update_config=1
country=ZA

network={
ssid="eduroam"
key_mgmt=WPA-EAP
identity="studentnumber@wf.uct.ac.za"
password=hash:generated_hash_from_earlier
}
</pre></li>
<li><p>Save the file</p></li>
<li><p>Open <code>/etc/dhcpcd.conf</code></p>
<pre> $ sudo nano /etc/dhcpcd.conf</pre></li>
<li><p>Make sure the following lines are in the document:</p>
<pre>interface wlan0
metric 200
</pre></li>
<li><p>Reboot your Pi</p></li>
<li><p>WiFi Generally takes a little longer to initialize than Ethernet, so give it time. You can see if it’s ready by running</p>
<pre>$ ifconfig </pre>
<p>And seeing if an IPv4 address (“inet”) has been given.</p></li>
<li><p>Test your configuration by pinging from the WiFi interface:</p>
<pre>$ ping google.com -I wlan0</pre></li></ol>
</div>

= Ethernet Connectivity =
Ethernet is the physical connection made using a CAT 5 or 6 cable - though there are ways that Ethernet can be mimicked over USB (see Details on the Pi 0 and 0W for more information).

If you're on a private network, connecting your Pi will usually just assign it an IP address and internet connectivity automatically works. If you're on a linux-based system, like Ubuntu, you can use the hostname of the Pi to connect. By default this is "raspberrypi", so you could SSH in using "SSH pi@raspberrypi". However, in most cases, you'll want to know the IP address and assign a static IP address.

== Static IPs ==
Setting a static IP makes it easy to access the Pi and ensures that the IP address of the Pi is always known. In this course, we assign the Pi an IP address of 192.168.137.15. The reason for this is that when using Ethernet Passthrough on Windows, Windows asserts a domain of 192.168.137.x, with the host PC being assigned 192.168.137.1. Keep in mind that all devices will need to be on the same subnet though, so if you're assigning a static IP to be used on your own Ethernet network, you need to know what the subnet of that network is.

If you're connecting your Pi through your desktop, you'll need to assign a static IP to the desktop, too.

== Setting a static IP on your Desktop ==
If you're connecting your Pi through your desktop, you'll need to assign a static IP to the desktop, too. If you're setting a static IP on a Pi that's already connected directly to the network through a router or similar network switch, you can ignore setting a static IP on the computer.

=== Windows ===
<span class="mw-customtoggle-WindowsIP" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-WindowsIP" class="mw-collapsible mw-collapsed">
To change the IP of your Ethernet port on Windows 10, complete the following steps:

* Right click on your network option in Windows taskbar
* Select “Open Network & Internet Settings”, on the lower right hand side of the screen.
* Select “Change Adapted Options”
* Right click on the Ethernet Connection and select “Properties”
* Select “Internet Protocol Version 4 (TCP/IPv4) and click ”Properties"
* Select “Use the following IP address:” and enter in the following options:<br />
- IP Address: 192.168.137.1<br />
- Subnet Mask: 255.255.255.0
* You have successfully changed the IP of the Ethernet card on your computer. It is suggested that you now ensure connectivity by attempting to ping the Pi.

[[File:windowsIPConfig.png|thumb|none|alt=|The IPv4 configuration screen in Windows 10]]
</div>
=== Ubuntu ===
<span class="mw-customtoggle-UbuntuIP" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-UbuntuIP" class="mw-collapsible mw-collapsed">
To change the IP of your Ethernet port on Ubuntu, complete the following steps:

* Click the network interface icon on the status bar and select Wired Settings
* Click the gear button of the interface you’d like to change
* Select the IPv4 Tab, and change the IPv4 method to Manual
* Under “Addresses” enter in the following:<br />
- IP Address: 192.168.137.1<br />
- Subnet Mask: 255.255.255.0
* You can leave Gateway and DNS blank

[[File:Ubuntustaticip.png|thumb|none|alt=|The IPv4 configuration screen in Ubuntu 18.10]]
</div>

== Setting a static IP on the Pi ==
To set a static IP on the Pi, you have multiple options. You can do it before first boot by addling a line to cmdline.txt on the boot partition of the SD card, or once the Pi is running by editing dhcpcd.
Before setting the static IP, ensure you have the correct subdomain, and that you don't assign an IP that another device on the network is using. If you're assinging it a static IP and you have, for example, a router acting as a DHCP server, ensure the IP you assign is outside of DHCP range.

=== From the boot partition ===
<span class="mw-customtoggle-PiStaticBoot" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-PiStaticBoot" class="mw-collapsible mw-collapsed">
<ol>
<li><p>Insert the SD card into your computer and navigate to the BOOT partition</p></li>
<li><p>Open “cmdline.txt” and append the following to the line (don’t create a new line)</p>
<pre> ip=192.168.137.15 </pre>
<p>This tells the Raspberry Pi to configure the Ethernet port to use the IP address 192.168.137.15</p></li>
<li><p>Enable SSH as per Section [sec:SSH].</p></li>
<li><p>You need to configure your PC to use the same subnet as the Pi. To do so, see the information below in the section on Assigning a static IP to the Pi.</p></li></ol>
</div>
=== In dhcpcd (while the Pi is running)===
<span class="mw-customtoggle-PiStaticDHCPCD" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-PiStaticDHCPCD" class="mw-collapsible mw-collapsed">
Once you’ve successfully SSH’d into your Pi, it’s a good idea to configure the networking options in the config files directly. You will need to set a static IP on the computer first if you are SSH'ing through an Ethernet connection.

Use a text editor such as nano to open /etc/dhcpcd.conf as sudo user, and edit it to the following:

<pre># Static IP profile for eth0
profile static_eth0
static ip_address=192.168.137.15/24
static routers=192.168.137.1
static domain_name_servers=192.168.137.1 8.8.8.8

# Ethernet interface configuration
interface eth0
fallback static_eth0

# Wireless configuration
interface wlan0
metric 200</pre>
</div>

== WiFi to Ethernet Passthrough ==
In a situation when you can't or don't want to connect to a WiFi network, but are connected to a computer through an Ethernet port There may be a situation in which you want your Pi to work as an access point rather than using the WiFi interface to provide the Pi with internet access. In this situation, you need to get internet access through the Ethernet port. Before starting, you need to ensure the computer you're using has a static IP assigned. When enabling network sharing on Windows, it automatically assigns 192.168.137.1. Once that's done, complete the following to enable network sharing:

=== Windows ===
<span class="mw-customtoggle-PassthroughWindows" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-PassthroughWindows" class="mw-collapsible mw-collapsed">
# Ensure the Pi is unplugged
# Right click on your network option in Windows taskbar
# Select “Open Network & Internet Settings”, on the lower right hand side of the screen.
# Select “Change Adapted Options”
# Right click on your WiFi network and select “Properties”
# Click the “Sharing” tab, and enable the first checkbox <ref>This setting is what forces us to have to use the subnet 192.168.137.x.</ref>
# Select the Ethernet connection that your Pi will be using in the drop down box (Usually just “Ethernet”, but may be different if there are multiple Ethernet posts on your system)

[[File:Windowspassthrough.png|thumb|none|alt=|Using WiFi to Ethernet passthrough in Windows]]
</div>
=== Ubuntu ===
<span class="mw-customtoggle-PassthroughUbuntu" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-PassthroughUbuntu" class="mw-collapsible mw-collapsed">
# Ensure the Pi is unplugged and turned off.
# Open a terminal and run <code>nm-connection-editor</code>
# Select the wired connection you’d like to share your WiFi to
# Select the IPv4 settings tab
# Under Method, select “Shared to other computers”
# under the IP addresses, click “Add” and enter in an address of 192.168.137.1, and a netmask of 24
# Select “Save”, and close the windows
# Plug in the Pi, start an SSH session and see if you can ping google.co.za

[[File:Nm-connection-editor.png|thumb|none|alt=|nm-connection-editor in Ubuntu 18.10]]
</div>

= Ensuring Connectivity =

Sometimes you may want to debug your connection to the Pi. A fast way to do this is via the ''ping'' command. ''Ping'' sends a packet to a particular host (in this case the Pi), and measures the time taken for a response from that host.

To use the ping command, open a command prompt window or terminal and type the following:

<pre>$ ping 192.168.137.15</pre>
If that host is unreachable (the Pi hasn’t booted yet or is incorrectly configured), a message will show that the host is unreachable. If everything was correctly configured, you should get

<pre>Reply from 192.168.137.15: bytes=32 time<1ns TTL=64</pre>
This means your Pi and computer are both correctly configured. See section [sec:SSH] for configuring your Pi for SSH access.

'''NB:''' Don’t be surprised if you can’t ping a Windows machine from your Pi. Windows blocks the specific type of packet required for a ping in the firewall.

= Networking Protocols=
For a more detailed overview on useful networking protocols, see [[Network Protocols]]
== SSH ==

=== Enabling SSH ===

If you have not connected to your Pi and configured it for SSH, you need to do so. SSH is disabled by default on new installations of Raspbian.

To enable SSH, add it as an enabled service in the <code>raspi-config</code> menu. If you do not have access to the Pi as yet, do the following:

# Insert the SD card into a computer
# Navigate to the BOOT partition
# Create a file called “ssh”. <strong>Note there is no file extension!</strong>
# Your Pi will enable SSH upon next boot

=== Using SSH ===

To use SSH on your Pi, you need to connect to the computer to a network. See Section [sec:NetworkingOnThePi] on various ways that can be done (it is suggested to use Ethernet upon first connection).

Once your Pi is connected to the computer and you have ensured connection (see Section [sec:Connectivity-EnsuringConnectivity]), use can log in to your Pi via SSH. If you are on a Linux-based system, such as Ubuntu or Mac, you should be able to run the following. Note that the default username is “pi” and the default password is “raspberry”.

<pre>$ ssh <username>@192.168.137.15</pre>
If you are on Windows, you may need to use PuTTY. Some instances of windows have SSH in the command line, and you can run the command shown above. But if not, you will need to do the following:

# Open PuTTY
# In the “Hostname” field, enter in “192.168.137.15”
# Click “Open”. A terminal window will be opened. If it is the first time you’re SSH’ing into your Pi on this particular computer, you will be asked about the server fingerprint. Click “Yes” to continue.
# You will be asked for a username and password. The default username is “pi” and the password is “raspberry”.
# You should now successfully connected to your Raspberry Pi via SSH

== VNC ==
To learn about how to install VNC, see
# Ensure the VNC service is enabled on the Pi

#Connect to the Pi through VNC.
# Set your preferred resolution for Raspbian
## In the desktop menu, go to Preferences - Raspberry Pi Configuration and click the “Set Resolution” button.
## Select a more appropriate resolution (1280*720 suggested)
## Select “Okay” and then “Okay”. You will be asked to reboot your Pi, do so.
# Set the VNC resolution
## Through editing /boot/config.txt, uncomment the following lines relating to framebuffer_width and framebuffer_height
## On the desktop on VNC, use the settings. Do this if you have already connected to VNC. This is a little more difficult as it required you to play with windows in order to see the buttons you need.

RaspberryPi:Networking

2020-08-18T12:05:39Z

CRNKEE002: /* Setting a static IP on your Desktop */

[[Category:RaspberryPi]]
There are many ways to interface with the Pi. This page will cover types of network connectivity. For more comprehensive, advanced networking details, see [[RaspberryPi:AdvancedConnectivity]].

= A Brief Overview of Networks =

It is useful to have a basic idea of how networks, IP addresses, and subnets work. For this, it it suggested you read [https://support.microsoft.com/en-za/help/164015/understanding-tcp-ip-addressing-and-subnetting-basics this article] from Microsoft.

= Wireless Connectivity =
WiFi connectivity is a useful way of connecting the Pi to the internet as it enables more portability. You can adjust WiFi Connections either before boot, by creating a <code>wpa_cupplicant.conf</code> file on the boot partition, or while the pi is running, either by editing <code>/etc/wpa/wpa_supplicant.conf</code> directly, or using <code>$ sudo raspi-config</code>. Note that the raspi-config method will not work for Eduroam.

== Simple Wifi Connections ==
If the Pi is up and running and you have access to it, you can run <code>$ sudo raspi-config</code> and enable WiFi using that menu, or editing <code>/etc/wpa/wpa_supplicant.conf</code> directly using an editor such as nano. However if you don't have access, you can create a a <code>wpa_supplicant.conf</code> file on the SD card, on the boot partition while it is plugged into another system.

If editing the wpa_supplicant configuration file, the contents should look something like the following:
<pre>
ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
update_config=1
country=ZA

network={
ssid="<Name of your WiFi network>"
psk="<Password for your WiFi network>"
}
</pre>

== Connecting to Eduroam ==
Connecting to Eduroam requires a fair amount of configuration which depends on your operating system. Generally though, edits to wpa_supplicant.conf and dhcpcd.conf are sufficient. Note that there are new releases of Raspberry Pi OS, and it is unknown if the edits for Buster are still required.

<span class="mw-customtoggle-Eduroam" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-Eduroam" class="mw-collapsible mw-collapsed">
=== Raspbian Buster ===
'''Note:''' There have been updates to the Buster code base, and roll back of wpasupplicant might not be required. However this is currently unable to be tested due to the lockdown. If someone has the chance to test, please update this page accordingly.
These instructions come from [https://www.raspberrypi.org/forums/viewtopic.php?p=1501822#p1501822 here].<br />
Unfortunately, when you use bleeding edge technology, you may end up cutting yourself. Raspbian Buster updates <code>wpa_supplicant</code> to a version that doesn’t have support for the authentication method used by Eduroam. So we need to roll back <code>wpa_supplicant</code> to an older version. Ensure your Pi has internet access through a method such as Ethernet passthrough, and run the following:

<pre>$ sudo apt-get remove wpasupplicant</pre>
Edit /etc/apt/sources.list :

<pre>$ sudo nano /etc/apt/sources.list</pre>
And change

<pre>deb http://raspbian.raspberrypi.org/raspbian/ buster main contrib non-free rpi</pre>
to

<pre>deb http://raspbian.raspberrypi.org/raspbian/ stretch main contrib non-free rpi</pre>
Run

<pre>$ sudo apt-get update
$ sudo apt-get install wpasupplicant</pre>
This will install the correct version of <code>wpa_supplicant</code>. Check that '''version 2.4''' is installed by running

<pre>$ wpa_supplicant -v</pre>
Now, change the sources file back.

<pre>$ sudo nano /etc/apt/sources.list</pre>
And edit the contents to contain

<pre>deb http://raspbian.raspberrypi.org/raspbian/ buster main contrib non-free rpi</pre>
Finally, run

<pre>$ sudo apt-get update</pre>
To update sources The correct version of <code>wpa_supplicant</code> should now be installed, and you can configure your Pi for WiFi as you would if you were using Raspbian Stretch as explained in below.

=== Raspbian Stretch ===

This section provides the instructions on how to configure the Pi to use Eduroam. It is possible to do using the GUI through VNC, but we will not cover that here.

<ol>
<li><p>SSH into your Pi.</p></li>
<li><p>Generate a hash for your password. Take note of it as it is needed in a later step</p>
<pre>
$ echo -n your_uct_password_here | iconv -t utf16le | openssl md4
</pre></li>
<li><p>Open /etc/wpa_supplicant/wpa_supplicant.conf</p>
<pre>$ sudo nano /etc/wpa_supplicant/wpa_supplicant.conf</pre></li>
<li><p>Edit it so it looks as follows:</p>
<pre>
ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
update_config=1
country=ZA

network={
ssid="eduroam"
key_mgmt=WPA-EAP
identity="studentnumber@wf.uct.ac.za"
password=hash:generated_hash_from_earlier
}
</pre></li>
<li><p>Save the file</p></li>
<li><p>Open <code>/etc/dhcpcd.conf</code></p>
<pre> $ sudo nano /etc/dhcpcd.conf</pre></li>
<li><p>Make sure the following lines are in the document:</p>
<pre>interface wlan0
metric 200
</pre></li>
<li><p>Reboot your Pi</p></li>
<li><p>WiFi Generally takes a little longer to initialize than Ethernet, so give it time. You can see if it’s ready by running</p>
<pre>$ ifconfig </pre>
<p>And seeing if an IPv4 address (“inet”) has been given.</p></li>
<li><p>Test your configuration by pinging from the WiFi interface:</p>
<pre>$ ping google.com -I wlan0</pre></li></ol>
</div>

= Ethernet Connectivity =
Ethernet is the physical connection made using a CAT 5 or 6 cable - though there are ways that Ethernet can be mimicked over USB (see Details on the Pi 0 and 0W for more information).

If you're on a private network, connecting your Pi will usually just assign it an IP address and internet connectivity automatically works. If you're on a linux-based system, like Ubuntu, you can use the hostname of the Pi to connect. By default this is "raspberrypi", so you could SSH in using "SSH pi@raspberrypi". However, in most cases, you'll want to know the IP address and assign a static IP address.

== Static IPs ==
Setting a static IP makes it easy to access the Pi and ensures that the IP address of the Pi is always known. In this course, we assign the Pi an IP address of 192.168.137.15. The reason for this is that when using Ethernet Passthrough on Windows, Windows asserts a domain of 192.168.137.x, with the host PC being assigned 192.168.137.1. Keep in mind that all devices will need to be on the same subnet though, so if you're assigning a static IP to be used on your own Ethernet network, you need to know what the subnet of that network is.

If you're connecting your Pi through your desktop, you'll need to assign a static IP to the desktop, too.

== Setting a static IP on your Desktop ==
If you're connecting your Pi through your desktop, you'll need to assign a static IP to the desktop, too. If you're setting a static IP on a Pi that's already connected directly to the network through a router or similar network switch, you can ignore setting a static IP on the computer.

=== Windows ===
<span class="mw-customtoggle-WindowsIP" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-WindowsIP" class="mw-collapsible mw-collapsed">
To change the IP of your Ethernet port on Windows 10, complete the following steps:

* Right click on your network option in Windows taskbar
* Select “Open Network & Internet Settings”, on the lower right hand side of the screen.
* Select “Change Adapted Options”
* Right click on the Ethernet Connection and select “Properties”
* Select “Internet Protocol Version 4 (TCP/IPv4) and click ”Properties"
* Select “Use the following IP address:” and enter in the following options:<br />
- IP Address: 192.168.137.1<br />
- Subnet Mask: 255.255.255.0
* You have successfully changed the IP of the Ethernet card on your computer. It is suggested that you now ensure connectivity by attempting to ping the Pi.

[[File:windowsIPConfig.png|thumb|none|alt=|The IPv4 configuration screen in Windows 10]]
</div>
=== Ubuntu ===
<span class="mw-customtoggle-UbuntuIP" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-UbuntuIP" class="mw-collapsible mw-collapsed">
To change the IP of your Ethernet port on Ubuntu, complete the following steps:

* Click the network interface icon on the status bar and select Wired Settings
* Click the gear button of the interface you’d like to change
* Select the IPv4 Tab, and change the IPv4 method to Manual
* Under “Addresses” enter in the following:<br />
- IP Address: 192.168.137.1<br />
- Subnet Mask: 255.255.255.0
* You can leave Gateway and DNS blank

[[File:Ubuntustaticip.png|thumb|none|alt=|The IPv4 configuration screen in Ubuntu 18.10]]
</div>

== Setting a static IP on the Pi ==
To set a static IP on the Pi, you have multiple options. You can do it before first boot by addling a line to cmdline.txt on the boot partition of the SD card, or once the Pi is running by editing dhcpcd.
=== From the boot partition ===
<span class="mw-customtoggle-PiStaticBoot" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-PiStaticBoot" class="mw-collapsible mw-collapsed">
<ol>
<li><p>Insert the SD card into your computer and navigate to the BOOT partition</p></li>
<li><p>Open “cmdline.txt” and append the following to the line (don’t create a new line)</p>
<pre> ip=192.168.137.15 </pre>
<p>This tells the Raspberry Pi to configure the Ethernet port to use the IP address 192.168.137.15</p></li>
<li><p>Enable SSH as per Section [sec:SSH].</p></li>
<li><p>You need to configure your PC to use the same subnet as the Pi. To do so, see the information below in the section on Assigning a static IP to the Pi.</p></li></ol>
</div>
=== In dhcpcd (while the Pi is running)===
<span class="mw-customtoggle-PiStaticDHCPCD" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-PiStaticDHCPCD" class="mw-collapsible mw-collapsed">
Once you’ve successfully SSH’d into your Pi, it’s a good idea to configure the networking options in the config files directly. You will need to set a static IP on the computer first if you are SSH'ing through an Ethernet connection.

Use a text editor such as nano to open /etc/dhcpcd.conf as sudo user, and edit it to the following:

<pre># Static IP profile for eth0
profile static_eth0
static ip_address=192.168.137.15/24
static routers=192.168.137.1
static domain_name_servers=192.168.137.1 8.8.8.8

# Ethernet interface configuration
interface eth0
fallback static_eth0

# Wireless configuration
interface wlan0
metric 200</pre>
</div>

== WiFi to Ethernet Passthrough ==
In a situation when you can't or don't want to connect to a WiFi network, but are connected to a computer through an Ethernet port There may be a situation in which you want your Pi to work as an access point rather than using the WiFi interface to provide the Pi with internet access. In this situation, you need to get internet access through the Ethernet port. Before starting, you need to ensure the computer you're using has a static IP assigned. When enabling network sharing on Windows, it automatically assigns 192.168.137.1. Once that's done, complete the following to enable network sharing:

=== Windows ===
<span class="mw-customtoggle-PassthroughWindows" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-PassthroughWindows" class="mw-collapsible mw-collapsed">
# Ensure the Pi is unplugged
# Right click on your network option in Windows taskbar
# Select “Open Network & Internet Settings”, on the lower right hand side of the screen.
# Select “Change Adapted Options”
# Right click on your WiFi network and select “Properties”
# Click the “Sharing” tab, and enable the first checkbox <ref>This setting is what forces us to have to use the subnet 192.168.137.x.</ref>
# Select the Ethernet connection that your Pi will be using in the drop down box (Usually just “Ethernet”, but may be different if there are multiple Ethernet posts on your system)

[[File:Windowspassthrough.png|thumb|none|alt=|Using WiFi to Ethernet passthrough in Windows]]
</div>
=== Ubuntu ===
<span class="mw-customtoggle-PassthroughUbuntu" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-PassthroughUbuntu" class="mw-collapsible mw-collapsed">
# Ensure the Pi is unplugged and turned off.
# Open a terminal and run <code>nm-connection-editor</code>
# Select the wired connection you’d like to share your WiFi to
# Select the IPv4 settings tab
# Under Method, select “Shared to other computers”
# under the IP addresses, click “Add” and enter in an address of 192.168.137.1, and a netmask of 24
# Select “Save”, and close the windows
# Plug in the Pi, start an SSH session and see if you can ping google.co.za

[[File:Nm-connection-editor.png|thumb|none|alt=|nm-connection-editor in Ubuntu 18.10]]
</div>

= Ensuring Connectivity =

Sometimes you may want to debug your connection to the Pi. A fast way to do this is via the ''ping'' command. ''Ping'' sends a packet to a particular host (in this case the Pi), and measures the time taken for a response from that host.

To use the ping command, open a command prompt window or terminal and type the following:

<pre>$ ping 192.168.137.15</pre>
If that host is unreachable (the Pi hasn’t booted yet or is incorrectly configured), a message will show that the host is unreachable. If everything was correctly configured, you should get

<pre>Reply from 192.168.137.15: bytes=32 time<1ns TTL=64</pre>
This means your Pi and computer are both correctly configured. See section [sec:SSH] for configuring your Pi for SSH access.

'''NB:''' Don’t be surprised if you can’t ping a Windows machine from your Pi. Windows blocks the specific type of packet required for a ping in the firewall.

= Networking Protocols=
For a more detailed overview on useful networking protocols, see [[Network Protocols]]
== SSH ==

=== Enabling SSH ===

If you have not connected to your Pi and configured it for SSH, you need to do so. SSH is disabled by default on new installations of Raspbian.

To enable SSH, add it as an enabled service in the <code>raspi-config</code> menu. If you do not have access to the Pi as yet, do the following:

# Insert the SD card into a computer
# Navigate to the BOOT partition
# Create a file called “ssh”. <strong>Note there is no file extension!</strong>
# Your Pi will enable SSH upon next boot

=== Using SSH ===

To use SSH on your Pi, you need to connect to the computer to a network. See Section [sec:NetworkingOnThePi] on various ways that can be done (it is suggested to use Ethernet upon first connection).

Once your Pi is connected to the computer and you have ensured connection (see Section [sec:Connectivity-EnsuringConnectivity]), use can log in to your Pi via SSH. If you are on a Linux-based system, such as Ubuntu or Mac, you should be able to run the following. Note that the default username is “pi” and the default password is “raspberry”.

<pre>$ ssh <username>@192.168.137.15</pre>
If you are on Windows, you may need to use PuTTY. Some instances of windows have SSH in the command line, and you can run the command shown above. But if not, you will need to do the following:

# Open PuTTY
# In the “Hostname” field, enter in “192.168.137.15”
# Click “Open”. A terminal window will be opened. If it is the first time you’re SSH’ing into your Pi on this particular computer, you will be asked about the server fingerprint. Click “Yes” to continue.
# You will be asked for a username and password. The default username is “pi” and the password is “raspberry”.
# You should now successfully connected to your Raspberry Pi via SSH

== VNC ==
To learn about how to install VNC, see
# Ensure the VNC service is enabled on the Pi

#Connect to the Pi through VNC.
# Set your preferred resolution for Raspbian
## In the desktop menu, go to Preferences - Raspberry Pi Configuration and click the “Set Resolution” button.
## Select a more appropriate resolution (1280*720 suggested)
## Select “Okay” and then “Okay”. You will be asked to reboot your Pi, do so.
# Set the VNC resolution
## Through editing /boot/config.txt, uncomment the following lines relating to framebuffer_width and framebuffer_height
## On the desktop on VNC, use the settings. Do this if you have already connected to VNC. This is a little more difficult as it required you to play with windows in order to see the buttons you need.

GNU Debugger (GDB)

2020-08-18T12:04:45Z

CRNKEE002: /* Installation */

[[Category:Software]]
The GNU Project Debugger (GDB)

= Installation =
== Windows ==
On Windows, gdb is a part of MinGW. See [[MinGW]] for more information.
== Ubuntu ==
GDB comes installed by default on most Unix-like systems, but if it's not installed, you can run the following:
<syntaxhighlight lang="Bash">
sudo apt install gdb
</syntaxhighlight>

= Usage =
This section defines simple usage of GDB. It is by no means comprehensive, but it should be sufficient for a fair amount of debugging scenarios.

<ol>
<li>Compile <br>
You would compile your file as per usual, but attach the g flag:
<pre>$ cc -g main.c</pre>
</li>
<li>Launch
To launch gdb, run the following, where "a.out" is the output of the compile command above
</li>
<li> Configure Debug
See below for useful debugging commands such as adding breakpoints, stepping through functions or printing the values of variables
</li>
<li>Run
Run the program with your added breakpoints by typing the "run" command.
</li>
<li>Finish
To close gdb, you can enter "q"
</li>
</ol>

= GDB Commands =
Some useful gdb commands include:
{| class="wikitable"
|-
!colspan="2"|General
|-
|help
|Shows details about commands
|-
!colspan="2"|Controlling Execution flow
|-
|break <line_number>
|Adds a breakpoint at the given line number. Other options include<br>
break <file_name:line_number><br>
break <file_name:function_name>
|-
|run
|Executes the program in gdb
|-
|next
|Debugger will execute the next line as single instruction. This includes whole functions<br>
Can be abbreviated to n.
|-
|step
|Runs a single line of code. Will enter into a called function, unlike next.
Can be abbreviated to s.
|-
|continue
|Continues execution until the next breakpoint.
Can be abbreviated to c.
|-
|finish
|If you're in a function which returns at some point, you can use the finish command to execute the program until the end of the function.
It's equivalent to setting a breakpoint at the return line of a function, and then letting the program run.
|-
!colspan="2"|Gathering information
|-
|print <variable>
|prints the value of a specified variable.
Can be abbreviated to p.
|-
|info variables
|Will give information on all variables, including some that you haven't defined
|-
|info locals
|Will give information on variables in the current scope
|-
|info args
|Will return information on the arguments passed
|-
!colspan="2"|Dealing with Pointers
|-
|print *<pointer>
|Prints what the pointer is pointing to
|-
|print &<variable>
|Displays the address of the variable
|-
|}

== gdb for openOCD ==
See the [[openOCD]] page for more details on using it. Here are some additional gdb commands that might be useful when debugging on hardware:
{| class="wikitable"
|monitor <command>
|[asses <command> directly to openOCD. Allows openOCD commands to be passed through gdb
|-
|info registers
|prints the names and values of the CPU registers
|-
|info registers rX
|Prints the value of the specifed register rX, where X is a number of a register (0-15 in ARM).
|-
|set $rX=val
|sets register X (O-15 in ARM) to the value val
|-
|x/format address
|Reads the contents of address and displays it according to format.
See [http://sourceware.org/gdb/current/onlinedocs/gdb/Memory.html this link] for more.
|-
|}

RaspberryPi:Networking

2020-08-18T12:02:55Z

CRNKEE002: /* Static IPs */

[[Category:RaspberryPi]]
There are many ways to interface with the Pi. This page will cover types of network connectivity. For more comprehensive, advanced networking details, see [[RaspberryPi:AdvancedConnectivity]].

= A Brief Overview of Networks =

It is useful to have a basic idea of how networks, IP addresses, and subnets work. For this, it it suggested you read [https://support.microsoft.com/en-za/help/164015/understanding-tcp-ip-addressing-and-subnetting-basics this article] from Microsoft.

= Wireless Connectivity =
WiFi connectivity is a useful way of connecting the Pi to the internet as it enables more portability. You can adjust WiFi Connections either before boot, by creating a <code>wpa_cupplicant.conf</code> file on the boot partition, or while the pi is running, either by editing <code>/etc/wpa/wpa_supplicant.conf</code> directly, or using <code>$ sudo raspi-config</code>. Note that the raspi-config method will not work for Eduroam.

== Simple Wifi Connections ==
If the Pi is up and running and you have access to it, you can run <code>$ sudo raspi-config</code> and enable WiFi using that menu, or editing <code>/etc/wpa/wpa_supplicant.conf</code> directly using an editor such as nano. However if you don't have access, you can create a a <code>wpa_supplicant.conf</code> file on the SD card, on the boot partition while it is plugged into another system.

If editing the wpa_supplicant configuration file, the contents should look something like the following:
<pre>
ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
update_config=1
country=ZA

network={
ssid="<Name of your WiFi network>"
psk="<Password for your WiFi network>"
}
</pre>

== Connecting to Eduroam ==
Connecting to Eduroam requires a fair amount of configuration which depends on your operating system. Generally though, edits to wpa_supplicant.conf and dhcpcd.conf are sufficient. Note that there are new releases of Raspberry Pi OS, and it is unknown if the edits for Buster are still required.

<span class="mw-customtoggle-Eduroam" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-Eduroam" class="mw-collapsible mw-collapsed">
=== Raspbian Buster ===
'''Note:''' There have been updates to the Buster code base, and roll back of wpasupplicant might not be required. However this is currently unable to be tested due to the lockdown. If someone has the chance to test, please update this page accordingly.
These instructions come from [https://www.raspberrypi.org/forums/viewtopic.php?p=1501822#p1501822 here].<br />
Unfortunately, when you use bleeding edge technology, you may end up cutting yourself. Raspbian Buster updates <code>wpa_supplicant</code> to a version that doesn’t have support for the authentication method used by Eduroam. So we need to roll back <code>wpa_supplicant</code> to an older version. Ensure your Pi has internet access through a method such as Ethernet passthrough, and run the following:

<pre>$ sudo apt-get remove wpasupplicant</pre>
Edit /etc/apt/sources.list :

<pre>$ sudo nano /etc/apt/sources.list</pre>
And change

<pre>deb http://raspbian.raspberrypi.org/raspbian/ buster main contrib non-free rpi</pre>
to

<pre>deb http://raspbian.raspberrypi.org/raspbian/ stretch main contrib non-free rpi</pre>
Run

<pre>$ sudo apt-get update
$ sudo apt-get install wpasupplicant</pre>
This will install the correct version of <code>wpa_supplicant</code>. Check that '''version 2.4''' is installed by running

<pre>$ wpa_supplicant -v</pre>
Now, change the sources file back.

<pre>$ sudo nano /etc/apt/sources.list</pre>
And edit the contents to contain

<pre>deb http://raspbian.raspberrypi.org/raspbian/ buster main contrib non-free rpi</pre>
Finally, run

<pre>$ sudo apt-get update</pre>
To update sources The correct version of <code>wpa_supplicant</code> should now be installed, and you can configure your Pi for WiFi as you would if you were using Raspbian Stretch as explained in below.

=== Raspbian Stretch ===

This section provides the instructions on how to configure the Pi to use Eduroam. It is possible to do using the GUI through VNC, but we will not cover that here.

<ol>
<li><p>SSH into your Pi.</p></li>
<li><p>Generate a hash for your password. Take note of it as it is needed in a later step</p>
<pre>
$ echo -n your_uct_password_here | iconv -t utf16le | openssl md4
</pre></li>
<li><p>Open /etc/wpa_supplicant/wpa_supplicant.conf</p>
<pre>$ sudo nano /etc/wpa_supplicant/wpa_supplicant.conf</pre></li>
<li><p>Edit it so it looks as follows:</p>
<pre>
ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
update_config=1
country=ZA

network={
ssid="eduroam"
key_mgmt=WPA-EAP
identity="studentnumber@wf.uct.ac.za"
password=hash:generated_hash_from_earlier
}
</pre></li>
<li><p>Save the file</p></li>
<li><p>Open <code>/etc/dhcpcd.conf</code></p>
<pre> $ sudo nano /etc/dhcpcd.conf</pre></li>
<li><p>Make sure the following lines are in the document:</p>
<pre>interface wlan0
metric 200
</pre></li>
<li><p>Reboot your Pi</p></li>
<li><p>WiFi Generally takes a little longer to initialize than Ethernet, so give it time. You can see if it’s ready by running</p>
<pre>$ ifconfig </pre>
<p>And seeing if an IPv4 address (“inet”) has been given.</p></li>
<li><p>Test your configuration by pinging from the WiFi interface:</p>
<pre>$ ping google.com -I wlan0</pre></li></ol>
</div>

= Ethernet Connectivity =
Ethernet is the physical connection made using a CAT 5 or 6 cable - though there are ways that Ethernet can be mimicked over USB (see Details on the Pi 0 and 0W for more information).

If you're on a private network, connecting your Pi will usually just assign it an IP address and internet connectivity automatically works. If you're on a linux-based system, like Ubuntu, you can use the hostname of the Pi to connect. By default this is "raspberrypi", so you could SSH in using "SSH pi@raspberrypi". However, in most cases, you'll want to know the IP address and assign a static IP address.

== Static IPs ==
Setting a static IP makes it easy to access the Pi and ensures that the IP address of the Pi is always known. In this course, we assign the Pi an IP address of 192.168.137.15. The reason for this is that when using Ethernet Passthrough on Windows, Windows asserts a domain of 192.168.137.x, with the host PC being assigned 192.168.137.1. Keep in mind that all devices will need to be on the same subnet though, so if you're assigning a static IP to be used on your own Ethernet network, you need to know what the subnet of that network is.

If you're connecting your Pi through your desktop, you'll need to assign a static IP to the desktop, too.

== Setting a static IP on your Desktop ==
=== Windows ===
<span class="mw-customtoggle-WindowsIP" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-WindowsIP" class="mw-collapsible mw-collapsed">
To change the IP of your Ethernet port on Windows 10, complete the following steps:

* Right click on your network option in Windows taskbar
* Select “Open Network & Internet Settings”, on the lower right hand side of the screen.
* Select “Change Adapted Options”
* Right click on the Ethernet Connection and select “Properties”
* Select “Internet Protocol Version 4 (TCP/IPv4) and click ”Properties"
* Select “Use the following IP address:” and enter in the following options:<br />
- IP Address: 192.168.137.1<br />
- Subnet Mask: 255.255.255.0
* You have successfully changed the IP of the Ethernet card on your computer. It is suggested that you now ensure connectivity by attempting to ping the Pi.

[[File:windowsIPConfig.png|thumb|none|alt=|The IPv4 configuration screen in Windows 10]]
</div>
=== Ubuntu ===
<span class="mw-customtoggle-UbuntuIP" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-UbuntuIP" class="mw-collapsible mw-collapsed">
To change the IP of your Ethernet port on Ubuntu, complete the following steps:

* Click the network interface icon on the status bar and select Wired Settings
* Click the gear button of the interface you’d like to change
* Select the IPv4 Tab, and change the IPv4 method to Manual
* Under “Addresses” enter in the following:<br />
- IP Address: 192.168.137.1<br />
- Subnet Mask: 255.255.255.0
* You can leave Gateway and DNS blank

[[File:Ubuntustaticip.png|thumb|none|alt=|The IPv4 configuration screen in Ubuntu 18.10]]
</div>

== Setting a static IP on the Pi ==
To set a static IP on the Pi, you have multiple options. You can do it before first boot by addling a line to cmdline.txt on the boot partition of the SD card, or once the Pi is running by editing dhcpcd.
=== From the boot partition ===
<span class="mw-customtoggle-PiStaticBoot" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-PiStaticBoot" class="mw-collapsible mw-collapsed">
<ol>
<li><p>Insert the SD card into your computer and navigate to the BOOT partition</p></li>
<li><p>Open “cmdline.txt” and append the following to the line (don’t create a new line)</p>
<pre> ip=192.168.137.15 </pre>
<p>This tells the Raspberry Pi to configure the Ethernet port to use the IP address 192.168.137.15</p></li>
<li><p>Enable SSH as per Section [sec:SSH].</p></li>
<li><p>You need to configure your PC to use the same subnet as the Pi. To do so, see the information below in the section on Assigning a static IP to the Pi.</p></li></ol>
</div>
=== In dhcpcd (while the Pi is running)===
<span class="mw-customtoggle-PiStaticDHCPCD" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-PiStaticDHCPCD" class="mw-collapsible mw-collapsed">
Once you’ve successfully SSH’d into your Pi, it’s a good idea to configure the networking options in the config files directly. You will need to set a static IP on the computer first if you are SSH'ing through an Ethernet connection.

Use a text editor such as nano to open /etc/dhcpcd.conf as sudo user, and edit it to the following:

<pre># Static IP profile for eth0
profile static_eth0
static ip_address=192.168.137.15/24
static routers=192.168.137.1
static domain_name_servers=192.168.137.1 8.8.8.8

# Ethernet interface configuration
interface eth0
fallback static_eth0

# Wireless configuration
interface wlan0
metric 200</pre>
</div>

== WiFi to Ethernet Passthrough ==
In a situation when you can't or don't want to connect to a WiFi network, but are connected to a computer through an Ethernet port There may be a situation in which you want your Pi to work as an access point rather than using the WiFi interface to provide the Pi with internet access. In this situation, you need to get internet access through the Ethernet port. Before starting, you need to ensure the computer you're using has a static IP assigned. When enabling network sharing on Windows, it automatically assigns 192.168.137.1. Once that's done, complete the following to enable network sharing:

=== Windows ===
<span class="mw-customtoggle-PassthroughWindows" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-PassthroughWindows" class="mw-collapsible mw-collapsed">
# Ensure the Pi is unplugged
# Right click on your network option in Windows taskbar
# Select “Open Network & Internet Settings”, on the lower right hand side of the screen.
# Select “Change Adapted Options”
# Right click on your WiFi network and select “Properties”
# Click the “Sharing” tab, and enable the first checkbox <ref>This setting is what forces us to have to use the subnet 192.168.137.x.</ref>
# Select the Ethernet connection that your Pi will be using in the drop down box (Usually just “Ethernet”, but may be different if there are multiple Ethernet posts on your system)

[[File:Windowspassthrough.png|thumb|none|alt=|Using WiFi to Ethernet passthrough in Windows]]
</div>
=== Ubuntu ===
<span class="mw-customtoggle-PassthroughUbuntu" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-PassthroughUbuntu" class="mw-collapsible mw-collapsed">
# Ensure the Pi is unplugged and turned off.
# Open a terminal and run <code>nm-connection-editor</code>
# Select the wired connection you’d like to share your WiFi to
# Select the IPv4 settings tab
# Under Method, select “Shared to other computers”
# under the IP addresses, click “Add” and enter in an address of 192.168.137.1, and a netmask of 24
# Select “Save”, and close the windows
# Plug in the Pi, start an SSH session and see if you can ping google.co.za

[[File:Nm-connection-editor.png|thumb|none|alt=|nm-connection-editor in Ubuntu 18.10]]
</div>

= Ensuring Connectivity =

Sometimes you may want to debug your connection to the Pi. A fast way to do this is via the ''ping'' command. ''Ping'' sends a packet to a particular host (in this case the Pi), and measures the time taken for a response from that host.

To use the ping command, open a command prompt window or terminal and type the following:

<pre>$ ping 192.168.137.15</pre>
If that host is unreachable (the Pi hasn’t booted yet or is incorrectly configured), a message will show that the host is unreachable. If everything was correctly configured, you should get

<pre>Reply from 192.168.137.15: bytes=32 time<1ns TTL=64</pre>
This means your Pi and computer are both correctly configured. See section [sec:SSH] for configuring your Pi for SSH access.

'''NB:''' Don’t be surprised if you can’t ping a Windows machine from your Pi. Windows blocks the specific type of packet required for a ping in the firewall.

= Networking Protocols=
For a more detailed overview on useful networking protocols, see [[Network Protocols]]
== SSH ==

=== Enabling SSH ===

If you have not connected to your Pi and configured it for SSH, you need to do so. SSH is disabled by default on new installations of Raspbian.

To enable SSH, add it as an enabled service in the <code>raspi-config</code> menu. If you do not have access to the Pi as yet, do the following:

# Insert the SD card into a computer
# Navigate to the BOOT partition
# Create a file called “ssh”. <strong>Note there is no file extension!</strong>
# Your Pi will enable SSH upon next boot

=== Using SSH ===

To use SSH on your Pi, you need to connect to the computer to a network. See Section [sec:NetworkingOnThePi] on various ways that can be done (it is suggested to use Ethernet upon first connection).

Once your Pi is connected to the computer and you have ensured connection (see Section [sec:Connectivity-EnsuringConnectivity]), use can log in to your Pi via SSH. If you are on a Linux-based system, such as Ubuntu or Mac, you should be able to run the following. Note that the default username is “pi” and the default password is “raspberry”.

<pre>$ ssh <username>@192.168.137.15</pre>
If you are on Windows, you may need to use PuTTY. Some instances of windows have SSH in the command line, and you can run the command shown above. But if not, you will need to do the following:

# Open PuTTY
# In the “Hostname” field, enter in “192.168.137.15”
# Click “Open”. A terminal window will be opened. If it is the first time you’re SSH’ing into your Pi on this particular computer, you will be asked about the server fingerprint. Click “Yes” to continue.
# You will be asked for a username and password. The default username is “pi” and the password is “raspberry”.
# You should now successfully connected to your Raspberry Pi via SSH

== VNC ==
To learn about how to install VNC, see
# Ensure the VNC service is enabled on the Pi

#Connect to the Pi through VNC.
# Set your preferred resolution for Raspbian
## In the desktop menu, go to Preferences - Raspberry Pi Configuration and click the “Set Resolution” button.
## Select a more appropriate resolution (1280*720 suggested)
## Select “Okay” and then “Okay”. You will be asked to reboot your Pi, do so.
# Set the VNC resolution
## Through editing /boot/config.txt, uncomment the following lines relating to framebuffer_width and framebuffer_height
## On the desktop on VNC, use the settings. Do this if you have already connected to VNC. This is a little more difficult as it required you to play with windows in order to see the buttons you need.

RaspberryPi:Networking

2020-08-18T12:01:25Z

CRNKEE002: /* Ethernet Connectivity */

[[Category:RaspberryPi]]
There are many ways to interface with the Pi. This page will cover types of network connectivity. For more comprehensive, advanced networking details, see [[RaspberryPi:AdvancedConnectivity]].

= A Brief Overview of Networks =

It is useful to have a basic idea of how networks, IP addresses, and subnets work. For this, it it suggested you read [https://support.microsoft.com/en-za/help/164015/understanding-tcp-ip-addressing-and-subnetting-basics this article] from Microsoft.

= Wireless Connectivity =
WiFi connectivity is a useful way of connecting the Pi to the internet as it enables more portability. You can adjust WiFi Connections either before boot, by creating a <code>wpa_cupplicant.conf</code> file on the boot partition, or while the pi is running, either by editing <code>/etc/wpa/wpa_supplicant.conf</code> directly, or using <code>$ sudo raspi-config</code>. Note that the raspi-config method will not work for Eduroam.

== Simple Wifi Connections ==
If the Pi is up and running and you have access to it, you can run <code>$ sudo raspi-config</code> and enable WiFi using that menu, or editing <code>/etc/wpa/wpa_supplicant.conf</code> directly using an editor such as nano. However if you don't have access, you can create a a <code>wpa_supplicant.conf</code> file on the SD card, on the boot partition while it is plugged into another system.

If editing the wpa_supplicant configuration file, the contents should look something like the following:
<pre>
ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
update_config=1
country=ZA

network={
ssid="<Name of your WiFi network>"
psk="<Password for your WiFi network>"
}
</pre>

== Connecting to Eduroam ==
Connecting to Eduroam requires a fair amount of configuration which depends on your operating system. Generally though, edits to wpa_supplicant.conf and dhcpcd.conf are sufficient. Note that there are new releases of Raspberry Pi OS, and it is unknown if the edits for Buster are still required.

<span class="mw-customtoggle-Eduroam" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-Eduroam" class="mw-collapsible mw-collapsed">
=== Raspbian Buster ===
'''Note:''' There have been updates to the Buster code base, and roll back of wpasupplicant might not be required. However this is currently unable to be tested due to the lockdown. If someone has the chance to test, please update this page accordingly.
These instructions come from [https://www.raspberrypi.org/forums/viewtopic.php?p=1501822#p1501822 here].<br />
Unfortunately, when you use bleeding edge technology, you may end up cutting yourself. Raspbian Buster updates <code>wpa_supplicant</code> to a version that doesn’t have support for the authentication method used by Eduroam. So we need to roll back <code>wpa_supplicant</code> to an older version. Ensure your Pi has internet access through a method such as Ethernet passthrough, and run the following:

<pre>$ sudo apt-get remove wpasupplicant</pre>
Edit /etc/apt/sources.list :

<pre>$ sudo nano /etc/apt/sources.list</pre>
And change

<pre>deb http://raspbian.raspberrypi.org/raspbian/ buster main contrib non-free rpi</pre>
to

<pre>deb http://raspbian.raspberrypi.org/raspbian/ stretch main contrib non-free rpi</pre>
Run

<pre>$ sudo apt-get update
$ sudo apt-get install wpasupplicant</pre>
This will install the correct version of <code>wpa_supplicant</code>. Check that '''version 2.4''' is installed by running

<pre>$ wpa_supplicant -v</pre>
Now, change the sources file back.

<pre>$ sudo nano /etc/apt/sources.list</pre>
And edit the contents to contain

<pre>deb http://raspbian.raspberrypi.org/raspbian/ buster main contrib non-free rpi</pre>
Finally, run

<pre>$ sudo apt-get update</pre>
To update sources The correct version of <code>wpa_supplicant</code> should now be installed, and you can configure your Pi for WiFi as you would if you were using Raspbian Stretch as explained in below.

=== Raspbian Stretch ===

This section provides the instructions on how to configure the Pi to use Eduroam. It is possible to do using the GUI through VNC, but we will not cover that here.

<ol>
<li><p>SSH into your Pi.</p></li>
<li><p>Generate a hash for your password. Take note of it as it is needed in a later step</p>
<pre>
$ echo -n your_uct_password_here | iconv -t utf16le | openssl md4
</pre></li>
<li><p>Open /etc/wpa_supplicant/wpa_supplicant.conf</p>
<pre>$ sudo nano /etc/wpa_supplicant/wpa_supplicant.conf</pre></li>
<li><p>Edit it so it looks as follows:</p>
<pre>
ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
update_config=1
country=ZA

network={
ssid="eduroam"
key_mgmt=WPA-EAP
identity="studentnumber@wf.uct.ac.za"
password=hash:generated_hash_from_earlier
}
</pre></li>
<li><p>Save the file</p></li>
<li><p>Open <code>/etc/dhcpcd.conf</code></p>
<pre> $ sudo nano /etc/dhcpcd.conf</pre></li>
<li><p>Make sure the following lines are in the document:</p>
<pre>interface wlan0
metric 200
</pre></li>
<li><p>Reboot your Pi</p></li>
<li><p>WiFi Generally takes a little longer to initialize than Ethernet, so give it time. You can see if it’s ready by running</p>
<pre>$ ifconfig </pre>
<p>And seeing if an IPv4 address (“inet”) has been given.</p></li>
<li><p>Test your configuration by pinging from the WiFi interface:</p>
<pre>$ ping google.com -I wlan0</pre></li></ol>
</div>

= Ethernet Connectivity =
Ethernet is the physical connection made using a CAT 5 or 6 cable - though there are ways that Ethernet can be mimicked over USB (see Details on the Pi 0 and 0W for more information).

If you're on a private network, connecting your Pi will usually just assign it an IP address and internet connectivity automatically works. If you're on a linux-based system, like Ubuntu, you can use the hostname of the Pi to connect. By default this is "raspberrypi", so you could SSH in using "SSH pi@raspberrypi". However, in most cases, you'll want to know the IP address and assign a static IP address.

== Static IPs ==
Setting a static IP makes it easy to access the Pi and ensures that the IP address of the Pi is always known. In this course, we assign the Pi an IP address of 192.168.137.15. The reason for this is that when using Ethernet Passthrough on Windows, Windows asserts a domain of 192.168.137.x, with the host PC being assigned 192.168.137.1. Keep in mind that all devices will need to be on the same subnet though, so if you're assigning a static IP to be used on your own Ethernet network, you need to know what the subnet of that network is.

== Setting a static IP on your Desktop ==
=== Windows ===
<span class="mw-customtoggle-WindowsIP" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-WindowsIP" class="mw-collapsible mw-collapsed">
To change the IP of your Ethernet port on Windows 10, complete the following steps:

* Right click on your network option in Windows taskbar
* Select “Open Network & Internet Settings”, on the lower right hand side of the screen.
* Select “Change Adapted Options”
* Right click on the Ethernet Connection and select “Properties”
* Select “Internet Protocol Version 4 (TCP/IPv4) and click ”Properties"
* Select “Use the following IP address:” and enter in the following options:<br />
- IP Address: 192.168.137.1<br />
- Subnet Mask: 255.255.255.0
* You have successfully changed the IP of the Ethernet card on your computer. It is suggested that you now ensure connectivity by attempting to ping the Pi.

[[File:windowsIPConfig.png|thumb|none|alt=|The IPv4 configuration screen in Windows 10]]
</div>
=== Ubuntu ===
<span class="mw-customtoggle-UbuntuIP" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-UbuntuIP" class="mw-collapsible mw-collapsed">
To change the IP of your Ethernet port on Ubuntu, complete the following steps:

* Click the network interface icon on the status bar and select Wired Settings
* Click the gear button of the interface you’d like to change
* Select the IPv4 Tab, and change the IPv4 method to Manual
* Under “Addresses” enter in the following:<br />
- IP Address: 192.168.137.1<br />
- Subnet Mask: 255.255.255.0
* You can leave Gateway and DNS blank

[[File:Ubuntustaticip.png|thumb|none|alt=|The IPv4 configuration screen in Ubuntu 18.10]]
</div>

== Setting a static IP on the Pi ==
To set a static IP on the Pi, you have multiple options. You can do it before first boot by addling a line to cmdline.txt on the boot partition of the SD card, or once the Pi is running by editing dhcpcd.
=== From the boot partition ===
<span class="mw-customtoggle-PiStaticBoot" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-PiStaticBoot" class="mw-collapsible mw-collapsed">
<ol>
<li><p>Insert the SD card into your computer and navigate to the BOOT partition</p></li>
<li><p>Open “cmdline.txt” and append the following to the line (don’t create a new line)</p>
<pre> ip=192.168.137.15 </pre>
<p>This tells the Raspberry Pi to configure the Ethernet port to use the IP address 192.168.137.15</p></li>
<li><p>Enable SSH as per Section [sec:SSH].</p></li>
<li><p>You need to configure your PC to use the same subnet as the Pi. To do so, see the information below in the section on Assigning a static IP to the Pi.</p></li></ol>
</div>
=== In dhcpcd (while the Pi is running)===
<span class="mw-customtoggle-PiStaticDHCPCD" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-PiStaticDHCPCD" class="mw-collapsible mw-collapsed">
Once you’ve successfully SSH’d into your Pi, it’s a good idea to configure the networking options in the config files directly. You will need to set a static IP on the computer first if you are SSH'ing through an Ethernet connection.

Use a text editor such as nano to open /etc/dhcpcd.conf as sudo user, and edit it to the following:

<pre># Static IP profile for eth0
profile static_eth0
static ip_address=192.168.137.15/24
static routers=192.168.137.1
static domain_name_servers=192.168.137.1 8.8.8.8

# Ethernet interface configuration
interface eth0
fallback static_eth0

# Wireless configuration
interface wlan0
metric 200</pre>
</div>

== WiFi to Ethernet Passthrough ==
In a situation when you can't or don't want to connect to a WiFi network, but are connected to a computer through an Ethernet port There may be a situation in which you want your Pi to work as an access point rather than using the WiFi interface to provide the Pi with internet access. In this situation, you need to get internet access through the Ethernet port. Before starting, you need to ensure the computer you're using has a static IP assigned. When enabling network sharing on Windows, it automatically assigns 192.168.137.1. Once that's done, complete the following to enable network sharing:

=== Windows ===
<span class="mw-customtoggle-PassthroughWindows" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-PassthroughWindows" class="mw-collapsible mw-collapsed">
# Ensure the Pi is unplugged
# Right click on your network option in Windows taskbar
# Select “Open Network & Internet Settings”, on the lower right hand side of the screen.
# Select “Change Adapted Options”
# Right click on your WiFi network and select “Properties”
# Click the “Sharing” tab, and enable the first checkbox <ref>This setting is what forces us to have to use the subnet 192.168.137.x.</ref>
# Select the Ethernet connection that your Pi will be using in the drop down box (Usually just “Ethernet”, but may be different if there are multiple Ethernet posts on your system)

[[File:Windowspassthrough.png|thumb|none|alt=|Using WiFi to Ethernet passthrough in Windows]]
</div>
=== Ubuntu ===
<span class="mw-customtoggle-PassthroughUbuntu" style="font-size:small; display:inline-block; "><span class="mw-customtoggletext" data-expandtext="Illuminate" data-collapsetext="Deluminate">[Show/hide]</span></span>
<div id="mw-customcollapsible-PassthroughUbuntu" class="mw-collapsible mw-collapsed">
# Ensure the Pi is unplugged and turned off.
# Open a terminal and run <code>nm-connection-editor</code>
# Select the wired connection you’d like to share your WiFi to
# Select the IPv4 settings tab
# Under Method, select “Shared to other computers”
# under the IP addresses, click “Add” and enter in an address of 192.168.137.1, and a netmask of 24
# Select “Save”, and close the windows
# Plug in the Pi, start an SSH session and see if you can ping google.co.za

[[File:Nm-connection-editor.png|thumb|none|alt=|nm-connection-editor in Ubuntu 18.10]]
</div>

= Ensuring Connectivity =

Sometimes you may want to debug your connection to the Pi. A fast way to do this is via the ''ping'' command. ''Ping'' sends a packet to a particular host (in this case the Pi), and measures the time taken for a response from that host.

To use the ping command, open a command prompt window or terminal and type the following:

<pre>$ ping 192.168.137.15</pre>
If that host is unreachable (the Pi hasn’t booted yet or is incorrectly configured), a message will show that the host is unreachable. If everything was correctly configured, you should get

<pre>Reply from 192.168.137.15: bytes=32 time<1ns TTL=64</pre>
This means your Pi and computer are both correctly configured. See section [sec:SSH] for configuring your Pi for SSH access.

'''NB:''' Don’t be surprised if you can’t ping a Windows machine from your Pi. Windows blocks the specific type of packet required for a ping in the firewall.

= Networking Protocols=
For a more detailed overview on useful networking protocols, see [[Network Protocols]]
== SSH ==

=== Enabling SSH ===

If you have not connected to your Pi and configured it for SSH, you need to do so. SSH is disabled by default on new installations of Raspbian.

To enable SSH, add it as an enabled service in the <code>raspi-config</code> menu. If you do not have access to the Pi as yet, do the following:

# Insert the SD card into a computer
# Navigate to the BOOT partition
# Create a file called “ssh”. <strong>Note there is no file extension!</strong>
# Your Pi will enable SSH upon next boot

=== Using SSH ===

To use SSH on your Pi, you need to connect to the computer to a network. See Section [sec:NetworkingOnThePi] on various ways that can be done (it is suggested to use Ethernet upon first connection).

Once your Pi is connected to the computer and you have ensured connection (see Section [sec:Connectivity-EnsuringConnectivity]), use can log in to your Pi via SSH. If you are on a Linux-based system, such as Ubuntu or Mac, you should be able to run the following. Note that the default username is “pi” and the default password is “raspberry”.

<pre>$ ssh <username>@192.168.137.15</pre>
If you are on Windows, you may need to use PuTTY. Some instances of windows have SSH in the command line, and you can run the command shown above. But if not, you will need to do the following:

# Open PuTTY
# In the “Hostname” field, enter in “192.168.137.15”
# Click “Open”. A terminal window will be opened. If it is the first time you’re SSH’ing into your Pi on this particular computer, you will be asked about the server fingerprint. Click “Yes” to continue.
# You will be asked for a username and password. The default username is “pi” and the password is “raspberry”.
# You should now successfully connected to your Raspberry Pi via SSH

== VNC ==
To learn about how to install VNC, see
# Ensure the VNC service is enabled on the Pi

#Connect to the Pi through VNC.
# Set your preferred resolution for Raspbian
## In the desktop menu, go to Preferences - Raspberry Pi Configuration and click the “Set Resolution” button.
## Select a more appropriate resolution (1280*720 suggested)
## Select “Okay” and then “Okay”. You will be asked to reboot your Pi, do so.
# Set the VNC resolution
## Through editing /boot/config.txt, uncomment the following lines relating to framebuffer_width and framebuffer_height
## On the desktop on VNC, use the settings. Do this if you have already connected to VNC. This is a little more difficult as it required you to play with windows in order to see the buttons you need.