PokeAlarm Documentation - Read the Docs

PokeAlarm DocumentationRelease 3.6

PokeAlarm Team

Mar 03, 2018

Initial Setup

1 Installation 3

2 FAQ 5

3 Server Settings 9

4 Events 15

5 Filters 19

6 Alarms 25

7 Managers 29

8 Geofences 33

9 Rules 39

10 Getting Started 41

11 JSON Formatting Help 49

12 3.5 -> 3.6 Alarm Upgrade Tool 51

13 Bug Reports / Feedback 53

14 Webhook Standard 55

15 Webhook Tester 61

16 Patch Notes 63

17 Object Caching 75

18 Docker 77

19 Location Services 81

20 Contributing 93

i

21 Indices and tables 95

ii

PokeAlarm Documentation, Release 3.6

PokeAlarm is a highly configurable application that filters and relays alerts about Pokemon Go to your favorite onlineservice, allowing you to be first to know of any rare spawns or raids.

Initial Setup 1

https://discord.gg/S2BKC7p

https://www.patreon.com/pokealarm

https://github.com/PokeAlarm/PokeAlarm

https://github.com/PokeAlarm/PokeAlarm/issues


2 Initial Setup

CHAPTER 1

Installation

This guide will walk you through installing a fresh copy of PokeAlarm.

Table of Contents

• Prerequisites

• Installing

• Running

• Updating

1.1 Prerequisites

This guide assumes the following:

• Latest version of Python 2.7 installed.

• Git installed.

• Monocle, RocketMap, or another supported scanner successfully installed.

• You are using a quality text editor like Notepad++, Nano, or Vi(m).

Warning: Do NOT use (or even open) any files with Notepad or TextEdit - they change the encoding on the fileand prevent it from loading correctly.

3

https://www.python.org/download/releases/2.7/

https://git-scm.com/downloads

https://github.com/Hydro74000/Monocle

https://github.com/RocketMap/RocketMap


1.2 Installing

1. Clone a local copy of PokeAlarm - Navigate a new folder to install PokeAlarm in (It is recommended youstore it in a different folder than your scanner). In a terminal, run the command git clone https://github.com/PokeAlarm/PokeAlarm.git to create a local copy of the project. This create a foldercalled ‘PokeAlarm’ that will contain the application.

2. Install the Requirements - In a terminal, navigate into the root folder of your PA installation. Runpip install -r requirements.txt --upgrade. This will install and update the modules thatPokeAlarm needs to run.

3. Configure PokeAlarm - Next you need to configure PokeAlarm.

• Server Settings let you configure things like host IP, port, language, and more.

• Filters represent which Events trigger notifications. You will need to create a filters file before starting PA.

• Alarms represent where and how notifications. You will need to create an alarms file before starting PA.

1.3 Running

1. Start PokeAlarm - In a terminal, use the command python start_pokealarm.py to start PokeAlarmand begin listening for information. If successful, you will see the following in the output:

Note: PokeAlarm installs some dependencies on the fly. If you encounter errors when first running a new service, tryrunning as root (with sudo) to ensure it can install the dependency.

2. Setup Scanner Webhook - Next, configure your scanner to send information to PA’s address.

• For Monocle: The webhook info only works in Hydro’s fork.

• For RocketMap: Configure the webhook types to send info as explained in RocketMap wiki.

Finally, start your scanner. If everything is set up correctly, PA will start logging information about what it isdoing to the console.

1.4 Updating

Warning: Updating PokeAlarm can be complicated if you edit files you aren’t supposed to. For this reason, werecommend not to edit any files ending in .py.

1. Check the Patch Notes for any big changes that might break your current configuration.

2. Open up a command line and change directory to the root folder of your install.

3. Run the command git pull && pip install -r requirements.txt to update to the latest ver-sion.

4 Chapter 1. Installation

https://github.com/Hydro74000/Monocle

https://rocketmap.readthedocs.io/en/develop/extras/webhooks.html

CHAPTER 2

FAQ

2.1 Overview

• General Info

• Troubleshooting

2.2 General Info

These are general questions about PA and it’s development.

2.2.1 Where should I go for support?

• If, after carefully reading the Wiki and the rest of this FAQ, you can visit our Discord. Make sure to read therules channel, so you don’t inadvertently get banned.

2.2.2 What scanners are supported?

• Currently RocketMap (RM) and Monocle are compatible with PA. If you are interested in adding support foryour program, feel free to read the Webhook Standard and ask us in Discord what you can do to add support forPA.

2.2.3 I have a great idea for a new feature!

• Open a Feature Request on our Github page. Use the correct template

• Please DO NOT just ask for a feature in Discord. There is a lot of chat in discord and your request will certainlyget lost. Issues let us track the request and real with it in a more concrete manor.

• If you see a request you like, be sure to comment on it to show your support!

5

https://discordapp.com/invite/S2BKC7p

../miscellaneous/webhook-standard.html

https://github.com/PokeAlarm/PokeAlarm/issues/new


2.2.4 Do you accept PRs?

• Yup - you can submit them via Github. If it is a big change, feel free to approach us before so we can coordinatebetter.

2.2.5 Do you support new services?

• Please check in the New/Upcoming Services MEGA-THREAD to see if the service has already been requested.If it hasn’t, feel free to leave a post requesting it.

2.2.6 How can I support PokeAlarm?

• Besides submitting PRs or helping us with the Wiki, you can support Deadly (the creator of PA) on Patreon.

2.3 Troubleshooting

2.3.1 PokeAlarm complains about a ValueError error and says I need to talk tosome guy named JSON?

1. Make sure you didn’t open any files with Notepad or TextEdit - they can break the encoding on your files. UseNotepad++ or a better editor.

2. If you sure that isn’t the problem, then you probably have an error with your JSON Formatting. Look up howJSON formatting works and use a JSON Editor to find your problem.

2.3.2 Why isn’t <gym_name> working right?

• You must have gym-details enabled in your scanner and webhook options.

• Most scanners don’t send the gym-details with every gym related webhook - PA will cache the details and try toremember them, but this goes away upon restart. It takes time for the scanner to send all the details.

You can use file-caching to save the gym names to a file so that they are available upon restart. Check out the ObjectCaching page for more information.

2.3.3 How can I optimize PokeAlarm?

PA uses Gevent and Multiprocessing to be as responsive as possible to incoming requests. However (due to languageand hardware limitations), it is possible for PA to be overwhelmed and have a hard time handling requests for largesetups. If you are experiencing problems, you can try the following options:

1. If on Windows, try Linux (even a VM will see large improvements).

2. Run PA on a separate server.

3. Lower the number of managers you are using. Each manager runs in its own process, which makes it expensive.

4. If possible, separate scanners and pa instances into smaller groups and even onto different servers.

5. Upgrade your server hardware.

6 Chapter 2. FAQ

https://github.com/RocketMap/PokeAlarm/issues/147

https://github.com/PokeAlarm/PokeAlarmWiki

https://www.patreon.com/pokealarm

http://www.jsoneditoronline.org/

../miscellaneous/object-caching.html

../miscellaneous/object-caching.html


PA also has a concurrency setting that can be lowered - it limits the number of active connections allowed to it.This will prevent PA

Additionally, there are a number of settings in RM to optimize:

1. Disable extra webhooks - use RM’s blacklist/whitelist and disable webhook types you aren’t using.

2. Lower webhook-threads (wh-concurrent or similar) - This will cause RM to send less connections at once.

3. Increase wh-frame-interval - Increase the number of events RM sends at once to lower overhead.

4. Increase wh-lfu-size - this will increase RM’s cache size to repeat less information.

5. Increase wh-backoff-factor - Increase break between webhooks.

6. Increase wh-connect-timeout and #wh-read-timeout timeouts for RM. This gives your server moretime to react.

7. Decrease database threads db-concurrency or similar - uses less sockets.

Note: Decreasing/Increase these settings may cause queue build up in a variety of different places. It is a matter oftrial and error to find the ideal settings for your setup.

Try the RM (or PA) Discord for more info.

2.3.4 Error 10053 on Windows or Error 53 on Linux?

• This is an issue with too many open sockets on windows that causes PA to be unable to open an new connections.See the above steps for some suggestions on optimization.

2.3.5 RocketMap repeatedly spams Caused by ReadTimeoutError("HTTPConnectionPool(host='127.0.0.1', port=4000)?

• This mean’s that RM is not connecting to PA for some reason:

1. Make sure PA is running.

2. Make sure RM is sending to the correct IP:PORT combo.

3. If the PokeAlarm instance is on a remote server, try increasing RM’s wh-timeout parameter (which defaultsto 1s).

4. Check hardware for a bottleneck. See above for optimizations.

2.3.6 Why do some DTS (<iv>, etc) or another DTS show up as ??

• PA replaces DTS that are used with ?, ???, or unknown when it doesn’t know the correct information. Thiscould be a variety of reasons

2.3.7 Map images aren’t showing up correctly... What can I do?

• Make sure you have added a Location Services and have the Static Maps API enabled. If you already have itenabled, make sure that you haven’t hit the limit for free users.

2.3. Troubleshooting 7

../miscellaneous/location-services.html


2.3.8 Missing icons in your alerts?

• Remove your lines from icon_url and avatar_url from your Alarms to use the default images in the PA.

2.3.9 Do you want to use custom images in your alerts?

• Add in your alarms the option to add images (depends on the service that is used) and add your url where theimages are. For example, if you use Discord it will be something like this:

"icon_url":"https://raw.githubusercontent.com/user/PokeIcons/master/icons/<pkmn_id>.→˓png"

8 Chapter 2. FAQ

../configuration/alarms/discord.html

CHAPTER 3

Server Settings

3.1 Overview

This guide will walk you through configuring server settings for PokeAlarm.

• Prerequisites

• Server Settings

• Command Line

• Configuration File

3.2 Prerequisites


1. You have correctly installed PokeAlarm.

2. You are using Notepad++, Nano, or Vi(m) to configure any files. Do NOT use or open any files with Notepador TextEdit - they will break your files!

3.3 Server Settings

Settings for the PokeAlarm server can be done the following two ways:

1. Command Line - When starting PokeAlarm, you can specify certain settings with flags following thestart up command. For example, you can change the IP that PokeAlarm binds itself to by using eitherpython start_pokealarm.py -H 192.168.0.1 or python start_pokealarm.py --host192.168.0.1.Note: when used together, command line flags will override arguments specified in the config-uration file.

9

../getting-started/installation.html


2. Configuration File - You can also use a configuration file in ini format to set server settings for PokeAlarm.These settings use the same flags at the command line. For example, you either host: 192.168.0.1 orH: 192.168.0.1 line to the configuration file to change the IP that PokeAlarm binds itself to.

For files, all relative paths will being from the PokeAlarm root folder, but absolute file paths can still be used.

3.4 Command Line

To get the most recent command line settings for your version, use the following command: pythonstart_pokealarm.py --help.

usage: start_pokealarm.py [-h] [-cf CONFIG] [-d] [-H HOST] [-P PORT][-C CONCURRENCY] [-m MANAGER_COUNT][-M MANAGER_NAME] [-f FILTERS] [-a ALARMS][-r RULES] [-gf GEOFENCES] [-l LOCATION][-L {de,en,es,fr,it,ko,pt,zh_hk}][-u {metric,imperial}] [-tz TIMEZONE] [-k GMAPS_KEY][--gmaps-rev-geocode GMAPS_REV_GEOCODE][--gmaps-dm-walk GMAPS_DM_WALK][--gmaps-dm-bike GMAPS_DM_BIKE][--gmaps-dm-drive GMAPS_DM_DRIVE][--gmaps-dm-transit GMAPS_DM_TRANSIT][-ct {mem,file}] [-tl TIMELIMIT] [-ma MAX_ATTEMPTS]

optional arguments:-h, --help Show this help message and exit.-cf CONFIG, --config CONFIG

Configuration file.-d, --debug Debug Mode.-H HOST, --host HOST Set web server listening host.-P PORT, --port PORT Set web server listening port.-C CONCURRENCY, --concurrency CONCURRENCY

Maximum concurrent connections for the webserver.-m MANAGER_COUNT, --manager_count MANAGER_COUNT

Number of Manager processes to start.-M MANAGER_NAME, --manager_name MANAGER_NAME

Names of Manager processes to start.-f FILTERS, --filters FILTERS

Filters configuration file. default: filters.json-a ALARMS, --alarms ALARMS

Alarms configuration file. default: alarms.json-r RULES, --rules RULES

Rules configuration file. default: None-gf GEOFENCES, --geofences GEOFENCES

Alarms configuration file. default: None-l LOCATION, --location LOCATION

Location, can be an address or coordinates.-L {de,en,es,fr,it,ko,pt,zh_hk}, --locale {de,en,es,fr,it,ko,pt,zh_hk}

Locale for Pokemon and Move names: default en," + "check locale folder for more options.

-u {metric,imperial}, --units {metric,imperial}Specify either metric or imperial units to use fordistance " + "measurements.

-tz TIMEZONE, --timezone TIMEZONETimezone used for notifications. Ex:"America/Los_Angeles"

-k GMAPS_KEY, --gmaps-key GMAPS_KEY

10 Chapter 3. Server Settings


Specify a Google API Key to use.--gmaps-rev-geocode GMAPS_REV_GEOCODE

Enable Walking Distance Matrix DTS.--gmaps-dm-walk GMAPS_DM_WALK

Enable Walking Distance Matrix DTS.--gmaps-dm-bike GMAPS_DM_BIKE

Enable Bicycling Distance Matrix DTS.--gmaps-dm-drive GMAPS_DM_DRIVE

Enable Driving Distance Matrix DTS.--gmaps-dm-transit GMAPS_DM_TRANSIT

Enable Transit Distance Matrix DTS.-ct {mem,file}, --cache_type {mem,file}

Specify the type of cache to use. Options: ['mem','file'] (Default: 'mem')

-tl TIMELIMIT, --timelimit TIMELIMITMinimum limit.

-ma MAX_ATTEMPTS, --max_attempts MAX_ATTEMPTSMaximum attempts an alarm makes to send anotification.

3.5 Configuration File

A copy of the most recent configuration file should be located at config/config.ini.example. You can copythis file as a starting point.

By default, PokeAlarm will load the file at config/config.ini if it exists. You can manually specify a configu-ration file with either the -cf or --config file via the command line.

# DO NOT USE NOTEPAD OR TEXTEDIT TO EDIT FILES!# USE AN EDITOR SUCH AS NOTEPAD++, ATOM, NANO OR VI(M)# You can create a copy of this config and edit it to suit your needs.# Uncomment a line (remove the #) when you want to change its default value.# By default, PA will use `config/config.ini` to load settings.# You can override the config file selection with `--config-file` or `-cf`.

######################### Webserver Settings########################

#host: 127.0.0.1 # Interface to listen on (default='127.0.0.1')#port: 4000 # Port to listen on (default='4000')#concurrency: 200 # Maximum concurrent connections to webserver→˓(default=200)#manager_count: 1 # Number of Managers to run (default=1)#debug # Enable debug logging (default='False)

########################## Manager Settings########################## All of the settings below this line are manager-specific.# If a single setting is supplied, it will apply to all Managers.# Example: `locale: en` will set all Managers to english# If an array of settings is supplied, they will be apply to Managers in order.# Example: `locale: [ en, fr, en ]` sets a different language for 3 Managers.

3.5. Configuration File 11


# `None` can be used to exempt a Manager from an optional setting

#manager_name: # Name of Manager, used for logging (default='manager#→˓')

# File Settings###################### File settings define location of files with settings for a Manager.# Relative paths are presumed from install folder, root paths are absolute.

#filters: filters.json # Filters for the Manager (default='filters.json')#alarms: alarms.json # Alarms for the Manager (default='alarms.json')#rules: rules.json # Rules for the Manager (default=None)#geofence: geofence.txt # Geofences to be used in Filters (default=None)

# Location Specific######################location: # Location, as address or coordinates (default=None)#locale: en # Language used for DTS translations (default='en')

# Options: ['de', 'en', 'es', 'fr', 'it', 'ko', 'pt',→˓'zh_hk' ]#unit: imperial # Units used to measurements.(default='imperial')

# Options: ['imperial', 'metric' ]#timezone: America/Los_Angeles # Timezones used for notifications. Default uses→˓system time (default=None)

# Options: https://en.wikipedia.org/wiki/List_of_tz_→˓database_time_zones

# GMaps Settings#################gmaps-key: # Google Maps API Key (default=None)#gmaps-rev-geocode: yes # Enable Reverse Geocoded DTS. (default='no')

# Note: This requires the Reverse Geocoding API to be→˓enabled on your GMAPs key.#gmaps-dm-walk: yes # Enable Walking DM DTS. (default='no')

# Note: This requires the Distance Matrix API to be→˓enabled on your GMAPs key.#gmaps-dm-bike: yes # Enable Bicycling DM DTS. (default='no')

# Note: This requires the Distance Matrix API to be→˓enabled on your GMAPs key.#gmaps-dm-drive: yes # Enable Driving DM DTS. (default='no')

# Note: This requires the Distance Matrix API to be→˓enabled on your GMAPs key.#gmaps-dm-transit: yes # Enable Transit DM DTS. (default='no')

# Note: This requires the Distance Matrix API to be→˓enabled on your GMAPs key.

# Miscellaneous#################cache_type: file # Type of cache used to share information between→˓webhooks. (default='mem')

# Options: ['mem', 'file']#timelimit: 0 # Minimum seconds remaining on an Event to trigger→˓notification (default=0)



# Note - `max_attempts` is being deprecated and may→˓be replaced by alarm-level settings#max_attempts: 3 # Maximum number of attempts an alarm makes to send a→˓notification. (default=3)

3.5. Configuration File 13



CHAPTER 4

Events

Table of Contents

• Prerequisites

• Introduction

• Dynamic Text Substitutions

• Missing Information

• Advanced

– Reverse Geocoding

– Distance Matrix

4.1 Prerequisites


• You are using the latest version of PokeAlarm.

4.2 Introduction

In PokeAlarm, an Event represents something of interest that has happened in the World. Events can be severaldifferent things - a new monster spawning, a gym changing teams, or a new raid appearing. There are 5 differentcategories for Events, each with different information:

• monster-events

• stop-events

15


• gym-events

• egg-events

• raid-events

4.3 Dynamic Text Substitutions

Dynamic Text Substitutions (or DTS) are special text that can be used to customize notifications based on the triggeredEvent. These values are surrounded with diamond brackets (< and >) and will by substituted with a value based on theEvent in question. For example, a notification with the following text:

A wild <mon_name> has appeared! It has <iv>% IVs!

Could be substituted to the following:

A wild Charmander has appeared! It has 100.0% IVs!

Or, it could appear like this:

A wild Pidgey has appeared! It has 55.6% IVs!

The DTS that you can use vary by type of Event - make sure to check the page for each type to which DTS can beused.

4.4 Missing Information

Note: You can accept or reject an event based on the state of missing information. See the is_missing_inforestriction on the Filters page for instructions.

When PA doesn’t have the correct information needed to correctly do a substitution, it may replace it with one of thefollowing:

• ?

• ???

• unknown

This can happen for a variety of reasons - but generally is because the scanner did not send the information needed inthe webhook. PA does it’s best to fill in the gaps by sharing and caching information between separate webhooks (likegym names or teams), but some info may require a settings update with your scanner (like IVs or CP).

4.5 Advanced

4.5.1 Reverse Geocoding

Reverse Geocoding is a process that to get the name or data of places where the Events take place. This can be usedto get things such as address, city, state, or more.

PA will only use Reverse Geocoding for Events that have been triggered. Each Event will use up a single point of yourAPI quota, regardless of number of fields or alarms used.

16 Chapter 4. Events


Text Description<street_num> Street number of the alert location<street> Street name of the alert location<address> Address of the alert location, includes both street number and street name, in that order

only<address_eu> Address of the alert location, in european format (street name and street number)<postal> Postal code of the alert location<neighborhood> Neighborhood code of the alert location<sublocality> Sublocality code of the alert location<city> City code of the alert location<county> County code of the alert location<state> State code of the alert location<country> Country code of the alert location

4.5.2 Distance Matrix

Distance Matrix calculations determine how far away an Event is, for both time and distance. This can be Walk-ing, Biking, Driving, or Transit. These calculations require a set location, and a Google Maps API key. For moreinformation, see the Distance Matrix section of the Location Services page.

Text Description<walking_distance> Estimated walking distance to the alert location<walking_duration> Estimated walking time to alert location<biking_distance> Estimated bike distance to the alert location<biking_duration> Estimated bike time to alert location<driving_distance> Estimated drive distance to the alert location<driving_duration> Estimated drive time to alert location<transit_distance> Estimated public transit distance to the alert location<transit_duration> Estimated public transit time to alert location

4.5. Advanced 17


18 Chapter 4. Events

CHAPTER 5

Filters

Table of Contents

• Prerequisites

• Introduction

• Restrictions

• Filters File

• Advanced

– Missing Information

– Geofences

– Custom DTS

5.1 Prerequisites

This pages assumes the following:

• You understand how Events work.

• You understand JSON formatting.


5.2 Introduction

A Filter is what PA uses to decide if it is worth of a notification or not. When PA receives a new Event, it is comparedone by one against the Filters. When PA finds a matching Filter, it triggers a notification.

19

https://www.w3schools.com/js/js_json_intro.asp


Note: By default, PA processes Filters in the order they are listed in the filters file and only triggers on the first match.You can override this behavior by using the advanced Rules feature.

There are 5 different types of Filters, each matching a category of Events:

• monster-filters

• stop-filters

• gym-filters

• egg-filters

• raid-filters

5.3 Restrictions

A Filter is represented as a named JSON Object containing several key-value pairs called restrictions. Each restrictionrepresents a limit on which Events are allowed to pass. Restrictions are explicit (they must be listed to be checked)and associative (all restrictions must be passed to match) A Filter with no restrictions would allow any Event to pass:

"all-filter-name":{}

Note: Filters will only check an Event’s value if a restriction requires it. A Monster’s IV value won’t be checkedunless either min_iv or max_iv is set. As such, you should avoid setting restrictions unless you intend to Filter onthose values.

To add a monsters restriction, you simply describe it inside the object. The following would only allow Monstersof certain species:

"only-starters":{"monsters":["Charmander","Squirtle","Bulbasaur"]

}

Additional restrictions are added in the same way:

"only-high-iv-lvl-starters":{"monsters":["Charmander","Squirtle","Bulbasaur"],"min_iv": 90.0,"min_lvl": 15

}

Each type of Filter has different restrictions, so make sure to check each page carefully.

5.4 Filters File

Note: A filters file (often refereed to as filters.json) is a file containing then Filters that PA uses. By default, PAloads the Filter from the filters.json located in the base folder of the project. See the Server Settings page forinstructions on specifying the file by a different name. This file must contain a single JSON object to load successfully:

20 Chapter 5. Filters


{

}

Inside this JSON object, you need to add sections for each type of Filter you wish to add. Sections are optional, andunspecified sections will be disabled by default.

{"monsters":{},"stops":{},"gyms":{},"eggs":{},"raids":{}

}

Each section can contain the following sub-sections:

The enabled sub-section is a boolean value of either true or false that enables or disables processing of thattype of Event.

The defaults sub-section is a JSON object containing default restrictions that are applied to all Filters in thesection, unless already specified. For example, adding "min_iv": 90 in the monsters defaults section will addthat restriction to all Filters - unless they already have a min_iv restriction.

Note: You can use null to ignore a default value. Even with a default "monsters" restriction set,"monsters":null inside a filter acts as if that the monster restriction is not set.

The filters section is simply a JSON object containing the Filters, configured as described above. Here is anexample of just the monsters section:

"monsters":{"enabled":true,"defaults":{},"filters":{

"filter_by_monsters_example":{"monsters":["Bulbasaur","Charmander",7]

},"filter_by_ivs_example":{

"min_atk": 0, "max_atk": 15,"min_iv": 0.0, "max_iv": 100

},"filter_by_moves_example":{

"monsters":["Bulbasaur"],"quick_moves":["Vine Whip","Tackle"],"charge_moves":["Sludge Bomb","Seed Bomb"]

}}

}

5.4. Filters File 21


5.5 Advanced

5.5.1 Missing Information

As described on the Events page, sometimes an Event is missing information. Erring on the side of caution, a Filterwill skip a restriction if the information needed to check it is missing. If your use the min_iv info, but the IV isunknown for any reason, then by default Filter will skip checking a restriction as if it wasn’t specified.

The is_missing_info restriction can be used to require information to be missing or not. When"is_missing_info":false is set, the Filter requires all checked values to be known. When"is_missing_info":true is set, the Filter does the opposite - at least one checked value must be unknownto pass.

Warning: The is_missing_info restriction only affects checked information. Filters only check informationif a restriction requires it. For example, IV is only checked if either min_iv or max_iv is set. The same is truefor other values.

5.5.2 Geofences

For more information on configuring your geofence.txt, see the Geofences page.

You can require an Event to be inside specific geofences for a Filter.

This example will check if an event is inside either "fence1" or "fence2" as defined in:

"filter_name_1":{"geofences":["fence1","fence2"]

}

Geofences are checked in order. The first geofence with the event inside will be used to define the <geofence>DTS.

If no geofences are set, the <geofence> DTS will always return unknown.

If a geofence with the set name does not exist, it will be skipped and an error will print out to the console.

Another example would be to configure alerts inside all of your geofences. You just have to configure the geofenceslike this:

"filter_name_1":{"geofences":["all"]

}

5.5.3 Custom DTS

Custom DTS is a feature that allows you to specify filter specific DTS to an Event when it passes a filter. Thecustom_dts is a JSON object of key-value pairs. For example, the <family> DTS would be either “Grassstarters” or “Fire starters” depending on the Filter it passed with the following configuration:

Warning: Using custom_dts at a Filter level will override any custom dts from “defaults” level - not just thespecific DTS used.



"filters":{"filter_name_1":{

"monsters":[1,2,3],"custom_dts":{"family":"Grass starters"}

},"filter_name_2":{

"monsters":[4,5,6],"custom_dts":{"family":"Fire starters"}

}}

5.5. Advanced 23



CHAPTER 6

Alarms

Table of Contents

• Prerequisites

• Introduction

• Creating an Alarm

• Customizing Alerts

• Alarms File

6.1 Prerequisites

This guide assumes:

• You understand how Events and Filters work.

• You understand what how DTS work.

• You understand JSON formatting.


6.2 Introduction

An Alarm object describes where and how PA is going to send a notification once it has been properly triggered.When an Event passes a Filter, it is passed on to the Alarms to trigger notifications. Each Alarm represents settingsfor exactly a notification will be sent: which service, what text, what images, and more.

25

https://www.w3schools.com/js/js_json_intro.asp


Note: By default, PA will trigger every Alarm when an Event passes a Filter. You can override this behavior by usingthe advanced Rules feature.

There are several different types of Alarms, each representing a different type of service:

• discord

• facebook-pages

• pushbullet

• slack

• telegram

• twilio

• twitter

Note: It is valid to have multiple Alarms with the same type - a different Alarm could represent a different channelor a specialized message instead of just a different service.

6.3 Creating an Alarm

Each Alarm is containing several key-value a named JSON Object containing several key-value pairs called alarmparameters. Some parameters are required for each alarm, and some are optional parameters. In the case of optionalparameters, default values are generally provided when they aren’t specified. For example, a basic Discord alarm lookslike this:

"my-discord-alarm":{"active":true,"type":"discord","webhook_url":"YOUR_WEBHOOK_URL"

}

The available parameters are different for every type of Alarm - make sure to check the appropriate wiki page to ensureyou are using the correct ones.

6.4 Customizing Alerts

It is possible to customize the parameters an Alarm uses for different types of Events. For example, you may wantto send all “monsters” to one channel and all “raids” to another. In this case, alert level parameters can be used.These parameters override the alarm level parameters when used. Here is an example that uses alarm using alert levelparameters:

"my-discord-alarm":{"active":true,"type":"discord","webhook_url":"DEFAULT_CHANNEL_URL","monsters":{

"webhook_url":"MONSTER_CHANNEL_URL"},

26 Chapter 6. Alarms


"raids":{"webhook_url":"RAIDS_CHANNEL_URL"

}}

In the above example, any alert level parameters not set will default to the alarm level parameters - this means “stops”,“gyms”, and “eggs” will all be diverted to the channel at "DEFAULT_CHANNEL_URL".

Additionally, are also several alert level parameters that can’t be set at the alarm level. For example, “body” can onlybe set at the alert level in Discord:

"my-discord-alarm":{"active":true,"type":"discord","webhook_url":"DEFAULT_CHANNEL_URL","monsters":{

"webhook_url":"MONSTER_CHANNEL_URL","body":"This is a monster event!"

},"raids":{

"webhook_url":"RAIDS_CHANNEL_URL","body":"This is a raid event!"

}}

Finally, you can use DTS to customize most parameters based on the event. This can be used for a variety of reasons:specializing the message, customizing the channel, or even inserting your own images. Check out DTS for informationon DTS.

6.5 Alarms File

An alarms file (sometimes referred to as an ‘alarms.json’) is a file containing then Alarms that PA uses. By default, PAloads from the alarms.json located in the base folder of the project. See the Server Settings page for instructionson specifying the file by a different name. This file must contain a single JSON object to load successfully:

{

}

Each Alarm will be listed inside this JSON object. It will end up looking something like this:

{"my-first-alarm":{"active":true,"type":"discord","webhook_url":"YOUR_WEBHOOK_URL"

},"my-second-alarm":{"active":true,"type":"slack","api_key":"YOUR_API_KEY","channel":"general"

},"my-third-alarm":{"active":true,

6.5. Alarms File 27


"type":"discord","webhook_url":"YOUR_WEBHOOK_URL"

}}

28 Chapter 6. Alarms

CHAPTER 7

Managers

7.1 Overview

This guide will walk you through configuring server settings for PokeAlarm.

• Prerequisites

• Introduction

• Multiple Managers

• Additional Options

– Manager Names

– Geofences

– Timezones

7.2 Prerequisites


1. You have correctly installed PokeAlarm.


7.3 Introduction

In PokeAlarm, a Manager is a grouping of different settings. Managers allow you to configure multiple combinationsof filters, alarms, geofences, and other settings behind single webserver.

29



Webhooks are received by the PokeAlarm server, which then passes a copy to the manager. Each Manager determines(independently)if the alert passes one of the set filters (and geofence if enabled). If it does, the Manager sends the alertto the alarm defined in the Alarms file.

PokeAlarm runs each Manager in a separate process, allowing each Manager to operate in parallel and taking advantageof multiple cores.

7.4 Multiple Managers

Managers can be configured using either the command line or the configuration file. In order to run multiple managers,you must first set manager_count equal to the number of mangers you want to run. Managers use the argumentsof a type in order. If only one argument (of a type) is provided, this argument will be applied to all Managers. Forexample, the following command:

python start_pokealarm.py -m 3 -f common.json -f rares.json -f uncommon.json -a→˓alarms.json

This command sets up three managers. The first uses the filter file common.json, the second uses the rares.json, and the third uses the uncommon.json. However, all three managers will use the same alarms.json fileto set up their alarms.

This same configuration can be accomplished via the following in the configuration file:

manager_count: 3filters: [ common.json, rares.json, uncommon.json ]alarms: alarms.json

30 Chapter 7. Managers


7.5 Additional Options

7.5.1 Manager Names

Manager names are currently useful for logging purposes only. Changing the name will change the name of the loggerused in PA’s output. Manager names are configured the same as other parameters:

manager_name: [ manager_0, manager_1, manager_2 ]

If no manager name is defined, PA will name that manager automatically based on it’s order.

7.5.2 Geofences

Geofences are a useful tool and can be bound in a mixture of combinations to different managers. Configuring geofencefiles is similar to other options:

geofence: [ city1.json, none, city2.json ]

As you can see, you can mix managers with geofences and without by using none for any managers that you don’twant a geofence file loaded for.

You can find more information about Geofences on the Geofences wiki page.

7.5.3 Timezones

By default PA will use your server time for notifications. If you wish to change this timezone, you can use either the-tz or --timezone to set a timezone. A full list of compatible timezones can be found here.

7.5. Additional Options 31

geofences.html

https://en.wikipedia.org/wiki/List_of_tz_database_time_zones


32 Chapter 7. Managers

CHAPTER 8

Geofences

8.1 Overview

• Introduction

• Instructions

• Example: 4 point geofence - Central Park, New York, NY

• Example: 21 point geofence - Coronado, San Diego, CA

• Example: Multiple Geofences in the same geofences.txt file

• Geofence Generator: Draw Your Own Geofence

8.2 Introduction

Geofencing will restrict PokeAlarm alerts to a defined geographical area. The area is defined by a list of at least 2sets of latitude and longitude coordinates. You may provide as many coordinates as you’d like to define your area ofinterest, provided that these sets are in the order that defines your polygon.

Note: PokeAlarm will first check pokemon alert distance, then will check to see if the pokemon is located within yourgeofence. See Monster Filters on how to limit alerts based on distance.

8.3 Instructions

Create a text file with with a series of at least 3 latitude,longitude sets and place this in the same folder asstart_pokealarm.py. (A minimum of 3 points are required as of PokeAlarm v3.1.)

To define a rectangular geofence: Use 2 lat/lon sets, with the first set defining the top left of the rectangle, and thesecond defining the bottom right of the rectangle.

33

filters/monster-filters.html


To define a polygonal geofence: Provide as many lat/lon sets as it takes to define your polygon. Make sure that youprovide the points in order to describe the polygon.

Execute start_pokealarm.py with the -gf or --geofences flag, along with the path to your geofence file,or add geofence:YOUR_GEOFENCE_FILE to config.ini.

8.4 Example: 4 point geofence - Central Park, New York, NY

The text file below defines the northwest, southwest, southeast and northeast corners of central park. The heading inbrackets [NAME_OF_GEOFENCE] is mandatory, and PokeAlarm will fail if not included in the geofence file.

file: central-park-geofence.txt

[Central Park, NY]40.801206,-73.95852040.767827,-73.98283540.763798,-73.97280840.797343,-73.948385

configuration/images/geofence_central_park_640x640.png

In the image above, each numbered marker 1-4 represents the lat,lon coordinates found in central-park-geofence.txt,respectively.

To run PokeAlarm with geofencing enabled, execute:

python start_pokealarm.py -gf central-park-geofence.txt

or

python start_pokealarm.py --geofences central-park-geofence.txt

or you can include geofences:central-park-geofence.txt in your config.ini file.

If successful, you should receive a confirmation in your log:

2018-01-20 18:05:26 [ Geofence][ INFO] Geofence Central Park, NY added!

For our Central Park example, all 4 points encompass the entire park. The visual of the geofenced area is below. Thered marker in the image denotes a selected location, here, The Pond, Central Park, NY.

configuration/images/geofence_central_park_bounded.png

PokeAlarm will then notify you of pokemon within the shaded area.

Note: Remember to configure the filters to use this area of the geofence or will not apply to alerts. Example:

34 Chapter 8. Geofences


"filter_tiny_central_park":{"geofences":["Central Park, NY"]

}

8.5 Example: 21 point geofence - Coronado Island, San Diego, CA

You may add as many lat,lon points to define you polygon, provided that the points in your geofence file are in orderof defining said polygon. Below is an example of a 21 point polygon encompassing an area.

file: geofence_coronado.txt

[Coronado, CA]32.7134997863394,-117.1889305114746132.71508853568461,-117.1933078765869132.715305181130056,-117.2054100036621132.71046664083005,-117.218971252441432.69977759183938,-117.2276401519775432.6864144801245,-117.2283267974853532.679985027301136,-117.2241210937532.6859810484179,-117.2110748291015632.685619853722,-117.1939086914062532.67239912263756,-117.172107696533232.675794797699766,-117.167730331420932.68020175796835,-117.1749401092529332.68164661564297,-117.1727943420410232.677600955252075,-117.1669578552246132.68540313620318,-117.1615505218505932.692626770053714,-117.1619796752929732.698549713686894,-117.1654129028320332.70346112493775,-117.1789741516113332.704400040429604,-117.1800899505615232.70700006253934,-117.1897888183593832.711983226476136,-117.18704223632812

And remember to set filters to apply geofence like this example:

"filter_coronado":{"geofences":["Coronado, CA"]

}

Below is the resulting geofence:

configuration/images/geofence_coronado.png

8.6 Example: Multiple Geofences in the same geofences.txt file

You are permitted to add more than one geofence area in a single geofences.txt file. Add a bracketed headerbefore each set of coordinates. For example:

8.5. Example: 21 point geofence - Coronado Island, San Diego, CA 35


[Central Park, NY]40.801206,-73.95852040.767827,-73.98283540.763798,-73.97280840.797343,-73.948385[Coronado, CA]32.7134997863394,-117.1889305114746132.71508853568461,-117.1933078765869132.715305181130056,-117.2054100036621132.71046664083005,-117.218971252441432.69977759183938,-117.2276401519775432.6864144801245,-117.2283267974853532.679985027301136,-117.2241210937532.6859810484179,-117.2110748291015632.685619853722,-117.1939086914062532.67239912263756,-117.172107696533232.675794797699766,-117.167730331420932.68020175796835,-117.1749401092529332.68164661564297,-117.1727943420410232.677600955252075,-117.1669578552246132.68540313620318,-117.1615505218505932.692626770053714,-117.1619796752929732.698549713686894,-117.1654129028320332.70346112493775,-117.1789741516113332.704400040429604,-117.1800899505615232.70700006253934,-117.1897888183593832.711983226476136,-117.18704223632812

In this example, you can configure an individual alarm to only check one geofence from your geofence.txt. This filterwill only check the geofence named Central Park, NY:

"filter_central_park": {"geofences":["Central Park, NY"]

}

Or check the 2 geofence zones with:

"filter_central_park_coronado":{"geofences":["Central Park, NY","Coronado, CA"]

}

Additionally, you can use "geofences":["all"] as a shortcut for checking all geofences in a geofence file.Example:

"filter_all_geofences":{"geofences":["all"]

}

8.7 Geofence Generator: Draw Your Own Geofence

These are handy web tool to create and visualize your desired geofence.

Jason’s A Better Fence Editor - Recommended by PokeAlarm team

To use it:


http://geo.jasparke.net/


1. Create a fence name, color and click Create. (If you have a fence already paste it into the Coordinate Set)

2. Click for each geofence point until you have made made a full circle.

3. Click exp (Export) from there you can copy, paste or click Download with or without fence name tag.

4. To better manage all your geofences in one file you can save a json file that saves everything as you have it.

5. Click load to load previously generated geofences and continue.

JennerPalacios’s Codepen Geofence Generator

To use it:

1. Type your desired location.

2. Click for each geofence point that you would like to add to the coordinate list.

3. Complete your geofence area by clicking the original point, the last point, or double clicking.

4. Click Show Coordinates, Assign a name - ie: [Seattle] and then click Copy to Clipboard

8.7. Geofence Generator: Draw Your Own Geofence 37

https://codepen.io/jennerpalacios/full/mWWVeJ



CHAPTER 9

Rules

9.1 Overview

• Prerequisites

• Default Rule

• Creating Custom Rules

• Examples

9.2 Prerequisites

This page assumes:

1. You have a working PA installations.

2. You read and understood the Filters page.

3. You read and understood the Alarms page

4. You have an understanding on what a Manager is.

9.3 Default Rule

Normally when PA is processing an Event, it goes through the Filters in the order listed. Once it finds a match, ittriggers all of the Alarms attached to that manager.

Imagine you have some filters( "100-iv", "90-iv", "in_geofence", "rare-mon") and some alarms("discord-rare", "discord-perfect", "telegram-all"). First, PA will check the "100-iv" filter.If that doesn’t match, it will check the "90-iv" filter. Once it finds a match, it will then send to all of the alarms.

This behavior is known as the default rule - all filters to all alarms. If you don’t specify any rules for a section,this is the default behavior. The default rule for the above scenario could be described as the following:

39

managers.html


"default":{"filters":["100-iv","90-iv","in_geofence","rare-mon"],"alarms":["discord-rare","discord-perfect","telegram-all"]

}

Each rule has a name, and 2 required sections: "filters" and "alarms". Each section is simply a list of namescorresponding to the appropriate section. Sections are required, and you will be unable to make a rule to a filter oralarm that doesn’t exist.

9.4 Creating Custom Rules

You can specify your own rules to override the defaults. This can be done by setting --rules rules.json orrules: rules.json in the config.ini.

Each rule file can have 5 sections, one for each type of event. An empty rules file would look like this, and wouldresults in the default rules:

{"monsters":{},"stops":{},"gyms":{},"eggs":{},"raids":{}

}

Adding rules will override the default rules and create new behavior. If multiple rules are specified, they will bechecked independently and possible trigger a notification for each one. For example, the following would send"rare-mon" events to the telegram alarm, and all other events to the discord alarm.

{"monsters":{

"discord-rule":{"filters":["100-iv","90-iv","in_geofence"],"alarms":["discord-rare","discord-perfect"]

},"telegram-rule":{

"filters":["rare-mon"],"alarms":["telegram-all"]

}}

}

9.5 Examples

Coming soon!

40 Chapter 9. Rules

CHAPTER 10

Getting Started

10.1 Overview

This guide contains an overview to the different parts of configuring and customizing PokeAlarm to fit your needs.

• Prerequisites

• Goals

• Setting up an Alarm

• Setting up Filters

– Monster Filters

– Gym Filters

– Raid Filters

• Customizing Alert Text

• Advanced: Managers

• Advanced: Missing Info

• Advanced: Custom DTS

10.2 Prerequisites


1. You have correctly installed PokeAlarm, including setting up a source for your information.


41



10.3 Goals

This guide will walk you through setting up and customizing PokeAlarm to fit your needs. Specifically, we will gothrough setting up a PA server to do the following:

1. Use Discord

2. Alert when Charmander family monsters are found.

3. Customize alerts for the other two starters based on IVs

4. Alert when an Instinct Gym falls (clearly the superior team)

5. Alert when a Raid appears for Legendary Birds

6. Customize the Monster and Raid Alerts text with DTS

10.4 Setting up an Alarm

In PokeAlarm, an ’Alarm’ is a block in the alarms.json section that represents how you want to receive an alert.For our example, we will use Discord, but the steps are similar between types of Alarms.

To create a Discord Alarm, you should be familiar with these two pages:

1. Learn how to configure your alarms file with the Alarms wiki page.

2. Learn how to set up a Discord webhook url with the Discord wiki page.

Once we have our webhook url set up, we can edit the default discord alarm in the alarms.json file:

{"discord_alarm":{"active":true,"type":"discord","webhook_url":"https://discordapp.com/api/webhooks/1234567890"

}}

Note: for brevity only the discord section is shown

Try starting PokeAlarm - If you have configured your Alarm correctly, you should see a start up message posted inyour discord channel!

10.5 Setting up Filters

Filters are how PokeAlarm decides which Events get sent to sent to the Alarms to trigger notifications. To get all thedetails of Filters, read the Filters wiki page.

In PokeAlarm, there are five different types of events. In a filter’s config file, there is a section for setting filters in eachtype of event: monsters, stops, gyms, eggs, and raids.

PokeAlarm will compare each Event to each Filter, one by one. If an Event passes a Filter, it will be passed onto theAlarms to trigger a notification. Note: Only one filter can be trigger at a time.

42 Chapter 10. Getting Started



10.5.1 Monster Filters

First, we want to decide which monsters we want notifications on. I want to create an army of Charizards, so I’mgoing to need a lot of candy! I’m going to create a new filter named best_monsters and set it to accept only theCharmander family:

{"monsters":{

"enabled":true,"defaults":{},"filters":{

"best_monsters":{"monsters":["Charmander","Charmeleon","Charizard"]

}}

}}

Note: for brevity only part of the filters file is shown

Bam! That was easy! So easy, maybe we should get a few of the other starters as well. However let’s only get the otherstarters with high IVs (only the best IV’s can compete with a monster as good as Charmander!). Let’s add anotherfilter, but for IV’s above 90%.

{"monsters":{



},"okay_monsters":{"monsters":["Bulbasaur", 2, 3, 7, 8, 9],"min_iv": 90

}}

}}

Wew! I got tired of typing out the names, so I just substituted in their ID numbers instead (and PA is A-OKAYwith that). I could have also added in "max_iv": 100 as well, but it is always better to leave out unnecessaryparameters (not only is it faster, but it can help avoid unintended things from happening!).

10.5.2 Gym Filters

Next, I want need to know when any of my team’s gyms switch to another team (so I can go put them back up). I’llstart with setting "old_teams":["Instinct"].

{"gyms":{

"enabled":true,"ignore_neutral":true,"defaults":{},

10.5. Setting up Filters 43


"filters":{"clearly_the_best_team":{

"old_teams":["Instinct"]}

}},

}


This filter will allow in any gym that switches from Instinct to any other team. Additionally, we don’t want to knowabout when it switches to neutral, so we set "ignore_neutral":true. You can list multiple different filters inthe filters section of gyms, and PA will check them one by one.

10.5.3 Raid Filters

Raid filters work very similar to Monster Filters. You can set up alerts for any monster - not just the ones in theexample. Here is the Raid section of a filters file set up for legendary birds:

{"raids":{


"legendary-birds":{"monsters":[144, 145, 146, 249, 250]

}}

}}


10.6 Customizing Alert Text

PokeAlarm allows you to customize the Alerts that it sends out. We want to customize our Raid Alerts to show a moreappropriate message. To add custom text to a Discord Alarm, you should be familiar with three pages:

1. Learn how to configure your alarms file with the Alarms wiki page.

2. Learn what fields Discord has to change with Discord wiki page.

3. Learn what DTS options are available to you with the Events wiki page.

{"discord_alarm":{"active":true,"type":"discord","webhook_url":"https://discordapp.com/api/webhooks/1234567890","raids":{"title":"The Legendary Bird <mon_name> has appeared! It has <cp> CP!"

}}

}




Note: for brevity only part of the alarms file is shown

Dynamic Text Substitutions substitute text dynamically (shocking!). This means that certain words will automaticallychange when surrounded by < and > If a Moltres were to appear, it will show up with the message set to "TheLegendary Bird Moltres has appeared! It has 9999 CP!".

Note: If PA doesn’t have that information, it will show either ’?’, ’unkn’, or ’unknown’ instead. If you get these inyour alert, you will need to tweak your scanners to send the correct information.

You can customize any notification by adding the proper alert settings to your alarms file. If we wanted to customizepokemon alerts, we use the following:

{"discord_alarm":{"active":true,"type":"discord","webhook_url":"https://discordapp.com/api/webhooks/1234567890","monsters":{

"title":"The starter <mon_name> jumped out of the bushes!","body":"It has an IV of <iv>%!"

},"raids":{"title":"The Legendary Bird <mon_name> has appeared! It has <cp> CP!"

}}

}

Note: for brevity only part of the alarms file is shown

You can customize more than just the title - each service has many different options. Check out the wiki page for yourspecific service for a full list.

10.7 Advanced: Managers

Now that we’ve customized our message, we have a little problem. If we add on additional filters (say for Dratini),they will have use the message "The starter <mon_name> jumped out of the bushes!" But Dratiniisn’t a starter pokemon! Let’s add a second manager that allow us to customize even more.

You can find out more about Manager’s and their settings on the Managers wiki page.

First, lets make two different filter files. We will call the following filter file starters_filter.json:

{"monsters":{



},"okay_monsters":{"monsters":["Bulbasaur", 2, 3, 7, 8, 9],"min_iv": 90

}}

}}

10.7. Advanced: Managers 45

../configuration/managers.html



Next, we can make a second filter file for Dratini. We will call this one dratini_filters.json:

{"monsters":{


"filter-name":{"monsters":[147, 148, 149]

}}

}}


We want the alerts from starter_filters.json to be different than the ones from dragon_filters.json.So we need two different alarms files. Here is what our starter_alarms.json file looks like:


"title":"The starter <mon_name> jumped out of the bushes!","body":"It has an IV of <iv>%!"

}}

}

As you can see, it is the same one as before. Here is what the dratini_alarms.json file looks like:


"title":"The high IV dragon <mon_name> appears with a roar!","body":"It has an IV of <iv>%!"

}}

}

Now we have two different filters and two different alarm files. Now we just need to set up the manager and link thefilter to the alarm we want to use. When we start PokeAlarm, we can use the following:

python start_pokealarm.py -m 2 -f starter_filters.json -a starter_alarms.json -f→˓dratini_filters.json -a dragon_filters.json

The -m flag tells PA that we want 2 managers. The first manager uses the first file specified by -f and the first filespecified by -a. The second manager uses the second filter and second alarm file.

Managers run in separate processes, so they run concurrently and scale well with the number of cores on your machine.However running too many managers can be inefficient and waste your computers resources.



With great power comes great responsibility.

- Uncle Ben (about Managers, probably)

Managers are a great tool that allow you to mix and match almost every setting to any filter or alarm settings. For fulldetails on the power of Managers, don’t forget to check out Managers wiki page.

10.8 Advanced: Missing Info

Sometimes, Event’s are missing information needed to correctly filter them. In these instances, you can use the"is_missing_info" parameter to require a filter to reject or allow Events with missing information. You canread more about the feature on the Filters wiki page.

I really only want monsters like Bulbasaur and Squirtle to trigger notifications if they have the right ivs thatI am looking for. If my scanner goofs up and doesn’t get the ivs, I don’t want to be bothered. Setting"is_missing_info":false tells that filter to reject if any necessary information is missing.

{"monsters":{



},"okay_monsters":{"monsters":["Bulbasaur", 2, 3, 7, 8, 9],"min_iv": 90, "is_missing_info":false

}}

}}

10.9 Advanced: Custom DTS

Custom DTS is a feature that let’s you define filter-specific DTS that ONLY work when that filter passes. You canread more about it on the Filters wiki page.

I can use it to change certain text depending on which filters pass.

{"monsters":{


"best_monsters":{"monsters":["Charmander","Charmeleon","Charizard"],"custom_dts":{"is_fav": "IS"}

},"okay_monsters":{"monsters":["Bulbasaur", 2, 3, 7, 8, 9],"min_iv": 90, "is_missing_info":false,"custom_dts":{"is_fav": "IS NOT"}

10.8. Advanced: Missing Info 47

../configuration/managers.html


}}

}}

If I used the following phrase in an alarms.json:

"<mon_name> <is_fav> my FAVORITE!"

could look like this if it passed the first filter:

Charmander IS my FAVORITE!

or like this if it passed the second filter:

Squirtle IS NOT my FAVORITE!

This feature, could be used for a variety of things like tagging special roles or even changing channels based on thefilter selected.

For example, say I changed my mind and DO want notifications from the other starters, but I want them to go into adifferent channel. First, I would modify my filters.json to add in a DTS:

{"monsters":{


"best_monsters":{"monsters":["Charmander","Charmeleon","Charizard"],"custom_dts":{"channel_api_key": "11111"}

},"okay_monsters":{"monsters":["Bulbasaur", 2, 3, 7, 8, 9],"min_iv": 90, "is_missing_info":false,"custom_dts":{"channel_api_key":"11111"}

},"okay_monsters_no_iv":{"monsters":["Bulbasaur", 2, 3, 7, 8, 9],"min_iv": 90, "is_missing_info":true,"custom_dts":{"channel_api_key":"22222"}

}}

}}

Next, I can change my alarms.json:

{"discord_alarm":{"active":true,"type":"discord","webhook_url":"https://discordapp.com/api/webhooks/<channel_api_key>"

}}

Now, if it passes "best_monsters" or "okay_monsters" it’ll send to the channel at https://discordapp.com/api/webhooks/11111. If it passes "okay_monsters_no_iv" then it will be sent to the channel at https://discordapp.com/api/webhooks/22222.


CHAPTER 11

JSON Formatting Help

TODO

49


50 Chapter 11. JSON Formatting Help

CHAPTER 12

3.5 -> 3.6 Alarm Upgrade Tool

TODO

51


52 Chapter 12. 3.5 -> 3.6 Alarm Upgrade Tool

CHAPTER 13

Bug Reports / Feedback

TODO

53


54 Chapter 13. Bug Reports / Feedback

CHAPTER 14

Webhook Standard

14.1 Overview

• Pokemon

• Pokestops

• Gyms

– Gym-details Example

• Egg example

• Raid example

14.2 Pokemon

Pokemon standard now includes moveset and IVs as of commit oc1b4.

14.2.1 Example:

{"type": "pokemon","message": {

"encounter_id": "0","spawnpoint_id": "0","pokemon_id": 201,"pokemon_level": 30,"player_level": 31,"latitude": 37.7876146,"longitude": -122.390624,"disappear_time": 1506897031,"last_modified_time": 1475033386661,

55

https://github.com/RocketMap/PokeAlarm/commit/0c1b4cce80e0ceb3cc6dbb2d802204af4dd3ce60


"time_until_hidden_ms": 5000,"seconds_until_despawn": 1754,"spawn_start": 2153,"spawn_end": 3264,"verified": false,"cp_multiplier": 0.7317000031471252,"form": 15,"cp": 768,"individual_attack": 10,"individual_defense": 1,"individual_stamina": 9,"move_1": 281,"move_2": 133,"height": 0.5694651007652283,"weight": 5.733094215393066,"gender": 3

}}

14.3 Pokestops

14.3.1 Example:

{"type": "pokestop","message": {

"pokestop_id": 0,"enabled": "True","latitude": 37.7876146,"longitude": -122.390624,"last_modified_time": 1572241600,"lure_expiration": 1572241600,"active_fort_modifier": 0

}}

14.4 Gyms

14.4.1 Example:

{"type": "gyms","message": {

"raid_active_until": 0,"gym_id": 0,"team_id": 0,"guard_pokemon_id": 0,"slots_available": 0,"guard_pokemon_id": 99,"lowest_pokemon_motivation": 0.8795773983001709,"total_cp": 11099,

56 Chapter 14. Webhook Standard


"occupied_since": 1506886787,"enabled": "True","latitude": 37.7876146,"longitude": -122.390624,"last_modified": 1572241600

}}

14.4.2 Gym-details example:

{"type": "gym_details","message": {

"id": "OWNmOTFmMmM0YTY3NGQwYjg0Y2I1N2JlZjU4OWRkMTYuMTY=","url": "http://lh3.ggpht.com/yBqXtFfq3nOlZmLc7DbgSIcXcyfvsWfY3VQs_

→˓gBziPwjUx7xOfgvucz6uxP_Ri-ianoWFt5mgJ7_zpsa7VNK","name": "Graduate School of Public Health Sculpture","description": "Sculpture on the exterior of the Graduate School of Public

→˓Health building.","team": 1,"latitude": 37.7876146,"longitude": -122.390624,"pokemon": [{

"num_upgrades": 0,"move_1": 234,"move_2": 99,"additional_cp_multiplier": 0,"iv_defense": 11,"weight": 14.138585090637207,"pokemon_id": 63,"stamina_max": 46,"cp_multiplier": 0.39956727623939514,"height": 0.7160492539405823,"stamina": 46,"pokemon_uid": 9278614152997308833,"deployment_time": 1506894280,"iv_attack": 12,"trainer_name": "SportyGator","trainer_level": 18,"cp": 138,"iv_stamina": 8,"cp_decayed": 125

}, {"num_upgrades": 0,"move_1": 234,"move_2": 87,"additional_cp_multiplier": 0,"iv_defense": 12,"weight": 3.51259708404541,"pokemon_id": 36,"stamina_max": 250,"cp_multiplier": 0.6121572852134705,"height": 1.4966495037078857,"stamina": 250,"pokemon_uid": 6103380929145641793,"deployment_time": 1506894733,

14.4. Gyms 57


"iv_attack": 5,"trainer_name": "Meckelangelo","trainer_level": 22,"cp": 1353,"iv_stamina": 15,"cp_decayed": 1024

}, {"num_upgrades": 9,"move_1": 224,"move_2": 32,"additional_cp_multiplier": 0.06381925195455551,"iv_defense": 13,"weight": 60.0,"pokemon_id": 31,"stamina_max": 252,"cp_multiplier": 0.5974000096321106,"height": 1.0611374378204346,"stamina": 252,"pokemon_uid": 3580711458547635980,"deployment_time": 1506894763,"iv_attack": 10,"trainer_name": "Plaidflamingo","trainer_level": 23,"cp": 1670,"iv_stamina": 11,"cp_decayed": 1435

}]}

}

14.5 Egg example

Take note that the type for egg is raid because it is collected from the same webhook event from RocketMap as raidsare.

{"type": "raid","message": {

"gym_id": "gym_id","start": 1499244052,"end": 1499246052,"level": 5,"latitude": 37.7876146,"longitude": -122.390624

}}

14.6 Raid example

{"type": "raid","message": {



"gym_id": "gym_id","pokemon_id": 200,"cp": 12345,"move_1": 123,"move_2": 123,"start": 1499244052,"end": 1499246052,"level": 5,"latitude": 37.7876146,"longitude": -122.390624

}}

14.6. Raid example 59



CHAPTER 15

Webhook Tester

TODO

61


62 Chapter 15. Webhook Tester

CHAPTER 16

Patch Notes

16.1 Patch History

• Patch 3.6

• Patch 3.5

• Patch 3.4

• Patch 3.3

• Patch 3.2

• Patch 3.1

16.2 Patch 3.6

This patch contains several breaking changes - make sure to read carefully, back up your current configuration, andhave some free time before attempting to upgrade.

16.2.1 Rules (Optional)

New Feature - The "Rules" feature will allow users to create rules that dictate which filters trigger which alarms.Rules are loaded via a file containing a json object, which has 5 sections similar to the Filters file. Each section isa key-value pair of "rule names" to "rules". Each rule can be described as a json object containing just two fields:"filters" and "alarms". Each field is an array of strings corresponding to the name of a filter or alarm from a manager.Rules cannot be loaded if they do not match an existing filter or alarm.

Rules are evaluated by checking the listed filters one by one (in order), until a match is found. Once a match is found,PA will them notify each alarm listed in the Rule. Every rule is always evaluated every time.

63


Rules are an optional configuration setting and if no rules are set then PA will check every filter in the order that theyare listed in the filters file and will target every alarm.

Rules can be loaded via a rules file with -r and --rules via commandline or rules: rules.json in con-fig.ini.

Each rules file must be configured key-value objects and contain at least one or more of following rules sections:

• monsters

• stops

• gyms

• eggs

• raids

The inner section of each rule must be configured as a key-value object where the key is the rule’s name, and the valueis the rule’s setting.

Each rule can be described as follows:

"example_rule" : {"filters": [ "filter1", "filter2" ],"alarms": [ "alarm1", "alarm2" ]

}

16.2.2 Alarms

Breaking Changes - To fully take advantage of the "Rules" feature, the "Alarms" feature was changed to require a key-value json object instead of a list. Alarms should now be a list of "name" -> "alarm settings". The alarms.json.examplehas been updated to match this.

Changed Alert Sections

The Alert sections of alarms has been updated to match the event names:

• pokemon -> monsters

• pokestop -> stops

• gym -> gyms

• egg -> eggs

• raid -> raids

Alerts Converter

A new tool has been added to tools/convert_alarms_file.py, this tool is designed to convert Alerts filesfrom 3.5 and prior to the 3.6 alert format.

Usage:

python convert_alarms_file.py /path/to/alarms.json

64 Chapter 16. Patch Notes


Telegram Changes

Breaking Changes - Telegram alarms have been reworked to resolve multiple issues and address Telegram APIchanges.

• Content Changes - Telegram now uses markdown instead of html to reduce conflicts caused by using invalidDTS fields. Existing alerts will have to be reconfigured to make this change.

– The venue field does not support markdown or html coding

– title and body have been merged into message to better represent how the Telegram API actuallytreats messages. The old behavior can be mimiced by using the following example content: *TITLEGOES HERE*\n BODY GOES HERE

• Field Changes - The following fields have been changed:

– bot_token: Can now be set at an Alert level. DTS compatible.

– chat_id: Now DTS compatible.

– stickers -> sticker: Set to "true" for sticker with message, set to "false" for no sticker.

– sticker_notify: Whether or not sticker messages causes a notification.

– sticker_url: Url to be used for the sticker. Must be .webp file.

– location -> map: true for map after message, false for no map.

– map_notify: Whether or not map messages causes a notification.

– venue: Sends the map and message in a single condensed format.

– venue_notify: Whether or not venue messages causes a notification.

– max_retries: Max attempts to send for each message. (Telegram no longer uses the command lineequivalent)

16.2.3 Filters

• Listed filters now evaluate in the order listed in the file.

• The "geofences" : [ "all" ] shortcut now evaluates in the order that the geofences are listed in thegeofence file.

• gym_name_contains is now case-insensitive.

Time Based Filtering

Filters now support filtering based on event timing. This allows for greater control over event alerts than what waspreviously supported via the timelimit configuration option.

• New Filters

– min_time_left - The minimum amount of time in seconds until the event

* max_time_left - The maximum amount of time in seconds until the event

• Filter Events

– Monsters - Filters based on time until monster despawns

* Stops - Filters based on time until the lure ends

* Raids - Filters based on time until the raid ends

16.2. Patch 3.6 65


* Eggs - Filters based on time until the egg hatches

16.2.4 Locale

• Added multi-lingual support for the Size DTS & Filter setting.

16.2.5 Dynamic Text Substitutions

• Monsters & Raids

– size - Changed to support locales

– weather - Outputs the current weather conditions in the alert

* weather_id - Outputs the current weather condition id

* weather_or_empty - Same as weather or an empty value

* weather_emoji - Outputs a unicode emoji for the current weather

– boosted_weather - Outputs the weather conditions if boosted

* boosted_weather_id - Outputs the boosted weather condition id

* boosted_weather_or_empty - boosted_weather or an empty value

* boosted_weather_emoji - Outputs an emoji for the boosted weather

* boosted_or_empty - Outputs the word boosted if Raid/Mon is boosted

* type1 - Outputs the name of the Monster’s Primary Type or ?

* type1_or_empty - Same as type1 or an empty value

* type1_emoji - Outputs an emoji for the Monster’s Primary Type or Empty

* type2 - Outputs the name of the Monster’s Secondary Type or ?

* type2_or_empty - Same as type2 or an empty value

* type2_emoji - Outputs an emoji for the Monster’s Primary Type or Empty

* types - Outputs the Monster’s Type formatted as "type1/type2"

* types_emoji - Outputs an emoji for the Monster’s Type(s) or Empty

• Eggs

– weather - Outputs the current weather conditions in the alert

* weather_id - Outputs the current weather condition id

* weather_or_empty - Same as weather or an empty value

* weather_emoji - Outputs an emoji for the current weather conditions

16.2.6 Server Settings

• Performance Fixes - Users should now see improved performance and less system resource usage overall.



16.2.7 Bug Fixes

• Twitter Alarms

– Maximum length has been extended to 280 characters to match Twitter standards and settings

* All URLs are now counted as 23 characters towards the overall character limit detection. URLs thatwould cause the tweet to exceed 280 characters will be dropped from the tweet.

* DTS is now evaluated before the length of the status update is calculated. This corrects issues withimproper Twitter Status Truncation

16.3 Patch 3.5

This patch contains several breaking changes - make sure to read carefully, back up your current configuration, andhave some free time before attempting to upgrade.

16.3.1 Filters

Breaking Changes - Filters have been completely reworked, with the design focused on reducing managers andoptimizing system resources. Several filter parameter’s have changed or been updated. For full instructions on the newsystem, please see the new Filters page in the wiki.

Some highlights include:

* Custom DTS - new feature to define filter specific DTS


• Added concurrency setting - Determines the maximum number of concurrent connections PA will accept.Lowering this may help lower-end systems improve the response time for their machines.

16.3.3 Alarms

• All

– Updated default image urls for icon_url and avatar_url. These default urls have built in cachebusting

• Discord

– webhook_url field is now DTS compatible

• Twilio

– Now supports using an array of numbers for the to field in Alert configurations.

16.3. Patch 3.5 67



• Pokemon

– enc_id changed to encounter_id

– level changed to mon_lvl

– pkmn changed to mon_name

– pkmn_id changed to mon_id

– pkmn_id_3 changed to mon_id_3

– form_id_3_or_empty replaced with form_id_3

– tiny_rat - Updated to use weight instead of size.

– big_karp - Updated to use weight instead of size.

• Pokestops

– id changed to stop_id

• Raids

– team_leader - Reports the name of the team leader of the team in control of the gym.

– pkmn changed to mon_name

– raid_level changed to raid_lvl

– time_left changed to raid_time_left

– 24h_time changed to 24h_raid_end

– gym_image_url changed to gym_image

• Eggs

– raid_level changed to egg_lvl

– begin_time_left changed to hatch_time_left

– time_left changed to raid_time_left

– begin_12h_time changed to 12h_hatch_time

– begin_24h_time changed to 24h_hatch_time


• Gyms


– slots_available - displays the number of open guard slots available in a gym

– guard_count - displays the number of guards assigned to a gym

16.3.5 Misc

• Added Gen3 Move information

• Updated Kyogre and Groudon stats

• Added Portuguese language translations - pt



16.4 Patch 3.4


• Implemented caching for managers with -ct or --cache_type. Cache is used to handling rememberingthings like pokemon history and gym names.

– (default) mem - data persists only in memory.

– file - data is saved and loaded from a file.

• PA now gracefully exits on ctrl+c, finishing items in queue and logging the status of managers.


• All

– lat_5 and lng_5 - Latitude and Longitude for the event, truncated to 5 decimal places.

– address_eu - same as <street> <street_num>.

• Pokemon

– form_or_empty - Reports the form name of the pokemon if known, or an empty string if unknown.

– pkmn_id_3 - pokemon id padded to 3 digits.

– form_id_or_emtpy - prints form_id padded to 3 digits if known, or and empty string if unknown.

• Raids

– form_or_empty - Reports the form name of the pokemon if known, or an empty string if unknown.

– team_name - Reports the current team for a Raid gym if known, or ’unknown’ if not.

– team_id - Reports the current team id for a Raid gym if known, or ’?’ if not.

– min_cp and max_cp - min and max potential cp for the raid boss if caught.

– pkmn_id_3 - pokemon id padded to 3 digits.

– form_id_or_emtpy - prints form_id padded to 3 digits if known, or and empty string if unknown.

16.4.3 Tools

• Webhook Tester

– Added webhook_tester.py for users to simulate sending events.

16.4. Patch 3.4 69


16.5 Patch 3.3

16.5.1 Dynamic Text Substitution

• Pokemon

– (Re) added 'form' DTS (and made it more robust).

Server Settings

• Reverse Location

– Location services have been completely reworked to be more reliable.

– Location results now retrieve results set in whatever language is set for that manager.

– Location results now cache in memory - lowering overall API usage.

16.6 Patch 3.2

16.6.1 Filters

• Pokemon

– Pokemon can now be filtered by their form_id (example": "form": [0, 1, 2]).

– Pokemon can now be filtered by their gender (example": "gender": ["male", "female").

– 'min_cp' and 'max_cp' are used to limit the CP of pokemon to alert.

• Egg

– "Egg" section is now added to the filters.json.

– 'enabled' allows incoming raid alerts to be toggled on or off.

– 'min_level' and 'max_level' are used to limit the levels of incoming raids to alert on.

• Raids

– "Raids" section is now added to the filters.json.

– 'enabled' allows raid alerts to be toggled on or off.

– 'default' allows setting default settings for filters, and has the same options as pokemon filters do.

– Filters for pokemon raids can be set similar to the "pokemon" section, with the "name": {} scheme.


• General

– Added 'applemaps' to most alerts for AppleMaps link for iOS users.

– Time DTS now switch to ##h##m format when longer than one hour.

• Pokemon



– Added support for the following substitutions: 'cp', 'form', 'form_id', 'level'.

– Added 'big_karp' that displays ’big’ on big magikarp and 'tiny_rat' that displays ’tiny’ on smallrattata.

• Egg

– "Egg" alerts have the following substitutions: 'type', 'id', 'raid_level', 'raid_end','raid_being', 'lat', 'lng', 'gym_name', 'gym_description', 'gym_url'.

• Raid

– "Raid" alerts have the following substitutions: 'type', 'id', 'pkmn_id','cp', 'quick_id', 'quick_damage', 'quick_dps', 'quick_duration','quick_energy', 'charge_id', 'charge_damage', 'charge_dps','charge_duration', 'charge_energy', 'raid_level', 'raid_end','raid_begin' 'lat', 'lng', 'gym_name', 'gym_description', 'gym_url'.

• Gyms

– Added the following Gym substitutions: 'name', 'description', 'url'.

– Added the following ’Gym Leader’ substitutions: 'old_team_id', 'new_team_leader','old_team_leader'.

16.6.3 Alarms

• Twitter

– Twitter now automatically truncates to 140 characters - it will preserve links if added to the end.

• Discord

– Discord usernames now automatically truncates usernames to 32 characters.

– Added 'avatar_url' to change the avatar of the post.

– Added content field that posts a message before the embed, allows for taging by user or roll.

– Added 'disable_embed' that disables the discord embeds when set to true.

16.7 Patch 3.1

16.7.1 Filters

• Multifilters - Each filter can now be one of the following:

– 'True' for all defaults, 'False' for entirely disabled.

– A single filter in a json object (Ex: { "min_iv":"0", "max_iv" : "0" ... }).

– Multiple filters inside an array: [{"min_iv":"0", "max_iv":"25" }, {"min_iv":"75","max_iv":"100"} ].

• Pokemon

– All default filter parameters are now encapsulated in a single filter under the label default.

– size requires an array of valid sizes from the following: ['tiny', 'small', 'normal','large', 'big'].

16.7. Patch 3.1 71


– move_1 and move_2 are now quick_move and charge_move.

– size, quick_move, charge_move, moveset filter parameters will accept any value when set tonull.

• Pokestops

– Now only two fields: enabled and filters.

– filters supports the Multifilter format with min_dist and max_dist fields.

• Gym

– Now only three fields enabled, ignore_neutral, and filters.

– filters supports multifilters with the following fields:

* from_team - Array of valid previous team names.

* to_team - Array of valid current team names.

* min_dist and max_dist working as before.


• <geofence> added - the name of the first geofence in which the notification is in.

• <size> now list either 'tiny', 'small', 'normal', 'large', or 'big'.

• Quick moves now use the following: <quick_move>, <quick_id>, <quick_damage>, <quick_dps>,<quick_duration>, <quick_energy>.

• Charges moves now use the following: <charge_move>, <charge_id>, <charge_damage>,<charge_dps>, <charge_duration>, <charge_energy>.

16.7.3 Alarms

• All Services

– startup_list is officially gone.

• Boxcar

– No longer supported.

• Discord

– api_key renamed to webhook_url.

– Will now retry if webhook was not received correctly.

– New optional alarm and alert level field: map.

* enabled - True of False to enabled/disabled map.

* Added other static map parameters.

• Slack

– channel parameter is now required at the Alarm level.

* Slack will no longer default to general if the correct channel cannot be found.

* Slack will still default to the Alarm level channel over the Alert level channel is not found (so everyonecan still use <pkmn>!).



• Pushover

– No longer supported.

16.7. Patch 3.1 73



CHAPTER 17

Object Caching

Table of Contents

• Prerequisites

• Introduction

• Caching Methods

– Memory Cache

– Binary File Cache

• Multiple Instances

• Clearing Cache

17.1 Prerequisites

This guide assumes:

1. You have a functional PokeAlarm installation

2. You have a basic understanding of how to manage binary files

3. You have read and understood the available Command Line Arguments in the Server Settings wiki

17.2 Introduction

PokeAlarm uses Cache objects to store information that is not present on runtime. The cached objects store informationsuch as gym-info and other dynamic objects sent into PokeAlarm via webhook. Cached data is used for internalcalculations as well as to provide details for Events in Alarms.

75


17.3 Caching Methods

There are currently two methods available for object caching:

Caching Method Descriptionmem Caches data to memory only, information is lost between sessionsfile Caches data to binary files located in the cache folder

Note: If no cache-type is selected, mem will be chosen as the default.

17.3.1 Memory Cache

When using the mem cache type, cached data is stored in memory only and is cleared whenever PA exits. This willcause all Events fields which require this data to display an unknown or null value until the data is received by PAthrough webhooks.

17.3.2 Binary File Cache

When using the file cache type, cached data is written to a binary file located in the cache/ directory. EachManagers has a unique binary cache file stored as cache/<manager_name>.cache. Cached data is backed upto this binary file once per minute and immediately before PA exits.

17.4 Multiple Instances

Using File caching with multiple instances can cause conflicts as cache files are stored under <manager_name>.cache. When using the file cache type and multiple instances, take caution and ensure that all managers areassigned an explicitly unique name.

17.5 Clearing Cache

• Memory Cache is cleared whenever PA exits for any reason.

• File Caches may be cleared by deleting the cache/<manager_name>.cache file that corresponds to themanager you wish to clear the cache for. (To clear all cached data, delete all files in the cache folder). PA willneed to be restarted once cache files are erased.

76 Chapter 17. Object Caching

CHAPTER 18

Docker

18.1 Overview

• Prerequisites

• Introduction

• Setup

– Cloning the repo

– Configuring the alarm

– Building the docker image

– Launching PokeAlarm

– Stopping PokeAlarm

• Integrating with RocketMap

– Docker network

– Using links

– RocketMap running without docker

• Updating alarms

• Running multiple alarm containers

18.2 Prerequisites

This guide assumes:

1. You have Docker installed and running on your machine

2. You have Git installed and running on your machine

77

https://docs.docker.com/

https://git-scm.com/downloads


3. You have read and understood the Alarms wiki

Please familiarize yourself with all of the above before proceeding.

18.3 Introduction

By leveraging Docker, we can run PokeAlarm instances without the need of installing Python, pip or other tools relatedto it.

This means that you don’t have to go through the hassle of managing python and its multiple versions if you don’t feelcomfortable doing it, or for any other reason.

18.4 Setup

18.4.1 Cloning the repo

The first thing that you need to do is to clone the PokeAlarm repository in the directory you’d like:

git clone https://github.com/PokeAlarm/PokeAlarm.git

18.4.2 Configuring the alarm

Now, enter the repository’s directory and copy the file called alarms.json.default to a file named alarms.json. Once that is done, open alarms.json and edit it to your liking. Refer to the alarm configuration documen-tation linked above as needed.

It’s also possible, but not required, to edit the configurations file. This will allow you to set default values to be usedfor most of the alarm’s configuration, reducing the number of arguments when launching the instance. To do so, makea copy of the config.ini.example file located inside the config dir and rename it to config.ini. Now, justuncomment the desired lines and provide the values.

18.4.3 Building the docker image

Once alarms.json is edited, we’ve got to build the docker image that we will use to launch our PokeAlarm container.To do so, execute the following command from the repository’s root directory:

docker build -t pokealarm .

This will create an image with the tag pokealarm, the dot indicates it should use the contents from the directory it wasexecuted.

18.4.4 Launching PokeAlarm

With the docker image created, we can launch a PokeAlarm container. To do so is as simple as executing:

docker run --name alarm -d pokealarm -k YOUR_GMAPS_API_KEY

This will launch a docker container named alarm using the image we just created and tagged pokealarm

78 Chapter 18. Docker

https://docs.docker.com/


18.4.5 Stopping PokeAlarm

Simply execute docker stop alarm and docker rm alarm. The removal of the container is a necessary stepbecause we want to reuse its name.

18.5 Integrating with RocketMap

We will cover 3 scenarios for integration with your RocketMap. For the first two scenarios, we will assume that givenyour interest in PokeAlarm with docker, you are already running RocketMap on docker containers. For the last, wewill assume you have it running locally with python.

18.5.1 Docker network

If you have followed the RocketMap documentation for docker, you probably have a docker network already setup.All you would need to do is to add the network’s name to you docker run command that was used before, like this:

docker run --name alarm --net=NETWORK_NAME -d pokealarm -k YOUR_GMAPS_API_KEY

Once that’s done, you are able to reach your PokeAlarm container from any other container in the same network, usingthe container’s name as host value. For example, you could add -wh 'http://alarm:4000' to your RocketMapinstances.

18.5.2 Using links

If you are not running a docker network what you need to do is to link your RocketMap container to your PokeAlarmcontainer. To do so, launch you PokeAlarm container as we’ve done before, but this time launch you RocketMapcontainer with the added flag --link alarm before the image’s name on your docker run command. With that linkdeclared, you can add -wh 'http://alarm:4000' to the end of the docker run command and it will be able tofind your PokeAlarm container.

18.5.3 RocketMap running without docker

If you are not running RocketMap on docker, what we need to do for it to be reachable is to bind a port on your hostto the container’s port. This is easily done by adding the -p docker flag to your docker run command:

docker run --name alarm -d -p 4000:4000 pokealarm -k YOUR_GMAPS_API_KEY

Once you execute that, you will be able to reach your PokeAlarm container on port 4000 by port 4000 on yourlocalhost. This means you could add -wh 'http://127.0.0.1:4000' to your ./runserver.py commandand it would be able to post to the webhook.

18.6 Updating alarms

If you want to update the alarms.json or config.ini files or wish to create any other alarm configuration file,you are free to do so at any time. However, you will need to rebuild your docker image afterwards, so that it can copythe new/edited files into the image.

18.5. Integrating with RocketMap 79

https://rocketmap.readthedocs.io/en/develop/advanced-install/docker.html


18.7 Running multiple alarm containers

All you have to do is to execute the appropriate (described above) docker run command multiple times, giving eachcontainer a new name. For example, this is how we could do that using the docker network approach described before:

docker run --name commons --net=NETWORK_NAME -d pokealarm -k YOUR_GMAPS_API_KEYdocker run --name rares --net=NETWORK_NAME -d pokealarm -k YOUR_GMAPS_API_KEY -c→˓rares.jsondocker run --name ultra --net=NETWORK_NAME -d pokealarm -k YOUR_GMAPS_API_KEY -c→˓ultra-rares.json

In the above block we are launching 3 containers of the pokealarm image in a docker network, all of which couldbe accessed by other containers in the network by their names.

• The first is named commons and using the default configuration alarms.json

• The second is named rares and uses the configuration file named rares.json

• The third is named ultra and used the configuration file named ultra-rares.json

If running RocketMap without docker, you would simply have to add different port bindings to each container, like:

docker run --name commons -p 4000:4000 -d pokealarm -k YOUR_GMAPS_API_KEYdocker run --name rares -p 4001:4000 -d pokealarm -k YOUR_GMAPS_API_KEY -c rares.jsondocker run --name ultra -p 4002:4000 -d pokealarm -k YOUR_GMAPS_API_KEY -c ultra-→˓rares.json

Meaning that the containers would be reachable on http://localhost:4000, http://localhost:4001and http://localhost:4002 respectively.

80 Chapter 18. Docker

CHAPTER 19

Location Services

Table of Contents

• Prerequisites

• Introduction

• Enabling the Various Google Maps APIs and Obtaining a Key

• Testing Your API Key

– Geocoding

– Distance Matrix

– Static Maps

• Google API Daily Limit

19.1 Prerequisites

This guide assumes:

1. You have a functional PokeAlarm installation

2. You have an available Google account (e.g., Gmail)

3. You have read and understood the available Command Line Arguments in the Server Settings wiki

19.2 Introduction

Using a Google Maps API key in PokeAlarm is optional. It enable additional features in PokeAlarm.

81


In order to use a feature, you must have the corresponding API enabled in Google API Manager, and have a generatedGoogle Maps API key. Below are the available features, and Google Map API to enable for that feature:

PokeAlarm Feature Google Maps API to EnableSet a location by name or address Google Maps GeocodingCalculate walking/biking/driving distance from a set location Google Maps Distance MatrixShow a Mini Map of pokemon, gyms, lures, eggs or raids Google Static Maps

You will enable the APIs per the requirements of you own PokeAlarm installation. In other words, if you only wantstatic maps, enable just the Google Static Maps API. If you want static maps and to set your location, enable theGoogle Static Maps and Google Maps Geocoding APIs.

In this guide, we will:

1. Enable all 3 APIs and generate an API key that will allow PokeAlarm to provide these features

2. Test the key to make sure it working correctly

3. Start PokeAlarm with your API key

19.3 Enabling the Various Google Maps APIs and Obtaining a Key

Now we’re going create a new project, add our 3 APIs to it, then generate our API key.

1. Log into Google API Manager.

2. Click Dashboard at the left. If this is your first time visiting the developers console, you should see “No APIsenabled” in the middle, like the image below.

3. At the top of the page, click the Project dropdown, then select Create project.

82 Chapter 19. Location Services

https://console.developers.google.com/


4. Name this project whatever you would like, e.g., “PokeAlarm”. Click Create.

5. You should now see your project name at the top. Click the blue +ENABLE API button at the top middle,which will bring your to the Google API Library. (You can also click Library at the left.)

19.3. Enabling the Various Google Maps APIs and Obtaining a Key 83


6. The Google API Library is where we will select our 3 APIs to enable. Let’s enable the Google Maps GeocodingAPI first. You can either type Google Maps Geocoding API in the middle search bar, or click on it under the“Google Maps API” section in the middle right.

7. You should see Google Maps Geocoding API. Click the blue ENABLE button at the top to enable the GoogleMaps Geocoding API.



You should see this screen if enabled:

Click on Dashboard at the left. You should now see Google Maps Geocoding API at the middle bottom.



8. Click on Library at the left and repeat the same process of enabling APIs for the Google Maps DistanceMatrix and Google Static Maps APIs. When you are finished, click Dashboard on the left and make sure thatyou see all 3 APIs at the middle bottom.

9. Now that we have the 3 APIs enabled, let’s generate our API key. Click on Credentials at the left, then the blueCreate Credentials in the middle.



10. Click API key in the middle.

11. Select Browser key.



12. If desired, name your key, or leave it as the default name. Click the blue Create button.

13. Your new API key will appear. Click the blue OK button.



To find your key later, click on the blue Credentials button at the left.

19.4 Testing Your API Key

Now that you have your various APIs enabled and your API key created, let’s test to see if it is working correctly.

19.4.1 Geocoding

To verify that your API key is working for geocoding and reverse geocoding, visit the URLs below and replaceYOUR_API_KEY with your Google Maps API key.

Geocoding

19.4. Testing Your API Key 89


https://maps.googleapis.com/maps/api/geocode/json?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&key=YOUR_API_KEY

Reverse Geocoding

https://maps.googleapis.com/maps/api/geocode/json?latlng=40.714224,-73.961452&key=YOUR_API_KEY

19.4.2 Distance Matrix

To verify that your API key is working for travel distance and time, visit the URLs below and replace YOUR_API_KEYwith your Google Maps API key.

https://maps.googleapis.com/maps/api/distancematrix/json?units=imperial&origins=Washington,DC&destinations=New+York+City,NY&key=YOUR_API_KEY

19.4.3 Static Maps

To verify that your API key is working for Static Maps, visit the URL below and replace YOUR_API_KEY with yourGoogle Maps API key.

https://maps.googleapis.com/maps/api/staticmap?center=Brooklyn+Bridge,New+York,NY&zoom=13&size=600x300&maptype=roadmap&markers=color:blue%7Clabel:S%7C40.702147,-74.015794&markers=color:green%7Clabel:G%7C40.711614,-74.012318&markers=color:red%7Clabel:C%7C40.718217,-73.998284&key=YOUR_API_KEY

If your key is valid, you should see this same static map image in your browser:

Starting PokeAlarm with a Google Maps API Key

There are 2 methods to start PokeAlarm with your Google Maps API key:

1. Run the command python start_pokealarm.py -k YOUR_GOOGLE_MAPS_API_KEY



2. Add key:YOUR_GOOGLE_MAPS_API_KEY to config.ini located in the config subfolder of yourPokeAlarm installation, then run the command python start_pokealarm.py.

19.5 Google API Daily Limit

Google allows up to 2,500 API requests per day for free. You may view your API usage from the Dashboard of theGoogle API Manager. If you have exceeded the free daily quota of 2,500 hits, the mapping elements in PokeAlarmmay not function correctly. If you find that you are exceeding the free daily 2,500 API calls, you may either switchto another valid Google Maps API key for the day or sign up for a Google Maps API Premium plan. For pricinginformation, visit the Google Maps API Pricing and Plans page.

19.5. Google API Daily Limit 91

https://console.developers.google.com/

https://developers.google.com/maps/pricing-and-plans/#details



CHAPTER 20

Contributing

20.1 Overview

This guide will show you how to submit issues, suggestions, feature requests, and wiki corrections to the PokeAlarmteam.

• Before You Begin

• Introduction

• Submitting an Issue

• Submitting a Pull Request

• Submitting a change to the to the readthedocs

20.2 Before You Begin

If you’re trying to troubleshoot an issue that you’re having that may not be a issue needing to be fixed within PokeAlarmitself, try visiting the PokeAlarm #troubleshooting channel on Discord.

20.3 Introduction

There are two ways to submit information to the PokeAlarm Github, each with its own template to be used.

• An Issue can be submitted to draw attention to a bug that needs to be fixed, to request a new feature, or to givesuggestions.

• If you know how to implement fix or a change that you’d like to see, you can submit a Pull Request.

93

https://discord.gg/S2BKC7p

https://github.com/PokeAlarm/PokeAlarm/issues

https://github.com/PokeAlarm/PokeAlarm/pulls


20.4 Submitting an Issue

1. From within the master branch of PokeAlarm, click on the Issues tab.

2. Click on the green button labeled "New issue".

3. Create a relevant title for your submission.

4. There are two templates preloaded into the Issue submission box - one for bugs and user issues and the otherfor enhancements and suggestions. All submissions do require the use of a template in order to be considered.Make sure to address only one issue per submission. Copy the applicable template and remove the one that youdo not need.

5. Click on "Submit new issue" button when finished.

20.5 Submitting a Pull Request

Pull Requests (PRs) are submitted through the dev branch of PokeAlarm to be tested prior to being included inperiodic patches merged to the Master branch. All coding to be considered must meet PEP 8 standards for Python andshould be checked using Flake8.

Our development team utilizes Travis CI for automated testing. Travis CI is a continuous integration service thatchecks for issues when PRs are first opened and when commits are added to them. Feedback on PRs will typicallybe given within 4 days from the date of the initial submission, excluding holidays. If changes are requested, pleasecomment on the PR when those changes have been completed.

Please keep your PR up to date so that we can pull it without conflicts. For clean git histories, use rebase instead ofmerging. To do this:

git fetch origingit rebase -i origin/dev(comment out all the commits that aren't related to yours)(handle any conflicts that arise from rebase)git push <personal_remote> <branch_name>

20.6 Submitting a change to the readthedocs

Submissions for changes to the readthedocs are to be made through Pull Requests on the PokeAlarm repository, all thereadthedocs files are inside docs folder.

The Wiki consists of files written using Markdown or reStructuredText, saved with the .md/.rst file extension.

1. From within the Master branch of the PokeAlarm repo, click on the Branch dropdown and choose dev fromthe menu.

2. Once the dev branch page loads, click the New Pull Request button.

3. Add a title for your request and include some information about your submission in the textbox.

4. Upload a new or updated file and click Create Pull Request.

94 Chapter 20. Contributing

http://flake8.pycqa.org/en/latest/index.html

https://github.com/PokeAlarm/PokeAlarm

https://help.github.com/articles/basic-writing-and-formatting-syntax/

http://docutils.sourceforge.net/docs/user/rst/quickref.html

CHAPTER 21

Indices and tables

• genindex

• modindex

• search

95

PokeAlarm Documentation - Read the Docs

Documents