Guide for how to install our open-source Pokémon automation software, SerialPrograms on Mac. This works for both Intel CPU and M1. Note we don't have optimization for M1 yet. So running on M1 macbook could be much slower.
The guide involves some program development processes. But the guide is aimed for any Mac user. You don't need to know programming to follow the guide.
If you have any questions regarding the documentation or find any errors in the doc, feel free to contact us directly in our Discord server.
Warning: if you don't have software development experience and deviate from the guide steps, you are at your own risk.
Go to Mac App Store App, install XCode App. This is a program made by Apple for software development. It also comes with basic software tools to build SerialPrograms. So it's safe to install it first.
Homebrew is a Mac software that manages software packages. SerialPrograms relies on several other open-source software components (called libraries, or packages by software developers). Homebrew is a tool to download and manage those packages.
To install it, the instruction on Homebrew home page is to use the command:
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
Note: if the current Homebrew home page has a different instruction than the one above, follow that from the home page. If you don't know how to do that, contact us.
The command above is to be executed in the Terminal App. macOS comes with Terminal App. Launch Terminal App, paste the command inside, press Enter on the keyboard to execute the command.
Apps like Terminal are often shown in movies and shows as what hackers work with on their computers. If you haven't used one before, be extra careful! The command you put into Terminal may end up deleting your files without easy way to recover or even destroy your macOS! Only execute the commands in this guide in Terminal.
Follow the prompted texts in Terminal to finish the installation.
- You will need to type your macOS password to give permission to install Homebrew.
- It will ask you to install Command Line Tools for XCode. XCode is the software development program made by Apple. It has some toolsets needed to build SerialPrograms. Follow the text guide on Terminal and install Command Line Tools for XCode.
- After installation finishes, the prompted text will say
==> Next steps:
- Run these three commands in your terminal to add Homebrew to your PATH:
echo '# Set PATH, MANPATH, etc., for Homebrew.' >> /Users/<YOUR_MAC_USERNAME>/.zprofile
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> /Users/<YOUR_MAC_USERNAME>/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"
Copy each of the three lines of commands (two starts with "echo" and one starts with "eval") into Terminal and press Enter to execute them. You need to copy one line, press Enter to execute it, then move on to the next line. You cannot execute all three lines in one single copy-paste. These commands make the installed Homebrew and future packages it will install, accessible in Terminal.
Note: if the prompted text after installation finishes has a different set of commands than the one above, follow that from your Terminal. If you don't know how to do that, contact us.
You can verify Homebrew installation is successful by executing brew help in Terminal.
You should see a screen of Homebrew instruction shows up like
Example usage:
brew search TEXT|/REGEX/
brew info [FORMULA|CASK...]
brew install FORMULA|CASK...
brew update
brew upgrade [FORMULA|CASK...]
brew uninstall FORMULA|CASK...
brew list [FORMULA|CASK...]
Note: you can scroll up and down in Terminal to see texts outside of the current screen.
CMake is a software tool that helps compile programs. Install it using Homebrew by running in Terminal
brew install cmake
Note: if you type a wrong letter in Terminal, press Delete key to delete it, or press Control-C to void the entire line and start with a new line to input command.
We use Qt6 software library to build UI (windows, panels, buttons...) for SerialPrograms. Install it by running in Terminal
brew install qt6
We need Tesseract software package to support our OCR (optical character recognition) technique to read texts from images.
Install it by running in Terminal
brew install tesseract
After installation, the prompted text may tell you that
==> Caveats
This formula contains only the "eng", "osd", and "snum" language data files.
If you need any other supported languages, run `brew install tesseract-lang`.
This says currently installed Tesseract can only read English. If your game language is not English, run in Terminal
brew install tesseract-lang
to install other languages. Contact us if you have questions when installing other languages.
OpenCV is a software package for various computer vision algorithms. We need it for using advance video inference methods. Install it by running in Terminal
brew install opencv
Before building the code of the automation program, make sure the software that builds the code into program is up-to-date. This software is called compilers by programmers. Apple provides a compiler called Clang on macOS. Verify its version by executing the command in Terminal:
g++ --version
You should see the output like
Apple clang version 14.0.0 (clang-1400.0.29.102)
Target: arm64-apple-darwin21.6.0
Thread model: posix
InstalledDir: /Library/Developer/CommandLineTools
The exact version, target and installed directory may be different on your machine. But as long as your Clang version is higher than 13.0.0, you should be fine to proceed.
If you find your Clang version is too low, check this tutorial to address it.
Go to SerialPrograms Github webpage.
If you know how to use Git to download code from Github, you can use Git and pick a release version based on Git branch names.
Otherwise, download code directly as follows. By default, when you visit this webpage, it lets you download the newest under-development version. The version may contain automation programs that are not fully developed or have major bugs. To use one of our stable release versions, first check the version numbers by pressing the dropdown menu currently shown as "main" on the webpage, on the same row as the green "Code" button. The dropdown menu shows recent version numbers. As the time of updating this guide (JAN 10, 2023), the newest version is "v0.26". You can pick the latest version you find. Once you select a version, the text of the dropdown menu will be changed from "main" to that version.
After that, click the green "Code" button. It will show several download options. You can pick "Download ZIP" to download the code as a ZIP file. The code you download will be from the version you picked. The default ZIP filename will be "Arduino-Source-<VERSION_NUMBER>.zip"
Place the code into a suitable folder you like. But avoid placing it in a "remote/cloud" folder like in OneDrive. Cloud folders may give some trouble for programs running on those folders. Also avoid placing it in your macOS account's "Desktop" folder or "Documents" folder. macOS has strict folder access management. It may reject the program from accessing data in those folders. An example path is
/Users/<YOUR_MAC_USERNAME>/games/pokemon/
If you download as a ZIP, unzip it to a suitable folder.
The downloaded code should be in a folder called "Arduino-Source". Using the above example, the full path of the folder is
/Users/<YOUR_MAC_USERNAME>/games/pokemon/Arduino-Source
SerialPrograms need some extra data (images, audio files and Pokémon data text files) to run. Go to our Packages Github webpage and download the data same as before but you don't need to pick the versions.
The downloaded data will be inside a folder called "Packages". Inside it there is a sub-folder called "SerialPrograms". Further inside is a sub-sub-folder "Resources". Move this "Resources" folder into the "Arduino-Source" folder you downloaded before. Make sure it is placed directly inside "Arduino-Source", not deeper into the folder hierarchy.
Click the "Arduino-Source" folder to select it in Finder App. Command-C to copy the folder, then go to Terminal, type cd, followed by a Space key, then Command-V to paste the folder. It actually paste the folder path in macOS file system to the Terminal. So you would have
cd <YOUR_PATH_TO_ARDUINO-SOURCE_FOLDER>
in your Terminal. Press Enter to execute it.
cd command moves the current active folder in Terminal to a new folder. Now your Terminal are running on "Arduino-Source" folder. Verify this by executing
ls
in Terminal. It will list the files and folders in "Arduino-Source" folder.
Make sure the current active folder in Terminal is the "Arduino-Source" folder, then execute the command in Terminal:
mkdir -p build_mac; cd build_mac
This makes a new folder called "build_mac" in "Arduino-Source" and move the Terminal's current active folder to the new folder.
Execute the command in Terminal:
cmake ../SerialPrograms/ -DUNIX_LINK_TESSERACT:BOOL=true -DCMAKE_BUILD_TYPE:STRING=Release -Wall
This command uses CMake to configure our code to prepare for compilation. If successful, it should print texts like
...
-- Configuring done
-- Generating done
-- Build files have been written to: <YOUR_PATH_TO_ARDUINO-SOURCE_FOLDER>/build_mac
Make sure the current active folder in Terminal is "build_mac", then execute the command in Terminal:
cmake --build . -j 10
to compile and build the program in "build_mac" folder. It will take a while to build dependent on your computer speed.
If successful, it will print
[100%] Built target SerialPrograms
in the end in Terminal.
We have built the program on our mac computers, so in most cases you won't see any error during building. But in case your machine has very different hardware or software environment as ours, and as a result it prints out error messages about the code, please reach out to us in our Discord server for help.
Now SerialPrograms is built! Run the program in Terminal by the command
./SerialPrograms
When you plan to run the program for a long period of time, you need to prevent your Mac from going to sleep.
Go to System Preferences App -> Battery -> select the checker box "Prevent your Mac from automatically sleeping when the display is off".
Enjoy shiny hunting!
To upgrade, in most cases you just need to repeat the process starting at Download Codebase.
In rare cases when we add new software library dependencies, just follow the guide to install those new libraries. If we upgrade our Qt dependency to a higher Qt version, use Homebrew to upgrade it by running
brew upgrade qt6
in Terminal.