Merge pull request #24 from UnownHash/dec-10

docs: FAQ and some general usage info
UnownHash · Dec 10, 2023 · 8850547 · 8850547
2 parents be054c8 + cd9d905
commit 8850547
Show file tree

Hide file tree

Showing 11 changed files with 199 additions and 58 deletions.
diff --git a/.prettierrc b/.prettierrc
@@ -2,11 +2,13 @@
   "semi": false,
   "trailingComma": "all",
   "singleQuote": true,
+  "proseWrap": "never",
   "overrides": [
     {
       "files": "*.mdx",
       "options": {
         "tabWidth": 4
       }
     }
+  ]
 }
diff --git a/pages/docs/dragonite/_meta.json b/pages/docs/dragonite/_meta.json
@@ -1,5 +1,6 @@
 {
   "index": "Introduction",
   "config": "Configuration",
+  "faq": "FAQ",
   "troubleshooting": "Troubleshooting"
 }
diff --git a/pages/docs/dragonite/config.mdx b/pages/docs/dragonite/config.mdx
@@ -3,25 +3,24 @@ import { Callout } from 'nextra-theme-docs'
 # Dragonite Configuration
 
 <Callout type="info" emoji="🚧">
-  This page is still under construction
+    This page is still under construction
 </Callout>
 
-
 ## General section
 
 ```toml
 [general]
-login_delay = 20 
-# seconds to sleep in-between PTC authing on one proxy
-
-# Whether raw worker stats are written
-stats = false
-
-# Host and Port used for the Dragonite API
-api_host = "127.0.0.1"
-api_port = 7272
+login_delay = 20
+...
 ```
 
+| Key | Default | Description |
+| :-- | :-- | :-- |
+| `login_delay` | 20 | Seconds to sleep in-between PTC authenticating with one proxy. For "unlimited" proxies we recommend setting this value to 1. |
+| `stats` | false | Whether raw worker stats are written to the Dragonite database. |
+| `api_host` | 127.0.0.1 | Host listener address for Dragonite API. |
+| `api_port` | 7272 | Host port address for Dragonite API. |
+
 ## Koji section
 
 ```toml
@@ -30,33 +29,52 @@ url = "http://ip:port"
 bearer_token = "KOJI_SECRET"
 ```
 
+| Key | Default | Description |
+| :-- | :-- | :-- |
+| `url` | "http://ip:port" | The URL for your Koji service. |
+| `bearer_token` | "KOJI_SECRET" | When Koji secret (`KOJI_SECRET`) configuration is enabled you must pass a secure token so Dragonite is able to communicate. |
+
 ## Prometheus section
 
 ```toml
 #[prometheus]
 #enabled = true
 ```
 
+| Key | Default | Description |
+| :-- | :-- | :-- |
+| `enabled` | true | Uncomment and enable this value to turn on the prometheus endpoint within Dragonite. |
+
 ## Tunning section
 
 ```toml
 [tuning]
 dynamic_route_split = true
-#recycle_gmo_limit = 4900
-#recycle_encounter_limit = 9900
-#recycle_on_jail=false
-#minimum_account_reuse_hours = 169
-#location_delay = 0
-#fort_location_delay = 0
+...
 ```
 
+| Key | Default | Description |
+| :-- | :-- | :-- |
+| `dynamic_route_split` | true | When enabled Dragonite will update the route that workers are using as they connect or disconnect from an area. |
+| `recycle_gmo_limit` | 4900 | (Advanced) Recommend keeping this value commented out. When the GMO limit is reached for a specific account it will be be rotated. |
+| `recycle_encounter_limit` | 9900 | (Advanced) Recommend keeping this value commented out. When an account has encountered this amount of pokemon it will be rotated. |
+| `recycle_on_jail` | false | Enabling this setting will utilize significantly more accounts. Currently three accounts are assign to one worker and will rotate while the worker is running. |
+| `location_delay` | 0 | This value, in milliseconds, will add a slight wait period while a worker is moving to a new location. Adding a slight delay has proven to decrease empty GMO results and positively impact scans overall. Recommend starting with 100, 200, 300, etc and monitoring overall results. |
+| `fort_location_delay` | 0 | This value, in milliseconds, is the same as `location_delay` however it only impacts fort scans (gyms/pokestops). |
+
 ## Rotom section
 
 ```toml
 [rotom]
 endpoint = "ws://127.0.0.1:7071"
+#secret = ""
 ```
 
+| Key | Default | Description |
+| :-- | :-- | :-- |
+| `endpoint` | "ws://127.0.0.1:7071" | This is the URL for your Rotom service. |
+| `secret` | "" | When Rotom secret configuration is enabled you must pass a secure token so Dragonite is able to communicate. |
+
 ## Logging section
 
 ```toml
@@ -67,26 +85,43 @@ save = true
 #max_age = 30 # days
 ```
 
+| Key | Default | Description |
+| :-- | :-- | :-- |
+| `save` | true | When enabled Dragonite will write log files to disk. |
+| `debug` | false | When enabled Dragonite will write debug logging, which is very "chatty" and not required for general usage. |
+| `max_size` | 500 | Max size that Dragonite will allow log files to grow before being deleted. |
+| `debug` | 30 | Time that logs will live on disk in days before Dragonite deletes the log file. |
+
 ## Processors section
 
 ```toml
 [processors]
-# Golbat Endpoint is singular - and will configure an endpoint for raw sending and API
 golbat_endpoint = "http://127.0.0.1:9001"
 golbat_raw_bearer = ""
 golbat_api_secret = ""
-# if this is present then dragonite will not send raws to the httpendpoint
 #golbat_grpc_endpoint = "127.0.0.1:50001"
 ```
 
+| Key | Default | Description |
+| :-- | :-- | :-- |
+| `golbat_endpoint` | "http://127.0.0.1:9001" | Golbat (http) Endpoint is singular and will configure an endpoint for raw sending and API. |
+| `golbat_raw_bearer` | false | Golbat raw bearer value (empty string for none). |
+| `golbat_api_secret` | 500 | Golbat secret when making api calls (empty string for none). |
+| `golbat_grpc_endpoint` | 30 | When enabled dragonite will not send raws to the `golbat_endpoint` (http endpoint). |
+
 ## Database section
 
 ```toml
 [db.dragonite]
 host = "0.0.0.0"
-port = 3306
-user = ""
-password = ""
-name = "dragonite"
-pool_size = 1
+...
 ```
+
+| Key | Default | Description |
+| :-- | :-- | :-- |
+| `host` | "0.0.0.0" | Database host address. |
+| `port` | 3306 | Database port address. |
+| `user` | "" | Database username. |
+| `password` | "" | Database password. |
+| `name` | "dragonite" | Database table name. |
+| `pool_size` | 1 | Database pool size is used to control how many connections are made from Dragonite. |
diff --git a/pages/docs/dragonite/faq.mdx b/pages/docs/dragonite/faq.mdx
@@ -0,0 +1,66 @@
+# Dragonite FAQ
+
+##### Q: How many accounts do I need?
+
+This depends heavily on your routes, scan location, configuration, network stability, MITM stability, etc. The only guidance we can give is having a weeks worth of accounts before reuse to satisfy the default tunning values. With game limitations this is a good starting point.
+
+##### Q: What settings does Dragonite use when creating a route?
+
+Dragonite sends requests to Koji to create routes. The default settings for each route type is listed below:
+
+**Pokemon**
+
+-   Mode: Cluster
+-   Category: Spawnpoint
+-   Radius: 70 (meters)
+-   Min Points: 3
+-   Cluster mode: Balanced
+
+**Pokemon (Bootstrap)**
+
+TBD
+
+**Fort**
+
+TBD
+
+**Fort Full**
+
+TBD
+
+##### Q: What logging options should I use?
+
+Docker, pm2, and Dragonite all have their own built-in logging options. While this is personal preference we do recommend you use Dragonite's logging and disable the others. Dragonite's logging will handle cleanup based on file size and length of time, we also compress these log files. Using tools like `zgrep`, `zless`, etc will allow you to read these compressed files.
+
+##### Q: How are POI names collected?
+
+Automatically of course! While a worker is scanning in any mode, except Level, we gather names and descriptions of Gyms and Pokestops.
+
+##### Q: Are lures accurate?
+
+Yes, instead of guessing that a lure will be 30 minutes we will open the Pokestop to gather the correct duration that a lure module is active, great for events that have long durations.
+
+##### Q: Can I see Gym Defenders?
+
+Dragonite will trigger this in game event but Golbat does not decode this proto.
+
+##### Q: How can I get in game route?
+
+Routes are collected when scanning for quests and during the Fort Mode.
+
+##### Q: How do Showcases work?
+
+We open Pokestops every 15mins to collect updated Showcase information. This response is stored in a global cache to make sure two workers don't request the same data.
+
+##### Q: What is fort mode?
+
+Fort mode is used for Pokestops and Gyms. Fort data is also collected during Pokemon routes however Fort mode can be used to optimize timings and allow extra flexibility for Unown# users. It's possible to scan a much larger area with Fort mode in a reasonable time while Pokemon routes handle smaller clusters.
+
+Fort mode uses 2 routes.
+
+-   Full route is basically bootstrap for whole fence, and a worker will run through the route once per day
+-   Route is optimized route, where workers will skip jumps without active POIs
+
+##### Q: I am seeing Empty GMOs in logs?
+
+Some amount of retry is expected. If a worker fails to get the expected data we will re-request the results. Tunable in the configuration section. It is possible that increasing your location delay might help, if you are seeing large amounts of retries in the logs.
diff --git a/pages/docs/golbat/_meta.json b/pages/docs/golbat/_meta.json
@@ -1,6 +1,7 @@
 {
   "index": "Introduction",
   "config": "Configuration",
+  "faq": "FAQ",
   "pvp": "PVP",
   "stats": "Statistics"
 }
diff --git a/pages/docs/golbat/faq.mdx b/pages/docs/golbat/faq.mdx
@@ -0,0 +1,5 @@
+# Golbat FAQ
+
+##### Q: What level accounts are required?
+
+Golbat requires all accounts be level 30+ to perform standard scanning. This requirement makes sure that all IV and quest scans have proper values.
diff --git a/pages/docs/golbat/stats.mdx b/pages/docs/golbat/stats.mdx
@@ -4,22 +4,27 @@ import Image from 'next/image'
 
 Golbat comes with basic database statistics built in. These tables are named with the `_stats` suffix. With these tables you can use raw SQL queries or hook into a third party visualization tool to visualize the data that Golbat is parsing.
 
-[Blissey](/docs/other/blissey) and our [Prometheus](https://github.com/UnownHash/Golbat/pull/100) integration can be used to get started on visualizing the data.
+[Blissey](/docs/other/blissey) and our [Prometheus](/docs/other/prometheus) integration can be used to get started on visualizing the data.
 
-<br/>
+<br />
 
-<Image src="https://user-images.githubusercontent.com/52629375/265464011-c2bcee57-834c-4694-b201-fa7524a7a52a.jpg" alt="Performance demo" width={900} height={900} />
+<Image
+    src="https://user-images.githubusercontent.com/52629375/265464011-c2bcee57-834c-4694-b201-fa7524a7a52a.jpg"
+    alt="Performance demo"
+    width={900}
+    height={900}
+/>
 
 ## Built-in statistic tables
 
-| Table name         |
-|--------------------|
-| raid_stats         |
-| pokemon_stats      |
-| pokemon_iv_stats   |
-| pokemon_area_stats |
-| pokemon_hundo_stats|
-| pokemon_nundo_stats|
-| quest_stats        |
-| invasion_stats     |
-| pokemon_shiny_stats|
+| Table name          |
+| ------------------- |
+| raid_stats          |
+| pokemon_stats       |
+| pokemon_iv_stats    |
+| pokemon_area_stats  |
+| pokemon_hundo_stats |
+| pokemon_nundo_stats |
+| quest_stats         |
+| invasion_stats      |
+| pokemon_shiny_stats |
diff --git a/pages/docs/other/hybrid-setup.mdx b/pages/docs/other/hybrid-setup.mdx
@@ -3,34 +3,35 @@ import { Callout } from 'nextra-theme-docs'
 # Hybrid Setup
 
 <Callout type="warning" emoji="⚠️">
-  This temporary solution is only required if you are using a legacy client and RealDeviceMap (RDM).
+    This legacy solution is only required if you are using a legacy client and
+    RealDeviceMap (RDM).
 </Callout>
 
-There are two methods to send data to Golbat while continuing to use the device controller component from RealDeviceMap (RDM). This will allow you take advantage of Golbat's parsing.
+This will allow you take advantage of Golbat's parsing.
 
 ## Using RDM Raw Reflection
 
 As of RealDeviceMap (RDM) version 1.51.0 (July 11, 2023) you can use the built-in `raw forward` option. Some notes:
 
-- This only works with the json config option
-- Disabling `application.process.pokemon` and `application.process.incident` are optional however they will save on disk IO
-- When `application.process.pokemon` is disabled:
-  - "Pokemon IV" instances will not function
-  - RDM frontend will not display pokemon
+-   This only works with the json config option
+-   Disabling `application.process.pokemon` and `application.process.incident` are optional however they will save on disk IO
+-   When `application.process.pokemon` is disabled:
+    -   "Pokemon IV" instances will not function
+    -   RDM frontend will not display pokemon
 
 Example configuration:
 
 ```json
 {
-  "application": {
-    "rawForward": {
-      "url": "http://yourGolbat:9001/raw",
-      "bearer": "yourGolbatBearerSecret"
-    },
-    "process": {
-      "pokemon": false,
-      "incident": false
-    },
-  }
+    "application": {
+        "rawForward": {
+            "url": "http://yourGolbat:9001/raw",
+            "bearer": "yourGolbatBearerSecret"
+        },
+        "process": {
+            "pokemon": false,
+            "incident": false
+        }
+    }
 }
 ```
diff --git a/pages/docs/other/prometheus.mdx b/pages/docs/other/prometheus.mdx
@@ -0,0 +1,10 @@
+import { Callout } from 'nextra-theme-docs'
+
+# Prometheus
+
+<Callout type="info" emoji="🚧">
+    This page is still under construction
+</Callout>
+
+-   https://github.com/UnownHash/Golbat/pull/100
+-   https://github.com/UnownHash/prom-dashboards
diff --git a/pages/docs/other/terminology.mdx b/pages/docs/other/terminology.mdx
@@ -1,4 +1,3 @@
-
 # Terminology
 
 This page includes definitions for most of the commonly used components used within the Unown# stack.
@@ -11,6 +10,10 @@ Niantic Pokemon Trainer Club (PTC) accounts that can be used with the Pokemon Go
 
 Areas encapsulates a Geofence, Routes, and scheduled events. Koji can drastically speed up your ability to create and manage these as your Areas grow or change.
 
+##### Devices
+
+Devices are physical objects that generally run iOS or Android in order to play the Pokemon Go game.
+
 ##### numWiEnc (Golbat database table)
 
 Number of pokemon that initial scanned as wild, lateron encountered
@@ -35,6 +38,10 @@ This mode can be used to send workers on a pre-defined route in order to catch P
 
 This mode can be considered an On-Demand scan mode. Once workers are added to this pool end users can use a tool like [ReactMap](./other/third-party) to send workers to specific locations around the world. Useful to get data for rare pokemon or locations outside of regular scan regions.
 
+##### MITM client
+
+MITM (Man in the Middle) client is a third party solution, normally paid, that is required to collect game data. Unown# is not affiliated with any particular provider.
+
 ##### Websockets (`ws://`)
 
 Websockets are a standard communication protocol much like web traffic that occurs over port 80/443. Multiple Unown# services use websockets to allow for two way communication between client and server over a single TCP connection. If you visit an endpoint in your browser that is serving websocket traffic you will be greeted with a "Upgrade Required" message.