mirror of
https://github.com/usetrmnl/byos_laravel.git
synced 2026-01-13 15:07:49 +00:00
feat: add tests, chore: update readme
This commit is contained in:
Benjamin Nussbaum
parent
715e6a2562
commit
e6a2bdb3bc
27 changed files with 1179 additions and 299 deletions
191
README.md
191
README.md
|
|
@ -1,10 +1,24 @@
|
|||
## Laravel Trmnl Server
|
||||
|
||||
This is a PoC of a TRMNL server, written in Laravel. Inspired by https://github.com/usetrmnl/byos_sinatra
|
||||
Laravel Trmnl Server is a self-hostable implementation of a TRMNL server, built with Laravel.
|
||||
It enables you to manage TRMNL devices, generate screens dynamically, and can act as a proxy for the TRMNL API (native plugin system).
|
||||
Inspired by [usetrmnl/byos_sinatra](https://github.com/usetrmnl/byos_sinatra).
|
||||
|
||||
|
||||
|
||||
[More Screenshots](screenshots/SCREENSHOTS.md)
|
||||
|
||||
### Key Features
|
||||
|
||||
* 📡 Device Information – Display battery status, WiFi strength, firmware version, and more.
|
||||
* 🔍 Auto-Join – Automatically detects and adds devices from your local network.
|
||||
* 🖥️ Screen Generation – Supports Markup, API, or update via Code.
|
||||
* 🔄 TRMNL API Proxy – Can act as a proxy for TRMNL API (requires TRMNL Developer Edition).
|
||||
* This enables a hybrid setup – for example, you can update your custom Train Monitor every 5 minutes in the morning, while displaying native TRMNL plugins throughout the day.
|
||||
* 🐳 Deployment – Dockerized setup for easier hosting (Dockerfile, docker-compose).
|
||||
|
||||
### Requirements
|
||||
|
||||
* PHP >= 8.2
|
||||
* ext-imagick
|
||||
* puppeteer [see Browsershot docs](https://spatie.be/docs/browsershot/v4/requirements)
|
||||
|
|
@ -45,31 +59,190 @@ To make your server accessible in the network, you can run the following command
|
|||
php artisan serve --host=0.0.0.0 --port 4567
|
||||
```
|
||||
|
||||
### Docker
|
||||
Use the provided Dockerfile, or docker-compose file to run the server in a container.
|
||||
You can persist the database file by mounting a volume to `/var/www/html/database/database.sqlite`.
|
||||
|
||||
```Dockerfile
|
||||
# docker-compose.yaml
|
||||
volumes:
|
||||
- ./database/database.sqlite:/var/www/html/database/database.sqlite
|
||||
```
|
||||
|
||||
### Usage
|
||||
|
||||
#### Environment Variables
|
||||
|
||||
| environment | description | default |
|
||||
|-------------------------------|------------------------------------------------------------------|-------------------|
|
||||
| `TRMNL_PROXY_BASE_URL` | Base URL of the native TRMNL service | https://trmnl.app |
|
||||
| `TRMNL_PROXY_REFRESH_MINUTES` | How often should the server fetch new images from native service | 15 |
|
||||
| `REGISTRATION_ENABLED` | Allow user registration via Webinterface | 1 |
|
||||
|
||||
#### Login
|
||||
|
||||
If your environment is local, you can access the server at `http://localhost:4567` and login with user / password
|
||||
admin@example.com / admin@example.com
|
||||
`admin@example.com` / `admin@example.com`, otherwise register. With environment variable `REGISTRATION_ENABLED` you can control, if registration is allowed.
|
||||
|
||||
#### Add your TRMNL Device
|
||||
#### ➕ Add Your TRMNL Device
|
||||
|
||||
http://localhost:4567/devices
|
||||
##### Auto-Join (Local Network)
|
||||
|
||||
* Add new device
|
||||
* You can grab the TRMNL Mac Address and API Key from the TRMNL Dashboard. Or debug the incoming request to `/api/setup` to determine.
|
||||
1. Switch on the “Permit Auto-Join” toggle in the header. For that to work only one user can be registered.
|
||||
2. New devices on your local network will be detected and added automatically when connecting to the server.
|
||||
|
||||
✅ This is the easiest way to connect your devices with minimal effort.
|
||||
|
||||
##### Manually
|
||||
|
||||
1. Open the Devices page:
|
||||
👉 http://localhost:4567/devices
|
||||
2. Click “Add New Device”.
|
||||
3. Retrieve your TRMNL MAC Address and API Key:
|
||||
- You can grab the TRMNL Mac Address and API Key from the TRMNL Dashboard
|
||||
- Alternatively, debug incoming requests to /api/setup to determine them
|
||||
|
||||
### ⚙️ Configure Server for Device
|
||||
|
||||
#### 📌 Firmware Version 1.4.6 or Newer
|
||||
|
||||
* Setup device
|
||||
* After entering Wifi credentials, choose "Custom Server"
|
||||
* Point to the URL of your server
|
||||
|
||||
#### Firmware Older Than 1.4.6
|
||||
|
||||
If your device firmware is older than 1.4.6, you need to flash a new firmware version to point it to your server.
|
||||
|
||||
#### Flash Firmware to point Device to your server
|
||||
See this YouTube guide: [https://www.youtube.com/watch?v=3xehPW-PCOM](https://www.youtube.com/watch?v=3xehPW-PCOM)
|
||||
|
||||
#### Generate Screen
|
||||
### 🖥️ Generate Screens
|
||||
|
||||
* Edit resources/views/trmnl.blade.php
|
||||
#### 🎨 Blade View
|
||||
* Edit `resources/views/trmnl.blade.php`
|
||||
* Available Blade Components are listed here: [laravel-trmnl | Blade Components](https://github.com/bnussbau/laravel-trmnl/tree/main/resources/views/components)
|
||||
* To generate the screen, run
|
||||
|
||||
```bash
|
||||
php artisan trmnl:screen:generate
|
||||
```
|
||||
|
||||
#### Generate via API
|
||||
You can dynamically update screens by sending a POST request.
|
||||
|
||||
* Send a POST request to `/api/screen` with the following payload
|
||||
|
||||
##### Header
|
||||
|
||||
`Authorization` `Bearer <TOKEN>`
|
||||
|
||||
##### Body
|
||||
|
||||
```json
|
||||
{
|
||||
"markup": "<h1>Hello World</h1>"
|
||||
}
|
||||
```
|
||||
|
||||
Token can be retrieved under Plugins > API in the Web Interface.
|
||||
|
||||
#### Markup via Web Interface
|
||||
|
||||
1. Navigate to Plugins > Markup in the Web Interface.
|
||||
2. Enter your markup manually or select from the available templates.
|
||||
3. Save and apply the changes.
|
||||
|
||||
* Available Blade Components are listed here: [laravel-trmnl | Blade Components](https://github.com/bnussbau/laravel-trmnl/tree/main/resources/views/components)
|
||||
|
||||
#### 🛠️ Generate Screens Programmatically
|
||||
|
||||
You can fetch external data, process it, and generate screens dynamically.
|
||||
* Fetch data from an external source.
|
||||
* Either render it in a Blade view or directly insert markup.
|
||||
* Use Laravel’s scheduler to automate updates.
|
||||
|
||||
#### 📌 Example: Fetch Train Monitor Data
|
||||
|
||||
This example retrieves data from [trmnl-train-monitor](https://github.com/bnussbau/trmnl-train-monitor) and updates the screen periodically.
|
||||
|
||||
##### Step 1: Create a new Artisan Command
|
||||
|
||||
```bash
|
||||
php artisan make:command PluginTrainMonitorFetch
|
||||
```
|
||||
|
||||
##### Step 2: Edit PluginTrainMonitorFetch.php
|
||||
|
||||
```php
|
||||
class PluginTrainMonitorFetch extends Command
|
||||
{
|
||||
protected $signature = 'plugin:train:fetch';
|
||||
|
||||
protected $description = 'Command description';
|
||||
|
||||
public function handle(): void
|
||||
{
|
||||
$markup = Http::get('https://oebb.trmnl.yourserver.at/markup')->json('markup');
|
||||
GenerateScreenJob::dispatchSync(1, $markup);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
##### Step 3: Schedule the Command in console.php
|
||||
|
||||
```php
|
||||
Schedule::command('plugin:train:fetch')
|
||||
->everyFiveMinutes()
|
||||
->timezone('Europe/Vienna')
|
||||
->between('5:00', '18:00');
|
||||
```
|
||||
|
||||
This will automatically update the screen every 5 minutes between 5:00 AM and 6:00 PM local time.
|
||||
|
||||
### 🤝 Contribution
|
||||
Contributions are welcome! If you’d like to improve the project, follow these steps:
|
||||
|
||||
1. Open an Issue
|
||||
- Before submitting a pull request, create an issue to discuss your idea.
|
||||
- Clearly describe the feature or bug fix you want to work on.
|
||||
2. Fork the Repository & Create a Branch
|
||||
3. Make Your Changes & Add Tests
|
||||
- Ensure your code follows best practices.
|
||||
- Add Pest tests to cover your changes.
|
||||
4. Run Tests
|
||||
- `php artisan test`
|
||||
5. Submit a Pull Request (PR)
|
||||
- Push your branch and create a PR.
|
||||
- Provide a clear description of your changes.
|
||||
|
||||
🚀 Thank you for contributing! Every contribution helps improve the project.
|
||||
|
||||
### 🏗️ Roadmap
|
||||
|
||||
Here are some features and improvements that are open for contribution:
|
||||
|
||||
##### 🔌 Plugin System
|
||||
|
||||
- Enable configurable plugins via the Web Interface.
|
||||
- Ensure compatibility with the trmnl-laravel package.
|
||||
- Implement auto-discovery for plugins.
|
||||
|
||||
##### ⏳ Scheduling
|
||||
|
||||
- Move task scheduling from console.php to a Web Interface.
|
||||
- Allow users to configure custom schedule intervals.
|
||||
|
||||
##### 🖥️ “Native” Plugins
|
||||
- Add built-in plugins such as (as an example):
|
||||
- ☁️ Weather
|
||||
- 💬 Quotes
|
||||
- 🏡 Home Assistant integration
|
||||
- Provide Web UI controls to enable/disable plugins.
|
||||
|
||||
##### Improve Code Coverage
|
||||
|
||||
- Expand Pest tests to cover more functionality.
|
||||
- Increase code coverage (currently at 86.9%).
|
||||
|
||||
### License
|
||||
MIT
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue