- About PiPass
- Master Branch Updates
- What's New in Version 1.52
- Known Behaviours
- Helpful Information
- Testing Environment
- Installation
- Using PiPass
- PiPass Customization
- PiPass Maintenance
- Hardware
- Future Features
- Support
PiPass turns your Raspberry Pi into a Nintendo 3DS Homepass Relay Station. The PiPass Dashboard can be accessed through a computer or mobile device. It can manage features without the need of opening up any files manually. However, some fine-tuning may require getting your hands 'dirty'. Though the process is relatively fast and easy.
This does not showcase a complete list of features, but it gives a sense in what PiPass looks like: PiPass Video Overview. The video shown is based on PiPass 1.4, however the general work-flow is relatively the same as in PiPass 1.52 with some minor differences.
If you like PiPass, please star the project on GitHub and thanks for trying out PiPass!
Please use 'PiPass Update' to receive the following changes that were implemented after PiPass 1.52:
- PiPass will now accept incorrectly formatted MAC addresses that use dashes instead of colons. PiPass will internally convert dashes to colons when dealing with Nintendo Zone MAC addresses and externally make this change for authenticated MAC addresses.
- PiPass will now check network connectivity. If there is a network connectivity issue, PiPass will stop cycling and stop hostapd. Once network connectivity has been re-established, PiPass will continue cycling again.
- PiPass can now detect incompatible hostapd WiFi chipsets that are unable to change its own MAC address.
- 'PiPass Settings' uses JQuery form validation instead of HTML5 form validation.
- Added 'Time Until Next Zone' progress bar to the dashboard.
- User interface tweaks.
- HTML code cleanup.
NOTE: Those who are using 'PiPass Update' on versions below PiPass 1.52, please go to 'PiPass Settings' and verify 'Hostapd Security'. PiPass 1.52 can now enable / disable hostapd security and it will assume no security if this setting is not updated after updating PiPass to PiPass 1.52. Once this setting has been updated, PiPass will automatically remember this setting for future versions.
PiPass 1.52 focuses on overall polish and being informative about what is exactly going on "behind the scenes". The biggest feature addition is the logging system that provides extra information regarding status and it also aids in troubleshooting. The changelog for this version of PiPass is as follows:
- Hostapd security can now be enabled / disabled through 'PiPass Settings'.
- Fixed 'Shuffle Zones' bug where piPass.py would force it to be enabled.
- PiPass now features a logging system that is accessible through the dashboard.
- piPass.py works with the logging system to diagnose issues (e.g., hostapd WiFi drivers).
- PiPass will log all invalid MAC addresses encountered and skip to the next zone.
- PiPass can now reset the network through the dashboard.
- PiPass PHP form validation messages now conforms to responsive design and the user interface.
- The PiPass version can now be viewed through the dashboard.
- Changelogs are accessible through 'About PiPass' in the dashboard.
- The dashboard only refreshes the 'Spoofing Status' and the 'Show Current' table, instead of the entire page.
- Scrollable modals.
- Minor rewording.
- Minor tweaks.
PiPass sometimes does not display expected or up-to-date values. Chrome is known to be finicky with this and will NOT cause issues with PiPass. When in doubt, manually refresh your browser as this is related to browser caching.
Many people have been trying to get the RTL8188CUS chipset to work with PiPass and with other Homepass solutions as well. There is a thread found in my issue list that has a discussion where someone was able to get the RTL8188CUS working with PiPass. It will require a bit of Linux knowledge to follow and so far many others have not been able to reproduce the workaround. Due to this, it is still recommended to purchase a compatible WiFi dongle that is known to work.
When using PiPass or any other Homepass solution, you may notice that StreetPasses only occur when your Nintendo 3DS is in sleep mode. To get StreetPasses while your Nintendo 3DS is 'awake', you must ensure that your Nintendo 3DS is not connected to a network.
Development and testing was done using all the components from the Canakit Raspberry Pi 2 Complete Starter Kit with WiFi. A -=new=- Nintendo 3DS XL with the 9.8.0-25U firmware was used to verify functionality of 'Homepass'.
The PiPass pre-made image has drivers pre-installed for Ralink, ZyDAS ZD1211/1211B, Atheros AR5007UG, and Realtek chipsets. The WiFi chipset that I tested on was the Ralink RT5370.
PiPass can be installed in three ways:
-
Downloading and installing a pre-made image for your Raspberry Pi 2.
-
Downloading and using a automatic installer for all Raspbian / Debian distributions. This will include the original Raspberry Pi Model B and Raspberry Pi Model B+.
-
Downloading the source code and installing PiPass manually. Others have used the manual install to fit certain Raspberry Pi customization that they have and others have successfully installed PiPass on their router running custom firmware (e.g., Tomato). Manual setup will be more work, but it has the advantage of being used on many Linux based devices that support Python.
Before moving onto your chosen installation method, please ensure that your Raspberry Pi is connected to your router via a Ethernet cable and that your WiFi USB dongle is plugged into your Raspberry Pi as well.
Currently, the pre-made image can only be used for the Raspberry Pi 2. PiPass can be downloaded through these mirrors:
The PiPass image was built using Minibian, a light weight image based on the Raspbian operating system. The smallest SD card at my availability was 4GB, so a 4GB SD card will be required at minimum. The actual "real" size of everything is just a little over 500MB.
If you are not sure on how to install an image onto your SD card, the following guide here does an excellent job in explaining how to do this for all three major platforms:
Once you have the PiPass image onto your SD card, you can now load PiPass into your Raspberry Pi. Though this is not necessary, if you need to log into your Raspberry Pi, the following guide is good if you will be accessing remotely through another computer:
Root access is only configured and the username and password is:
+ Username: root
+ Password: PiPass
For security sake, PiPass will only work on the Nintendo 3DS systems that you authorize. Access the PiPass Dashboard by opening up a web browser on a device of your choice and enter your Raspberry Pi's IP address into the address bar. The PiPass Dashboard should be displayed. Go to your Nintendo 3DS and open up your connection settings to find out your 3DS' MAC address. Once you have your MAC address, you can add it to the authenticated list by doing the following:
+ Click "PiPass".
+ Click "Settings".
+ Enter your 3DS' MAC address on a separate line and in the format of XX:XX:XX:XX:XX:XX.
+ Click "Save".
With your 3DS' MAC address saved, you will want to start PiPass:
+ Click "PiPass".
+ Click "Start".
+ Click "Start PiPass".
Wait a few seconds for the PiPass services to fully startup. At this point, you may have StreetPasses waiting for you already. If not, you may want to check the PiPass Logs for detailed information:
+ Click "Dashboard".
+ Click "PiPass Logs".
Generally speaking, if hostapd services are running, you should be OK. The PiPass logging system will send a warning message if a driver issue or invalid MAC address is suspected to be a problem.
If the PiPass logging system is sending a warning message regarding invalid MAC addresses, then you should make a note of the offending MAC addresses and double check if you have entered them correctly. PiPass will automatically skip invalid MAC addresses and move to the next valid Nintendo Zone in the list. Please note that some MAC addresses appear to be valid, but they are actually invalid according to hostapd. In these cases, it is best to edit PiPass DB. More information about editing PiPass DB can be found in the sections below.
For WiFi driver issues, the PiPass pre-made image has drivers pre-installed for Ralink, ZyDAS ZD1211/1211B, Atheros AR5007UG, and Realtek chipsets. Check to see if your WiFi adapter is based on one of these chipsets and make sure that it can function as an "Access Point". There might be some changes that you will need to do. I've tried to make these changes easy, so if it is a driver issue, you may want to use the PiPass Dashboard to configure the correct driver:
+ Navigate to the PiPass Dashboard with your web browser.
+ Click "PiPass".
+ Click "Settings".
+ Enter the correct driver name for "Hostapd Driver".
+ Click "Save".
If problems persist, refer to the manual guide for some extra help.
NOTE: The automatic installer is considered BETA at the moment. It works for me on a clean and configured image of Minibian and it should work just the same on a clean and configured image of Raspbian. If there are some issues with the installer, please let me know.
The PiPass automatic installer is meant to help those install PiPass on all models of the Raspberry Pi. Depending on the operating system, the automatic installer will work on all Raspbian / Debian distributions. Before you begin, the automatic installer assumes that you have a operating system already installed and configured on your Raspberry Pi.
The installer can be downloaded through Google Drive or through Dropbox. After downloading, simply copy install_pipass.sh to your Raspberry Pi and execute it through the terminal. There may be some permission issues, so run this command in the same directory in where you copied install_pipass.sh:
-> sudo chmod 755 install_pipass.sh
While in the same directory as install_pipass.sh, run this command to begin the installation:
-> ./install_pipass.sh
Once the installation is completed, your Raspberry Pi will restart. On another device, open up the web browser and enter the IP address of your Raspberry Pi to access the PiPass Dashboard.
For security sake, PiPass will only work on the Nintendo 3DS systems that you authorize. Go to your Nintendo 3DS and open up your connection settings to find out your 3DS' MAC address. Once you have your MAC address, you can add it to the authenticated list by doing the following:
+ Click "PiPass".
+ Click "Settings".
+ Enter your 3DS' MAC address on a separate line and in the format of XX:XX:XX:XX:XX:XX.
+ Click "Save".
With your 3DS' MAC address saved, you will want to start PiPass:
+ Click "PiPass".
+ Click "Start".
+ Click "Start PiPass".
Wait a few seconds for the PiPass services to fully startup. At this point, you may have StreetPasses waiting for you already. If not, you may want to check the PiPass Logs for detailed information:
+ Click "Dashboard".
+ Click "PiPass Logs".
Generally speaking, if hostapd services are running, you should be OK. The PiPass logging system will send a warning message if a driver issue or invalid MAC address is suspected to be a problem.
If the PiPass logging system is sending a warning message regarding invalid MAC addresses, then you should make a note of the offending MAC addresses and double check if you have entered them correctly. PiPass will automatically skip invalid MAC addresses and move to the next valid Nintendo Zone in the list. Please note that some MAC addresses appear to be valid, but they are actually invalid according to hostapd. In these cases, it is best to edit PiPass DB. More information about editing PiPass DB can be found in the sections below.
For WiFi driver issues, the PiPass automatic installer installs drivers for Ralink, ZyDAS ZD1211/1211B, Atheros AR5007UG, and Realtek chipsets. Check to see if your WiFi adapter is based on one of these chipsets and make sure that it can function as an "Access Point". There might be some changes that you will need to do. I've tried to make these changes easy, so if it is a driver issue, you may want to use the PiPass Dashboard to configure the correct driver:
+ Navigate to the PiPass Dashboard with your web browser.
+ Click "PiPass".
+ Click "Settings".
+ Enter the correct driver name for "Hostapd Driver".
+ Click "Save".
If problems persist, refer to the manual guide for some extra help.
Before you begin, there is a great guide that explains in detail on how to setup a Homepass Relay Station. It is a good read and I encourage everyone to take a look at it. It is especially helpful to those who are having WiFi driver issues. The guide, written by Semperverus, can be found here. The following instructions will assume you are familiar with Linux and will briefly explain the installation process.
Here is a list of dependencies needed for PiPass, so install the following packages through these commands:
-> sudo apt-get install apache2 -y
-> sudo apt-get install bridge-utils -y
-> sudo apt-get install hostapd -y
-> sudo apt-get install iputils-ping -y
-> sudo apt-get install p7zip-full -y
-> sudo apt-get install php5 -y
-> sudo apt-get install python -y
-> sudo apt-get install sudo -y
This would also be a good point where you would install the correct WiFi driver for your WiFi USB dongle. As a reference, these are the WiFi drivers that the PiPass pre-made image uses:
-> sudo apt-get install firmware-ralink -y
-> sudo apt-get install firmware-realtek -y
-> sudo apt-get install zd1211-firmware -y
You may want to install the following in addition to the correct WiFi driver:
-> sudo apt-get install firmware-linux-nonfree -y
-> sudo apt-get install wireless-tools -y
Now download PiPass from the 1.52 branch as a zip file and extract the contents on your local machine. You will notice three directories inside PiPass: etc, opt, and var. These three directories are the locations where you want to install PiPass (e.g., Linux root locations would be /etc/, /opt/, and /var/). Go ahead and merge the directories and it will be safe to overwrite the files with PiPass' configuration files.
Most of the features controlled by PiPass can actually be ran through the PiPass Dashboard. Since your Raspberry Pi will act as a web server as well, you will need to make sure it has the permissions to do so. The following commands can grant execution:
-> sudo chmod -R 755 /opt/PiPass/
-> sudo chmod -R 755 /var/www/
Now this part is a little more involved as we will need to grant the Dashboard some rights for execution. Typically, you would not want to do this on a public webpage, but since PiPass is ran locally and that we have some security measures in place, it should be fine. We'll need root access, so run the following commands:
-> su
-> visudo -f /etc/sudoers
Now add the following line at the end of the file:
+ www-data ALL=(ALL:ALL) NOPASSWD: ALL
For security sake, PiPass will only work on the Nintendo 3DS systems that you authorize. Access the PiPass Dashboard by opening up a web browser on a device of your choice and enter your Raspberry Pi's IP address into the address bar. The PiPass Dashboard should be displayed. Go to your Nintendo 3DS and open up your connection settings to find out your 3DS' MAC address. Once you have your MAC address, you can add it to the authenticated list by doing the following:
+ Click "PiPass".
+ Click "Settings".
+ Enter your 3DS' MAC address on a separate line and in the format of XX:XX:XX:XX:XX:XX.
+ Click "Save".
Likewise, you can add the MAC address of your Nintendo 3DS by entering the following command:
-> sudo nano /etc/hostapd/mac_accept
Like the dashboard, each MAC address should be on a new line.
With the previous steps completed, you will want to start PiPass. In the PiPass Dashboard:
+ Click "PiPass".
+ Click "Start".
+ Click "Start PiPass".
Wait a few seconds for the PiPass services to fully startup. At this point, you may have StreetPasses waiting for you already. If not, you may want to check the PiPass Logs for detailed information:
+ Click "Dashboard".
+ Click "PiPass Logs".
Generally speaking, if hostapd services are running, you should be OK. The PiPass logging system will send a warning message if a driver issue or invalid MAC address is suspected to be a problem.
If the PiPass logging system is sending a warning message regarding invalid MAC addresses, then you should make a note of the offending MAC addresses and double check if you have entered them correctly. PiPass will automatically skip invalid MAC addresses and move to the next valid Nintendo Zone in the list. Please note that some MAC addresses appear to be valid, but they are actually invalid according to hostapd. In these cases, it is best to edit PiPass DB. More information about editing PiPass DB can be found in the sections below.
For WiFi driver issues, check to see if your WiFi driver is correctly installed and working. There might be some changes that you will need to do. I've tried to make these changes easy, so if it is a driver issue, you may want to use the PiPass Dashboard to configure the correct driver:
+ Navigate to the PiPass Dashboard with your web browser.
+ Click "PiPass".
+ Click "Settings".
+ Enter the correct driver name for "Hostapd Driver".
+ Click "Save".
If problems persist, Semperverus' guide is an excellent resource for troubleshooting. With luck, you should have PiPass working manually.
The PiPass Dashboard can be accessed on a device on your network by typing in your Raspberry Pi's IP address on your computer's or mobile device's browser. Most of what you need can be accessed through the Dashboard, including the ability to configure PiPass.
By default, PiPass will be a particular Nintendo Zone for 30 minutes, before moving onto the next one. This should give you enough time to play all the mini-games before you get your next batch. If this time is too long or too short for you, you can edit this setting through the PiPass Dashboard.
Like most of the settings, this feature can be enabled or disabled through the PiPass Dashboard. Enabling shuffling will visit Nintendo Zones in your current list in random order, ensuring that each pass-through is different.
The baseline database will use the Nintendo Zones worksheet found on FatMagic's database. This section will show you how to set up a custom source where you can easily define multiple custom configurations and load them on demand.
+ Use your own or create a Google account to store your database.
Now, make a copy of this spreadsheet and save it on Google Drive.
+ You can copy the spreadsheet easily by clicking "File" -> "Make a copy...".
Publish your spreadsheet to the Web by clicking:
+ "File" -> "Publish to the web..."
+ "Publish"
Also, make sure to copy the URL link of that spreadsheet. Now, open up the PiPass Dashboard:
+ Navigate to the PiPass Dashboard with your web browser.
+ Click "PiPass".
+ Click "Settings".
"PiPass DB Key" will be of interest. Take your spreadsheet's KEY and replace the previous KEY value. For example, the URL you just copied would look something like this:
+ https://docs.google.com/spreadsheets/d/1OfgyryUHeCPth76ziFT985XNLS-O5EXtjQDa0kA1L6M/pubhtml
The KEY would be the value 1OfgyryUHeCPth76ziFT985XNLS-O5EXtjQDa0kA1L6M between /d/ and /pubhtml. So copy that KEY value and replace it with the previous KEY value.
Now you will need to enter the worksheet you want to use. "PiPass DB Worksheet" controls which worksheet to use. The default value of 1 selects the very first worksheet and the value of 2 selects the second worksheet. For example, setting PiPass DB Worksheet to the value of 2 would use the "nintendo_zones" worksheet in the templated spreadsheet that you just copied.
NOTE: When creating your own PiPass DB, please keep the formatting of the Google Spreadsheet consistent with the default PiPass DB. You may add / remove worksheets and change the content, but do not introduce new formatting (e.g., colouring of cells) as Google may return incorrect identifiers that PiPass will not understand.
This feature can be enabled or disabled through the PiPass Dashboard. Enabling security will make PiPass use the 3DS MAC addresses that are inputted in '3DS Authentication'. Disabling security will allow anyone access to your network. When disabling security, discretion is advised.
The authenticated list of 3DS systems that are allowed to connect to PiPass. Enter the 3DS MAC addresses on a separate line and in the format of XX:XX:XX:XX:XX:XX. This option can be found through the dashboard.
In most cases, the default hostapd driver will work. However, the driver is configurable through the dashboard if need be.
There are some users who use a different Linux configuration when manually installing. Configuring the dashboard install path through the PiPass Dashboard allows one the flexibility in choosing which web server is best for their purpose. However, PiPass will assume that the main program is installed in /opt/PiPass/. The PiPass Dashboard is configurable in that you may choose to install it somewhere else.
PiPass can be updated through the dashboard. This will pull updates from the master branch and provide PiPass with 'bleeding edge' updates. This is especially useful for those who are unfamiliar with Linux. Updating can be done by:
+ Click 'PiPass' in the dashboard.
+ Click 'Update'.
Please allow for 30 seconds for all the updates to complete.
This will force your Raspberry Pi to re-detect and reconfigure all Ethernet and Wifi devices. PiPass uses your very first installed WiFi dongle, so if you want PiPass to use another one instead, please remove all WiFi dongles connected to your Raspberry Pi and ensure that the one you want to use is connected before you reset the network.
I have listed some kits that are quite good if you will be purchasing a Raspberry Pi for the first time. I'm not asking for any donations, but if you will be purchasing any hardware, these Amazon referral links would be helpful. The pricing on these items are exactly the same as a non-referral.
Please let me know if any other hardware is compatible and I will add them to this list.
Mini RT5370 150Mbps USB Wifi Wireless LAN Card 802.11 N/g/b Adapter with Antenna
Raspberry Pi 2 Model B Project Board - 1GB RAM - 900 MHz Quad-Core CPU
Protronix 150Mbps USB Wireless Network WIFI Adapter for Laptop Notebook 802.11N/G
Wifi With Antenna For Raspberry Pi - Instructions Included - PLUG and PLAY
I want to expand the functionality of PiPass by adding the following:
- Borrowing a Raspberry Pi Model B and Raspberry Pi Model B+ for an expanded list of pre-made images.
- I am always looking for suggestions, but I cannot guarantee that I will implement a requested feature. I will try my best though!
If you have any problems with PiPass, please let me know through my GitHub. I will do my best to help you out.