A set of tools to easily configure the Raspberry Pi to function as a High-Speed Multimedia (HSMM) wireless node.
PHP Shell CSS Python Batchfile Perl Other
#5 Compare This branch is 113 commits ahead, 125 commits behind urlgrey:master.
Latest commit 9edea6a Nov 13, 2015 @bwattendorf fixed " in script

README.md

BBHN-Pi-VPN

BBHN-Pi-VPN is the name change of HSMM (High Speed Multi Media) to BBHN (Broad Band Ham net) also the VPN was added to allow setting up virtual private networks linking BBHM networks using Wired internet connections. This allows network to be joined where they would not be able to be connected using wireless easily.

HSMM-Pi is a set of tools designed to easily configure the Raspberry Pi to function as a High-Speed Multimedia (HSMM) wireless node. HSMM offers radio amateurs (HAMs) the ability to operate high-speed data networks in the frequencies shared with unlicenced users of 802.11 b/g/n networking equipment. HAMs can operate HSMM at higher power with larger antennas than are available to unlicensed users. The BBHN-Pi-VPN project makes it possible to run an HSMM mesh node on the Raspberry Pi. The project has been tested to work on other embedded computing platforms, including the Beaglebone Black.

The BBHN-Pi-VPN project can used by people not possessing an amateur radio license so long as they are in compliance with the transmission rules set by the FCC or the local regulating body. This typically means sticking with the WiFi antenna provided with your WiFi adapter.

BBHN-Pi-VPN is origionaly from hsmm-Pi by urlgrey the VPN backend was origional by Robery Moony Zl1FLY the VPN UI addon was done by Bruce Wattendorf W1BAW

BBHN-Pi-VPN Blog: care of Rhode Island BBHN group bbhn-ri.com

For a video tour, see the following YouTube video: http://www.youtube.com/watch?v=ltUAw02vfqk

The project consists of a PHP web application that is used to configure and monitor the mesh node, and an installation shell script that installs dependencies and puts things in the right spots.

The BBHN-Pi-VPN project is designed to run on Ubuntu 12.04 systems. Rather than providing an OS image for BBHN-Pi-VPN, I've instead created an installation script that will transform a newly-imaged host into an BBHN-Pi-VPN node. This has several benefits:

  • Greater transparency: You can see exactly which changes are made to the base system by looking at the install shell script.
  • Easier to port to more platforms: Any platform that runs the supported Ubuntu releases ought to be capable of running BBHN-Pi-VPN
  • Easier to host: I only need to post the installation script and webapp files on Github and it's done.
  • Easier to seek support: Ubuntu is widely used and supported, no need to introduce another customization.

Hardware Requirements

BBHN-Pi-VPN has been tested to work with the Raspberry Pi running the Raspbian OS, and with the Beaglebone Black running Ubuntu 12.04 from the onboard eMMC flash memory. The requirements for each are listed below.

Raspberry-Pi Node:

  • Raspberry Pi (256MB or 512MB of RAM will work)
  • USB WiFi adapter (tested with the N150 adapter using the Ralink 5370 chipset)
  • SD memory card (4GB minimum)

Beaglebone Black Node:

  • Beaglebone Black
  • USB WiFi adapter (tested with the N150 adapter using the Ralink 5370 chipset)
  • SD memory card (4GB minimum) (used for initial imaging of the eMMC flash memory only)

Modes

The BBHN-Pi-VPN can function as an internal mesh node or as a gateway mesh node. A description of each is provided below.

Mesh Gateway Node

The Mesh Gateway is capable of routing traffic throughout the mesh, and provides an Internet link to the mesh through the wired Ethernet port. The gateway obtains a DHCP lease on the wired interface, and advertises its Internet link to mesh nodes using OLSR.

Internal Mesh Node

This node is capable of routing traffic throughout the mesh and providing mesh access to any hosts connected to its wired Ethernet port. The node can run a DHCP server that issues DHCP leases to any hosts on the wired connection. It also runs a DNS server that can provide name resolution for mesh nodes and Internet hosts. The following sequence shows how the two types of nodes can be deployed:

(Client1) --> (Switch) --> (Internal Mesh Node) --> 
(Ad-Hoc WiFi Network) --> (Mesh Gateway) --> (Internet)

There could be any number of mesh nodes in the Ad-Hoc WiFi Network. The route among the nodes is managed entirely with OLSR.

I've done all of my testing with N150 USB wifi adapters that use the Ralink 5370 wireless chipset. These adapters are cheap (~$7 USD), compact, and easy to come by. They also use drivers that are bundled with most Ubuntu distributions, making setup easy. The N150 adapter tested included a threaded antenna connector that should make it easy to add a linear amplifier and aftermarket antenna (outside the scope of the BBHN-Pi-VPN project).

Raspberry Pi Installation

  1. Download the Raspbian Wheezy 2015-02-16 disk image on your Mac/PC/whatever (http://downloads.raspberrypi.org/raspbian/images/raspbian-2015-02-17/)
  2. Write the image to an SD memory card. This involves formatting the SD card; I recommend the steps described at http://elinux.org/RPi_Easy_SD_Card_Setup
  3. Insert the card into a Raspberry Pi
  4. Connect the wired Ethernet port on the Pi to a network with Internet access
  5. Apply power to the Pi
  6. Login to the Pi, either through an SSH session or the console, using the 'pi' account
  7. Run the Raspberry Pi Setup program:

    sudo raspi-config
    
  8. Expand the filesystem to fill the SD memory card
  9. Change the password for the 'pi' account
  10. If installing over an SSH connection to the Pi, then I recommend you install 'screen' (sudo apt-get install screen) to ensure that the installation script is not stopped prematurely if you lose connectivity with the Pi. This is optional, but I highly recommend using screen if installing over the network. You can find more info on screen here: http://linux.die.net/man/1/screen
  11. Run the following commands to download the BBHN-Pi-VPN project and install

    git clone https://github.com/bwattendorf/bbhn-pi-vpn.git
    cd bbhn-pi-vpn
    git checkout tags/v0.4.0-1
    sh install.sh
    
  12. Login to the web application on the Pi: http://(wired Ethernet IP of the node):8080/
  13. Access the Admin account using the 'admin' username and 'changeme' password.
  14. Change the password for BBHN-Pi-VPN
  15. Configure as either an Internal or Gateway node

Beaglebone Black Installation

  1. Download the latest Beaglebone Black Ubuntu 12.04 image: http://www.armhf.com/index.php/boards/beaglebone-black/#precise
  2. Write the image to an SD memory card using the steps on the page referenced in the previous step
  3. Insert the SD card into a Beaglebone Black board
  4. Apply power to the Beaglebone Black
  5. Login to the Beaglebone Black through an SSH session or the console using the 'ubuntu' account
  6. Transfer the image to the running Beaglebone Black using SCP
  7. Write the image to the eMMC flash memory using the steps mentioned in the first step here.
  8. Wait for all 4 LEDs to go solid (could take several minutes)
  9. Shutdown the Beaglbone Black (sudo /sbin/init 0)
  10. Remove the memory card from the Beaglebone Black
  11. Apply power to the Beaglebone Black
  12. Login to the Beaglebone Black through an SSH session or the console using the 'ubuntu' account
  13. Change the password for the 'ubuntu' account
  14. To set up the Beagle Bone Black to use the usb port for network share on the PC first share the PC's ip port then
  15. on the Beagle Bone set the gate way and then add the name server to the Beagle Bone

    sudo /sbin/route add default gw 192.168.7.1
    sudo nano /etc/resolv.conf
    
    then add nameserver 8.8.8.8 to the bottom and save
    
  16. Install the development tools necessary to build OLSRD and retrieve the BBHN-Pi-VPN project:

    sudo apt-get upgrade
    sudo apt-get install make gcc git
    
  17. If installing over an SSH connection, then I recommend you install 'screen' (sudo apt-get install screen) to ensure that the installation script is not stopped prematurely if you lose connectivity. This is optional, but I highly recommend using screen if installing over the network. You can find more info on screen here: http://linux.die.net/man/1/screen
  18. Run the following commands to download the BBHN-Pi-VPN project and install

    sudo git clone https://github.com/bwattendorf/bbhn-pi-vpn.git
    cd bbhn-pi-vpn
    git checkout tags/v0.4.0-1
    sh install.sh
    
  19. Login to the web application: http://(wired Ethernet IP of the node):8080/
  20. Access the Admin account using the 'admin' username and 'changeme' password.
  21. Change the password for BBHN-Pi-VPN
  22. Configure as either an Internal or Gateway node

Upgrade Steps

This is experimental, and you should fall back to a fresh installation if things aren't functioning as you'd expect. This is supported only on the HEAD of the master branch at this time.

  1. Login to the host using SSH or the console
  2. Run the following commands to upgrade:

    cd ~/bbhn-pi-vpn
    git pull
    sh install.sh
    
  3. Access the web UI and check the configuration. Save the Network and Location settings, even if no changes are needed.
  4. If the save operation fails, then you might need to replace the SQLite database file due to database schema changes. Runn the following command:

    cd ~/bbhn-pi-vpn/
    sudo cp src/var/data/bbhn-pi-vpn/hsmm-pi.sqlite /var/data/hsmm-pi/
    
  5. Repeat the step of reviewing and saving the configuration through the web UI.

Internal Mesh Node Configuration

This represents the minimum set of steps:

  1. Select Admin->Network from the menubar
  2. Configure the WiFi interface:
    1. Specify an IP address that will be unique throughout the mesh network. This will be different every mesh node. A default will be provided based on the last 3 fragments of the WiFi adapter MAC address.
  3. Configure the Wired interface:
    1. Set the Wired interface mode to LAN
  4. Configure the Mesh settings
    1. Specify your amatuer radio callsign (i.e. KK6DCI)
    2. Specify your node name, likely a composition of your callsign and a unique number in your mesh (i.e. KK6DCI-7)
  5. Click 'Save'
  6. If successful, click the 'Reboot' button in the alert and proceed.

Gateway Node Configuration

This represents the minimum set of steps:

  1. Select Admin->Network from the menubar
  2. Configure the WiFi interface:
    1. Specify an IP address that will be unique throughout the mesh network. This will be different every mesh node. A default will be provided based on the last 3 fragments of the WiFi adapter MAC address.
  3. Configure the Wired interface:
    1. Set the Wired interface mode to WAN
  4. Configure the Mesh settings
    1. Specify your amatuer radio callsign (i.e. KK6DCI)
    2. Specify your node name, likely a composition of your callsign and a unique number in your mesh (i.e. KK6DCI-7)
  5. Click 'Save'
  6. If successful, click the 'Reboot' button in the alert and proceed.