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,18 @@
 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. This password is shared across all bots. 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.
+
+* Bot end-point :
+  - GET `/api/bots` => List all bots
   - 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 +32,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,22 @@
 # 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 much 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 login in the official client and you 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 +25,32 @@ 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
+ * You catched 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 +74,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