{"id":19218575,"url":"https://github.com/sitespeedio/humble","last_synced_at":"2025-02-23T09:14:39.223Z","repository":{"id":142003392,"uuid":"438952914","full_name":"sitespeedio/humble","owner":"sitespeedio","description":"Raspberry Pi WiFi network link conditioner","archived":false,"fork":false,"pushed_at":"2022-07-05T11:06:26.000Z","size":54,"stargazers_count":8,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-04-13T21:43:11.811Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sitespeedio.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2021-12-16T10:42:55.000Z","updated_at":"2024-04-02T08:25:01.000Z","dependencies_parsed_at":"2023-09-24T06:57:31.184Z","dependency_job_id":null,"html_url":"https://github.com/sitespeedio/humble","commit_stats":{"total_commits":16,"total_committers":1,"mean_commits":16.0,"dds":0.0,"last_synced_commit":"88e7aceeb364ffef66559f5a7b0990861e6211f1"},"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sitespeedio%2Fhumble","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sitespeedio%2Fhumble/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sitespeedio%2Fhumble/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sitespeedio%2Fhumble/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sitespeedio","download_url":"https://codeload.github.com/sitespeedio/humble/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":240006040,"owners_count":19732872,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-09T14:27:15.899Z","updated_at":"2025-02-23T09:14:39.158Z","avatar_url":"https://github.com/sitespeedio.png","language":null,"readme":"# Humble - Raspberry Pi WiFi network link conditioner\n\nConnect your Raspberry Pi4 with your router turn on the Pi and join your new configurable WiFi network named `humble`. Access your Raspberry Pi4 through HTTP and choose the WiFi speed like this:\n\n![throttle](https://user-images.githubusercontent.com/540757/146691181-4bef0437-fa58-41a4-a5ae-1d12da7bbf05.gif)\n\nTable of Contents\n=================\n* [Background](#background)\n* [Prerequisite](#prerequisite)\n* [Install using the pre-made image](#install-using-the-pre-made-image)\n  * [Log into the device](#log-into-the-device)\n  * [Changing WiFi password](#changing-wifi-password)\n  * [Changing SSH login password](#changing-ssh-login-password)\n  * [Use a USB WiFi antenna](#use-a-usb-wifi-antenna)\n  * [Raspberry Pi image setup](#raspberry-pi-image-setup)\n  * [Change WiFi geographical location](#change-wifi-geographical-location)\n  * [Turn on auto update for the Throttle front end](#turn-on-auto-update-for-the-throttle-front-end)\n* [Install from scratch](#install-from-scratch)\n  * [Install the OS and prepare your device](#install-the-os-and-prepare-your-device)\n  * [Enable WiFi](#enable-wifi)\n  * [Install and setup](#install-and-setup)\n  * [Install throttle frontend](#install-throttle-frontend)\n* [Change throttling using the API](#change-throttling-using-the-API)\n* [Take a copy of your SD card](#take-a-copy-of-your-sd-card)\n\n## Background\nInspired by Sam Smiths [PiNC](https://github.com/phuedx/pinc) I wanted to make a easy way for everyone (not just developers) to try out different internet speeds.\n\n## Prerequisite\nYou need a Raspberry Pi 4 with a Ethernet cable that you can connect to your router.\n\n## Install using the pre-made image\n1. Download the pre-made image from [releases](https://github.com/sitespeedio/humble/releases).\n2. Burn the image on a SD card using [Raspberry Pi Imager](https://www.raspberrypi.com/software/).\n3. Insert the SD card into the Raspberry Pi 4.\n4. Connect your Raspberry Pi with your router through a Ethernet cable and turn on your Raspberry Pi.\n5. Join your new configurable `humble` WiFi network on desktop or mobile phone with the password `goslowtogoFAST`.\n6. Access your Raspberry Pi through HTTP and chose the WiFi speed. On Mac access `http://raspberrypi.local:3001` from your web browser. On other OS you can use `nmap` to [find your Raspberry IP address](https://community.wia.io/d/11-how-to-set-up-a-raspberry-pi-without-an-external-monitor-or-keyboard). Access that IP using port 3001 in your browser.\n7. Choose the WiFi speed.\n\nWhen you checked that everything works you should change the WiFi password and the SSH password!\n\n### Log into the device\nUse the user `pi` and password `myloveisyourloveforever` to log into the device using SSH.\n\n### Changing WiFi password\n\nEdit the file `/etc/wpa_supplicant/wpa_supplicant.conf` and change the password to your new password.\n\n```bash\nsudo nano /etc/hostapd/hostapd.conf\n```\n\nReboot by `sudo reboot`.\n\n### Changing SSH login password\nLogin to the device and change the password to your new password using `passwd`.\n\n### Use a USB WiFi antenna\nIf you want to use your *humble* installation for performance testing you probably want to use a USB WiFi antenna that is better than the default one that comes with the Raspberry Pi. \n\nThe new WiFi will probably be `wan1` on your Raspberry and that means you need to reconfigure your Pi so its used:\n\n1. Edit */etc/dhcpcd.conf* with `sudo nano /etc/dhcpcd.conf` and change `wan0` to `wan1`.\n2. Edit */etc/dnsmasq.conf* with `sudo nano /etc/dnsmasq.conf` and change `wan0` to `wan1`.\n3. Edit */etc/hostapd/hostapd.conf* with `sudo nano /etc/hostapd/hostapd.conf` and change `wan0` to `wan1`.\n4. Reboot by `sudo reboot`.\n\n----\nIf you use another antenna you need to make sure that the WiFI do not go to sleep mode. You can check your setup with `iwcofig` and look for the power option for you WiFi.\n\nTo turnoff sleeping mode you can run:\n\n`sudo iw wlan1 set power_save off`\n\nAnd for turning it off for startup you need to edit:\n\n```sudo nano /etc/rc.local```\n\nThen before *exit 0* add the following line:\n```/sbin/iwconfig wlan1 power off```\n### Raspberry Pi image setup\nThe image (based on Raspberry Pi OS Lite) has the following extra setup:\n\n* It runs unattended-upgrades to keep the image up to date.\n* It runs fail2ban\n* It starts [the web version of throttle](https://github.com/sitespeedio/throttle-frontend) on startup using systemd.\n\n\n### Change WiFi geographical location \nThe WiFi setup in the images has Sweden as geographical setup and you probably want to change that. Use https://en.wikipedia.org/wiki/ISO_3166-1 to find your country code. I'm located in Sweden so I use `SE`.\n\nYou need to change in two different places. First run:\n\n```bash\nsudo raspi-config nonint do_wifi_country SE\n```\n\nAnd then edit the file `/etc/hostapd/hostapd.conf` and change the current country code to yours.\n\n```bash\nsudo nano /etc/hostapd/hostapd.conf\n```\n\nAnd change the row:\n```\ncountry_code=SE\n```\n\nThen reboot by `sudo reboot`.\n### Turn on auto update for the Throttle front end\n\nYou can make sure user interface is automatically updated by adding the following in the crontab.\n\nFirst open the crontab:\n```bash\ncrontab -e\n```\n\nAnd then add the following lines:\n```\n0 6 * * *  bash -lc /home/pi/update.sh  2\u003e\u00261 | logger -t humble-updates\n```\n\n## Install from scratch\n\nThank you SpaceRex for your tutorial [Turn your Raspberry Pi into a WiFi Router!](https://www.youtube.com/watch?v=laeOmNDE-Ac), that helped me a lot to set this up! Checkout the [video](https://www.youtube.com/watch?v=laeOmNDE-Ac) for more details.\n\n### Install the OS and prepare your device\n1. Download and install the latest [Raspberry Pi OS Lite](https://www.raspberrypi.com/software/operating-systems/) image to a SD card using [Raspberry Pi Imager](https://www.raspberrypi.com/software/).\n2. Add an empty file named `SSH` to root section of the SD card so you more easily can access the Raspberry Pi.\n3. Insert the SD card into the Raspberry Pi, connect your Raspberry Pi with your router through a Ethernet cable and turn on your Raspberry Pi.\n4. Find the IP number of your Raspberry Pi, use `nmap` to [find your Raspberry IP address](https://community.wia.io/d/11-how-to-set-up-a-raspberry-pi-without-an-external-monitor-or-keyboard) or on Mac just use `raspberrypi.local`.\n5. Login to your Raspberry using SSH (this example if for Mac): `SSH pi@raspberrypi.local` with password `raspberry`.\n6. Once you logged in, change the password for the *pi* user using `passwd` to set a new password.\n\nNow you are ready to turn your Raspberry Pi into a WiFi router.\n\n### Enable WiFi\n1. By default the WiFI on the Raspberry Pi is disabled (you will get a message like **Wi-Fi is currently blocked by rfkill.** when you login to the device). Enable the WiFi by setting your geographical location. Use https://en.wikipedia.org/wiki/ISO_3166-1 to find the country code. I'm located in Sweden so I use `SE`.\n\nFirst run:\n```bash\nsudo raspi-config nonint do_wifi_country SE\n```\nThen reboot the device:\n```bash\nsudo reboot\n```\n\n### Install and setup\n1. First make sure to update:\n```sudo apt update```\n2. Install the following so your Raspberry Pi can act as a router: \n```sudo DEBIAN_FRONTEND=noninteractive apt install -y hostapd dnsmasq netfilter-persistent iptables-persistent```\n3. Make sure it starts on boot:\n```bash\nsudo systemctl unmask hostapd.service\nsudo systemctl enable hostapd.service\n```\n\n4. Edit `etc/dhcpcd.conf` and make sure to add the interface at the bottom of the file and set the subnet that is gonna be used (make sure you don't use that IP before on your network). This makes sure that when wlan0 is used (our WiFi) the Raspberry Pi get IP 10.2.1.1:\n```bash\nsudo nano /etc/dhcpcd.conf\n```\n\nThen add at the bottom of the file:\n```\ninterface wlan0\n    static ip_address=10.20.1.1/24\n    nohook wpa_supplicant\n\n```\n\n5. Then edit `/etc/sysctl.d/routed-ap.conf` to forward ipv4 adresses.\n\nOpen the file: \n```bash\nsudo nano /etc/sysctl.d/routed-ap.conf\n```\nand add `net.ipv4.ip_forward=1` in that file.\n\n6. Tell the traffic where to go. In the terminal run:\n\n```bash\nsudo iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE\nsudo netfilter-persistent save\n```\n\n7. The step prepare your Raspberry to be a router and setup which IP addresses devices will have when they connect. That happens on `/etc/dnsmasq.conf`. \n\nAs a first step, move the old version so we have a backup:\n\n```bash\nsudo mv /etc/dnsmasq.conf /etc/dnsmasq.conf.old\n```\n\nThen open (a new) file:\n`sudo nano /etc/dnsmasq.conf` \n\nAnd add the following lines:\n```\ninterface=wlan0\ndhcp-range=10.20.1.5,10.20.1.100,255.255.255.0,72h\ndomain=wlan\naddress=/rt.wlan/10.20.1.1\n```\n\n8. Setup your host access point file. Edit `/etc/hostapd/hostapd.conf`\nHere you need to add your country code again (https://en.wikipedia.org/wiki/ISO_3166-1) and set a password (`wpa_passphrase`) and a name `ssid` of your WiFi network.\n\nOpen the file:\n```\nsudo nano /etc/hostapd/hostapd.conf\n```\n\nAnd then add:\n```                     \ncountry_code=SE\ninterface=wlan0\nssid=humble\nhw_mode=a\nchannel=36\nmacaddr_acl=0\nauth_algs=1\nignore_broadcast_ssid=0\nwpa=2\nwpa_passphrase=goslowtogoFAST    \nwpa_key_mgmt=WPA-PSK\nwpa_pairwise=TKIP\nrsn_pairwise=CCMP\n```\n\nChange the `country_code` to your country code. \n\nIt's also in this configuration file you choose what frequency your WiFi network will be on.     \n`hw_mode`can be either *a* = 5GHz, *b* = 2.4Ghz or *g* =2.4 GHz.\n\n9. Make sure your WiFI has power save turned off (*Power Management:off*). First check that power saving is turned on by running `iwcofig`. If it's on, you can make sure that is turned off on startup by:\n\n```sudo nano /etc/rc.local```\n\nThen before *exit 0* add the following line:\n```/sbin/iwconfig wlan0 power off```\n\n10. The WiFI setup is done. Reboot your Pi `sudo reboot` and try to connect to your WiFi network on your desktop or mobile.\n\n### Install throttle frontend\nTo be able to run the frontend you need to install NodeJS. [Install latest LTS](https://nodejs.org/en/), when I write this that version is 16.13.1. \n\n```bash\nwget https://nodejs.org/dist/v16.13.1/node-v16.13.1-linux-armv7l.tar.xz\ntar xf node-v16.13.1-linux-armv7l.tar.xz\ncd node-v16.13.1-linux-armv7l/\nsudo cp -R * /usr/local/\n```\n\nThen you can verify that it worked by running:\n```bash\nnode --version\n```\n\nAs the last step you need to install the frontend.\n\n```bash\nsudo apt install -y git\ngit clone https://github.com/sitespeedio/throttle-frontend.git\ncd throttle-frontend\nnpm install --production\n```\n\nStart the frontend with: \n```bash\nnode lib/app.js\n```\n\nAnd open your browser and access ```http://\u003craspberrypiip\u003e:3001```\n\n## Change throttling using the API\nInstead of using the graphical frontend, you can use the API to change the throttling. Call the API with the profile you want to use. \n\nSet throttling to cable:\n\n```bash\ncurl http://raspberrypi.local:3001/api/cable -H \"Accept: application/json\"\n```\n\nSet throttling to 3g:\n```bash\ncurl http://raspberrypi.local:3001/api/3g -H \"Accept: application/json\"\n```\n\nStop throttling:\n```bash\ncurl http://raspberrypi.local:3001/api/stop -H \"Accept: application/json\"\n```\n\n## Take a copy of your SD card\nThis is how I do it on my Mac. First make sure you have your SD card inserted. Then use `diskutil list` to find the disk. On my computer it's mounted as */dev/disk2*. Then to copy and compress it I use:\n\n```\nsudo dd if=/dev/rdisk2 bs=1m | xz -T 0 -9 -e \u003e /Users/peter/Desktop/humble-version.xz\n```\n\nNote that I've changed */dev/disk2* to */dev/rdisk2* to make it read only.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsitespeedio%2Fhumble","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsitespeedio%2Fhumble","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsitespeedio%2Fhumble/lists"}