hellopi 1.0

Hello Pi

Hello Pi is a program that identifies the ip address of Raspberry Pis added to the local area network.

What It Does:

Hello Pi makes it easy to identify the ip address of a Raspberry Pi (RPi) computer added to the same DHCP-configured local area network (LAN). Additionally, it can report the ip address of other devices added to the same LAN. It eliminates the need to attach a display and keyboard to the RPi solely to discover its ip address.

The Problem It Solves:

A frequent, common problem when commissioning a new RPi is that the ip address that it will be assigned is not initially known. Traditionally, this has meant that the user must connect a display and keyboard to the new RPi in order to check what ip address it has been assigned. This is inconvenient and can be a problem if the RPi is intended to be used in a "headless" (no connected display) configuration. A headless setup would typically be configured using SSH to login remotely from another computer, but this requires knowledge of the ip address of the target RPi. Hello Pi makes it easy to learn the ip address of a device when it is powered-up while connected to the same LAN.

How To Use It:

Hello Pi is run from a computer (the 'Host') connected to the same DHCP-configured LAN as the RPi (the 'Target') or other device to be discovered.

1. Using the command-prompt, start Hello Pi on the Host.
   • Note that the -h option can be used to see a list of available command options.
2. The initial state of the Target (RPi or device) is powered-down/unpowered.
3. Connect Target to the LAN.
   • If using Ethernet, physically connect the cable.
   • If using WiFi, configure the wpa_supplicant.conf file in the boot folder of the OS image.
4. Power-up the Target and wait while it boots.
5. Observe the output of Hello Pi on the Host to learn the ip address assigned to the Target.
6. To repeat the process, power-down the Target and return to step 2.

Theory of Operation:

This section is presented for those curious about how the program works, but is not required reading
to use the program.

Hello Pi listens to the exchange between the Target device and the DHCP server. When the Target is powered-up while connected to the LAN, it sends a broadcast DHCP Discovery message. The DHCP server receives this message and sends a DHCP Offer response. The Target then replies with a broadcast DHCP Request response acknowledging acceptance of the ip address that was offered.

Since the Target's DHCP Request message is broadcast to all devices on the LAN, Hello Pi on the Host listens for this message and reports the accepted ip address.

Hello Pi has the option to report the ip address of only RPis, or can be instructed to report the ip address of any device that connects and is configured via DHCP. In order to discriminate between RPis and other devices, the OUI (Organizationally Unique Identifier) of the MAC address is compared to the OUIs registered to the Raspberry Pi Foundation.

Platform-specific Details:

Linux/BSD:

Hello Pi on Linux must be run with elevated privileges (via sudo or as root). This is required to allow it to create a "raw socket", which it uses to see DHCP Request broadcast messages sent by devices connecting to the LAN. From these messages, it can display the ip address of the connecting RPi or device.

Windows:

Hello Pi on Windows must be run with administrator privileges. This is required to allow it to create a "raw socket", which it uses to see DHCP Request broadcast messages sent by devices connecting to the LAN. From these messages, it can display the ip address of the connecting RPi or device.

For Hello Pi to read broadcast DHCP Request messages on Windows, they must be allowed through the firewall. To allow broadcast DHCP Requests on Windows, add the following firewall ALLOW rule:

WINDOWS FIREWALL ALLOW RULE:
    Name: DHCP Server Port
    Protocol: UDP
    Local port: 67
    Remote port: 68
    Local IP Address: 255.255.255.255
    Remote IP Address: 0.0.0.0

Command-line Options:

USAGE: 
    hellopi <OPTIONS>
            OR
    python3 hellopi.py <OPTIONS>

OPTIONS:
  -a    Display ALL devices (not just RPis) making a DHCP Request for an ip address.
  -h    Display this help message.
  -q    Quiet the program startup information.
  -v    Display verbose messages.

Installation:

Run From Source:

1. To run Hello Pi from source, download the project source files into the desired folder.
2. Open a terminal window in the source directory.
   • Windows: Right-click the Command Prompt app and select "Run as administrator". Next change to the source directory.
   • Linux: Open a terminal window and change to the source directory.
3. Run the program with administrator access rights.
   • Windows: The Command Prompt app was already opened with admin rights in step 2, so simply run the command with: python3 hellopi.py -h
   • Linux: Run the command with: sudo python3 hellopi.py -h

Install and Run System-wide:

1. To install Hello Pi so that it can be run like a command, download the project source files into a working folder.
2. Open a terminal window in the source directory.
   • Windows: Right-click the Command Prompt app and select "Run as administrator". Next change to the source directory.
   • Linux: Open a terminal window and change to the source directory.
3. Run the setup.py install program with administrator access rights.
   • Windows: python setup.py install
   • Linux: sudo python3 setup.py install
4. To run Hello Pi any time after installation, open a terminal window and use the hellopi command. Use hellopi -h to see a list of the command's options.