Created HomeAPI Setup (markdown)

2025-07-21 01:45:54 +02:00
parent 9a4cc926a2
commit bc248b1bf4
1 changed files with 164 additions and 0 deletions
--- a/HomeAPI-Setup.md
+++ b/HomeAPI-Setup.md
@@ -0,0 +1,164 @@
+## What is This?
+
+You can think what we are about to configure in this tutorial is the server for giving the ESP32 the image data it needs to display it on the screen.
+
+$\color{Red}\Huge{\textsf{THIS API IS CURRENTLY BUILT FOR FETCHING SWEDISH PUBLIC TRANSPORT DATA,}}$
+$\color{Red}\Huge{\textsf{YOU WILL HAVE TO DISABLE IT OR REPLACE IT IF YOU DON'T LIVE IN SWEDEN.}}$
+
+
+---
+
+## Step 1: Download & Extract
+
+1. **Download** the zip file provided to your computer.
+2. **Extract** the zip file to a folder, e.g., `C:\HomeApi` or your Desktop.
+
+---
+## Step 2: Configuring the API
+When you have extracted the zip file there should be a ``appsettings.json`` file inside the folder. Open it and edit the lines I have marked.
+
+Public API's that require keys: 
+ - https://www.weatherapi.com/ (Weather)
+ - https://www.trafiklab.se/api/our-apis/resrobot-v21/ (ResRobot)
+
+```json
+{
+  "Kestrel": {
+    "Endpoints": {
+      "Http": {
+        "Url": "http://*:5000"
+      }
+    }
+  },
+  "Logging": {
+    "LogLevel": {
+      "Default": "Information",
+      "Microsoft.AspNetCore": "Warning"
+    }
+  },
+  "ApiConfiguration": {
+    "EspConfiguration": {
+      "InformationBoardImageUrl": "http://192.168.101.178:5000/home/default.jpg", <--- Server Address (always use ip)!
+      "UpdateIntervalMinutes": 2,
+      "BlackTextThreshold": 190,
+      "EnableDithering": true,
+      "DitheringStrength": 8,
+      "EnhanceContrast": true,
+      "ContrastStrength": 10,
+      "IsHighContrastMode": true
+    },
+    "Keys": {
+      "Weather": "NOT COMMITED", <---- WeatherApi key 
+      "ResRobot": "NOT COMMITED" <---- Swedish transit api key
+    },
+    "BaseUrls": {
+      "Nominatim": "https://nominatim.openstreetmap.org",
+      "Aurora": "http://api.auroras.live",
+      "Weather": "https://api.weatherapi.com/v1",
+      "ResRobot": "https://api.resrobot.se"
+    },
+    "DefaultCity": "Stockholm, stockholms lan",
+    "DefaultStation": "Stockholm C"
+  },
+  "AllowedHosts": "*"
+}
+```
+---
+
+## Step 3: Install .NET 9 Runtime
+
+> **You must install the .NET 9 Runtime to run this app.**
+
+### 1. Go to the official .NET download page:
+
+- [https://dotnet.microsoft.com/download/dotnet/9.0](https://dotnet.microsoft.com/download/dotnet/9.0)
+
+### 2. Download the correct runtime:
+
+- Choose **".NET Runtime"** (not SDK).
+    - For Windows, select "x64" or "Arm64" depending on your machine.
+    - For Mac/Linux, pick the right option for your OS.
+
+### 3. Install:
+
+- Run the installer and follow the instructions.
+
+---
+
+## Step 4: Verify .NET Installation
+
+Open your **Command Prompt** (Windows) or **Terminal** (Mac/Linux) and run:
+
+```sh
+dotnet --version
+```
+
+- If it prints something like `9.0.x`, you are ready!
+
+---
+
+## Step 6: Run the API
+
+1. **Navigate** to the extracted folder.  
+   - Example (Windows):
+     ```sh
+     cd C:\HomeApi\dotnet
+     ```
+   - Example (Mac/Linux):
+     ```sh
+     cd ~/Downloads/HomeApi/dotnet
+     ```
+
+2. **Run the API**:
+   ```sh
+   dotnet HomeApi.dll
+   ```
+
+3. You should see output like:
+   ```
+   Now listening on: http://localhost:5000
+   Application started. Press Ctrl+C to shut down.
+   ```
+
+---
+
+## Step 6: Test the API
+
+- Open your web browser and go to:  
+  [http://localhost:5000/scalar](http://localhost:5000/scalar)
+- You should see an API documentation page.
+
+---
+
+## Stopping the API
+
+- Press `Ctrl+C` in the terminal window where the app is running.
+
+---
+
+## FAQ
+
+**Q: I get 'dotnet is not recognized'?**  
+The .NET runtime is not installed or not added to your PATH. Re-install it and reboot your computer.
+
+**Q: How do I change the port?**  
+Open `appsettings.json` and look for URLs or configuration relating to ports. Edit as needed, or run with:
+```sh
+dotnet HomeApi.dll --urls "http://localhost:8080"
+```
+
+**Q: Do I need Visual Studio?**  
+No! You only need the .NET 9 Runtime.
+
+**Q: How do I call the API?**  
+You can use a browser for GET endpoints or tools like [Postman](https://www.postman.com/) or `curl` for others.
+
+---
+
+## Useful Links
+
+- [.NET 9 Runtime Download](https://dotnet.microsoft.com/download/dotnet/9.0)
+- [Postman](https://www.postman.com/)
+- [Official .NET Docs](https://learn.microsoft.com/dotnet/core/)
+
+---