Updated explanation in several files

.github/ISSUE_TEMPLATE.md

@@ -1,3 +1,11 @@
+### Prerequisites (Remove this section if you want)
+Make sure you...
+
+* Have checked the FAQ if your question has not been answered there.
+* Have searched the existing issues if your question has not been asked here.
+* Post a FULL stacktrace and not only a part of it.
+* Fill in all the fields correctly, it helps us immensly if we get a complete image of your situation.
+
 **Description:**
 [Short description of the issue observed. If this is feature request you can modify the template as required.]
 

API.md

@@ -1,13 +1,20 @@
 REST API Documentation :
 
-* Secure your API with the `rest_api_password` setting. This password is shared across all bots. If the setting isn't set, it will be generated and saved in the config file.
-* Request an access token with a `POST` to `/api/bot/{name}/auth`, the request body must be `rest_api_password`. This token must be placed in the `X-PGB-ACCESS-TOKEN` header for further use of the API.
-* Bot end-point : 
+* Secure your API by putting a secure and random password in the `rest_api_password` setting in your config.properties file or the `restApiPassword` setting in your JSON file(s). Each bot has its own password, so use the correct one in the next step (or if you are lazy, use the same value everywhere). If the configuration key is not set, it will be generated and saved in the config file.
+
+* Request an access token with a `POST` to `http://localhost:8080/api/bot/{name}/auth` where `{name}` is the name of your bot (= `default` by default) and the raw body must be the value from the `rest_api_password` setting from the first step. Mind the default server port, which is 8080 (to change this, run the bot as `java -jar PokemonGoBot.jar --server-port=XXXX`) and do NOT use the socket port defined in your bot configuration (which is by default 8001).
+You will get a response from the server with a random session token which must be placed in the `X-PGB-ACCESS-TOKEN` header for further use of the API.
+
+* General end-point :
+  - GET `/api/bots` => List all bots (this does not need the `X-PGB-ACCESS-TOKEN` header)
+
+* Bot end-point :
   - POST `/api/bot{name}/load` => Load bot
   - POST `/api/bot{name}/unload` => Unload bot
   - POST `/api/bot{name}/reload` => Reload bot
   - POST `/api/bot{name}/stop` => Stop bot
   - POST `/api/bot{name}/start` => Start bot
+
 * Pokemon end-point :
   - GET `/api/bot{name}/pokemons` => List all pokemons
   - POST `/api/bot{name}/pokemon/{id}/transfer` => Transfer pokemon
@@ -27,4 +34,6 @@ REST API Documentation :
   - POST `/api/bot{name}/location/{latitude}/{longitude}` => Change bot location
   - GET `/api/bot{name}/profile` => Get account profile
   - GET `/api/bot{name}/pokedex` => Get account pokedex
-  - GET `/api/bot{name}/eggs` => Get eggs
+  - GET `/api/bot{name}/eggs` => Get eggs
+
+A very simple [proof of concept with javascript](https://gist.github.com/Sieberkev/0f96f190615cebf15a07ca2a8a2a61ca) can be found here.

FAQ.md

@@ -1,13 +1,24 @@
 # Frequently Asked Questions
 
 ## I got `BUILD FAILED`
-Most of the time it's because the you didn't execute step 2 of the README.
 
-After that, just try `gradlew clean build`.
+There is a lot of output with the reason WHY the build fails, please read it through carefully and fix any errors mentionned in the output.
 
-If there's still a problem, open an issue.
+## I get an `AsyncPokemonGoException: Unknown exception occurred` / `Error running loop ProfileLoop!` / `Error running loop BotLoop!`
 
-## The bot doesn't catch Pokemon
+Only that is not enough, check the whole stacktrace for the correct error.
+
+## I get an `InvalidProtocolBufferException: Contents of buffer are null`
+
+This is a known issue with the currently used Pokemon GO API. The bot sends too many requests in a too short time to the servers, which return with a null value. We hope to get that fixed shortly, but is not something you can simply fix with some configuration settings or by putting extra Thread.sleep() in the code.
+
+## After login I see `Accepting ToS` and get a `RemoteServerException: Your account may be banned! please try from the official client.`
+
+If you CAN login to the official client, complete the tutorial (catch your first pokemon, touch your first pokestop) and try again.
+
+If you CAN'T login in the official client but see "Error fetching game data": RIP items/eggs/pokemons, your account got permabanned. You knew this was possible since you did read and violate the ToS of the official game.
+
+## The bot doesn't find/catch Pokemon
 
 Currently not reproducible so can't be reliably fixed. Look here for some people that managed to get it fixed: https://github.com/jabbink/PokemonGoBot/issues/21
 
@@ -16,16 +27,33 @@ Some possible issues:
  * Make sure your system time is (semi-)correct (let it autosync with an online server)
  * Make sure the mobile app is not on (kill the process if need be)
  * Make sure the account you're botting on did do the initial tutorial (mainly catching a starter Pokemon)
+ * Make sure your item bank is empty
+ * Make sure you have enough pokeballs and your pokebank is not full
+ * You caught too many pokemons in a short time and are softbanned (don't catch more than 1000 Pokemon in 23 hours, [source](https://www.reddit.com/r/pokemongodev/comments/4xkqmq/new_ban_types_and_their_causes/)).
+
+## The bot doesn't find/loot Pokestops
+
+Some possible issues:
+
+ * Your startlocation is wrong and/or there are no pokestops nearby.
+ * You looted too many pokestops in a short time and are softbanned (don't loot more than 2000 Pokestops in 23 hours, [source](https://www.reddit.com/r/pokemongodev/comments/4xkqmq/new_ban_types_and_their_causes/))
+
+## The bot doesn't walk
+
+Some possible issues:
+
+ * You're camping a Pokestop with a lure (should be visible in log)
+ * You're resting (should be visible in log)
 
 ## Immediately after starting I get a LoginFailedException
 
 - Make sure the provided credentials in the `config.properties` file are correct.
 - If you're using PTC, your credentials are correct and your password is longer than 15 characters, only enter the first 15 characters of your account and the login should work.
 - If there is a token present, remove it and retry.
 
-## After 1.5 hours I get a errors with Google login
+## After 1.5 hours I get a errors with PTC/Google login `LoginFailedException: Invalid Auth status code recieved, token not refreshed?`
 
-Known issue with the Java API handling login for Google.
+Known issue with the Java API handling login for PTC/Google.
 
 ## I get a RemoteServerException or something about "502"
 
@@ -49,23 +77,27 @@ If your bot runs the GUI socket on port `8001`, everything should work automatic
 
 ## The bot refuses to login to my Google account
 
-Make sure you enter the full email address (including `@`) in the `username=` property.
+Make sure you enter the full email address (including `@`) in the `username=` property. If you use a JSON configuration, make sure the credential type is set as `google-auto`.
 
 ## Error: unable to access jarfile xxxxx
 
-Make sure you are working in the directory where the JAR file is located
+Make sure you are working in the directory where the JAR file is located. If you JAR file is located in `C:\Users\userprofilename\Desktop\pogobot\` you can change your directory in the console with the command `cd C:\Users\userprofilename\Desktop\pogobot\` (do not simply copy/paste this command but alter it to your location first).
 
 ## I want to use multiple bots
 
 Define the bot configurations in multiple JSON files in the `bot-settings` directory.
 
 Refer to the file named [`json-template.json`](./json-template.json) for an example.
 
+If you use a PTC account, set credential type to "ptc", if you use a Google account, set credential type to `google-auto`!
+
 Make sure all JSON files have a different `guiPortSocket` or set that port to `0`!
 
 ## I get "Address already in use"
 
-You are either trying to run multiple bots by running Java multiple times, multiple bot configurations use the same `guiPortSocket` or the port is simply in use by another application.
+It is possible you did not close the bot correctly (do not close the console window, but do `CTRL+C` first to close the process) and it is still running in the background. Kill all running JAVA processes and restart the bot.
+
+If that is not the case, you are either trying to run multiple bots by running Java multiple times, multiple bot configurations use the same `guiPortSocket` or the port is simply in use by another application.
 
 To change the socket ports, change `guiPortSocket` (`gui_port_socket` in `config.properties`) to another port, or disable the GUI by setting this to `0`.
 

USAGE.md

@@ -14,7 +14,7 @@ having to answer the same question can really clog up the pipes for people who a
 
 ## Prebuilt
 
-1. Make sure you have Oracle Java 1.8 or higher installed (`java -version` in a command line)
+1. Make sure you have Oracle Java 1.8 JRE (JDK works too) installed (`java -version` in a command line)
     - If not, go [here](http://www.oracle.com/technetwork/java/javase/downloads/jre8-downloads-2133155.html).
 2. Download the latest release from [here](https://github.com/jabbink/PokemonGoBot/releases).
 3. Download [config.properties.template](https://raw.githubusercontent.com/jabbink/PokemonGoBot/master/config.properties.template) and save it in the same directory
@@ -26,9 +26,15 @@ having to answer the same question can really clog up the pipes for people who a
 
 ## From source
 
-1. Clone this repo: `git clone https://github.com/jabbink/PokemonGoBot.git && cd PokemonGoBot` or download the zip
-2. Run from terminal/cmd: `gradlew build`
-3. Rename `./config.properties.template` to `./config.properties`
-4. Modify `config.properties` as you please
-5. To run the bot directly from console run `gradlew run`
-6. :exclamation: If you use JetBrains IntelliJ, install the Lombok plugin and enable Settings -> Compiler -> Annotation Processors -> Enable annotation processing :exclamation:
+1. Make sure you have Oracle Java JDK 1.8 installed (`java -version` in a command line)
+    - If not, go [here](http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html).
+2. Clone this repo: `git clone https://github.com/jabbink/PokemonGoBot.git && cd PokemonGoBot` or download the zip
+3. Run from terminal/cmd: `gradlew build`
+4. Copy `./config.properties.template` to `./config.properties`
+5. Modify `config.properties` as you please
+6. To run the bot directly from console run `gradlew run`
+7. :exclamation: If you use JetBrains IntelliJ, install the Lombok plugin and enable Settings -> Compiler -> Annotation Processors -> Enable annotation processing :exclamation:
+
+## Stopping the bot
+
+Do not simply close the console window, but press `CTRL+C` first to terminate the bot gracefully. Otherwise there's a chance the process will still run in the background and give an `address in use` error when you want to restart it.

config.properties.template

@@ -14,10 +14,14 @@ proxy_type=SOCKS
 proxy_username=
 proxy_password=
 
-# Token to login directly
+# Token to login directly (leave this empty, the bot will fill this in automatically)
 token=
+
+# Fill in the start GPS location (latitude/longitude) where you want the bot to start
 latitude=
 longitude=
+
+# Do you want the bot so start from the location when you shut it down?
 save_location_on_shutdown=true
 
 # Desired probability to catch Pokemon with 1 throw