mirror of
https://github.com/daniviga/django-ram.git
synced 2025-08-04 13:17:50 +02:00
189 lines
6.2 KiB
Markdown
189 lines
6.2 KiB
Markdown
# Django Railroad Assets Manager (django-ram)
|
|
|
|
[](https://github.com/daniviga/django-rma/actions/workflows/django.yml)
|
|
|
|
|
|
|
|
A `jff` (just for fun) project that aims to create a
|
|
model railroad assets manager that allows to:
|
|
|
|
- Create a database of assets (model trains) and consists with their metadata
|
|
- Manage the database via a simple but rationale backoffice
|
|
- Expose main data via an HTML interface to show how beautiful is your collection
|
|
to the outside world
|
|
- Act as a DCC++ EX REST API gateway to control assets remotely via DCC.
|
|
By anyone, if you'd like (seriously?).
|
|
|
|
## Preface
|
|
|
|
**This project is work in progress**. It is intended for fun only and
|
|
it has been developed with a commitment of few minutes a day;
|
|
it lacks any kind of documentation, code review, architectural review,
|
|
security assesment, pentest, ISO certification, etc.
|
|
|
|
This project probably doesn't match your needs nor expectations. Be aware.
|
|
|
|
> [!CAUTION]
|
|
> Your model train may catch fire while using this software.
|
|
|
|
Check out [my own instance](https://daniele.mynarrowgauge.org).
|
|
|
|
## Components
|
|
|
|
Project is based on the following technologies and components:
|
|
|
|
- [Django](https://www.djangoproject.com/): *the* web framework
|
|
- [Django REST](https://www.django-rest-framework.org/): API for the lazy
|
|
- [Bootstrap](https://getbootstrap.com/): for the web frontend
|
|
- [Arduino](https://arduino.cc): DCC hardware; you must get one, really
|
|
- [DCC++ EX Command Station](https://dcc-ex.com/): DCC firmware; an amazing project
|
|
- [DCC++ EX WebThrottle](https://github.com/DCC-EX/WebThrottle-EX): the DCC++ EX web throttle, a slightly modified version
|
|
|
|
It has been developed with:
|
|
|
|
- [vim](https://www.vim.org/): because it rocks
|
|
- [arduino-cli](https://github.com/arduino/arduino-cli/): a mouse? What the heck?
|
|
- [vim-arduino](https://github.com/stevearc/vim-arduino): another IDE? No thanks
|
|
- [podman](https://podman.io/): because containers are fancy
|
|
- [QEMU (avr)](https://qemu-project.gitlab.io/qemu/system/target-avr.html): QEMU can even make toast!
|
|
|
|
## Future developments
|
|
|
|
### Live assets KPI collection
|
|
|
|
Realtime data usage is collected via a daemon connected over TCP to the Commandstation-EX and recorded for every asset with a DCC address.
|
|
|
|
### Asset lifecycle
|
|
|
|
Data is collected to compute the asset usage and then the wear level of its components (eg. the engine).
|
|
|
|
### Required mainentance forecast
|
|
|
|
Eventually data is used to "forecast" any required maintenance, like for example the replacement of carbon brushes, gear and motor oiling.
|
|
|
|
## Requirements
|
|
|
|
- Python 3.11+
|
|
- A USB port when running Arduino hardware (and adaptors if you have a Mac)
|
|
|
|
## Web portal installation
|
|
|
|
### Using containers
|
|
|
|
Do it yourself, otherwise, raise a request :)
|
|
|
|
### Manual installation
|
|
|
|
Setup your virtualenv
|
|
|
|
```bash
|
|
$ python3 -m venv venv
|
|
$ source ./venv/bin/activate
|
|
```
|
|
|
|
Install dependencies
|
|
|
|
```bash
|
|
$ pip install -r requirements.txt
|
|
# Development stuff
|
|
$ pip install -r requirements-dev.txt
|
|
```
|
|
|
|
Bootstrap Django
|
|
|
|
```bash
|
|
$ cd ram
|
|
$ python manage.py migrate
|
|
$ python manage.py createsuperuser
|
|
```
|
|
|
|
Run Django
|
|
|
|
```bash
|
|
$ python manage.py runserver
|
|
```
|
|
|
|
Browse to `http://localhost:8000`
|
|
|
|
|
|
## DCC++ EX connector
|
|
|
|
The DCC++ EX connector exposes an Arduino board running DCC++ EX Command Station,
|
|
connected via serial port, to the network, allowing commands to be sent via a
|
|
TCP socket. A response generated by the DCC++ EX board is sent to all connected clients,
|
|
providing synchronization between multiple clients (eg. multiple JMRI instances).
|
|
|
|
Its use is not needed when running DCC++ EX from a [WiFi](https://dcc-ex.com/get-started/wifi-setup.html) capable board, like when
|
|
using an ESP8266 module, a [Mega+WiFi board](https://dcc-ex.com/reference/hardware/microcontrollers/wifi-mega.html), or an
|
|
[ESP32](https://dcc-ex.com/reference/hardware/microcontrollers/esp32.html) (recommended).
|
|
|
|
### Manual setup
|
|
|
|
You'll need [namp-ncat](https://nmap.org/ncat/) , and `stty` to setup the serial port.
|
|
|
|
> [!IMPORTANT]
|
|
> Other variants of `nc` or `ncat` may not work as expected.
|
|
|
|
Then you can run the following commands:
|
|
|
|
```bash
|
|
$ stty -F /dev/ttyACM0 -echo 115200
|
|
$ ncat -n -k -l 2560 </dev/ttyACM0 >/dev/ttyACM0
|
|
```
|
|
|
|
> [!IMPORTANT]
|
|
> You'll might need to change the serial port (`/dev/ttyACM0`) to match your board.
|
|
|
|
> [!NOTE]
|
|
> Your user will also need access to the device file, so you might need to add it to the `dialout` group.
|
|
|
|
|
|
### Using containers
|
|
|
|
```bash
|
|
$ cd connector
|
|
$ podman build -t dcc/connector .
|
|
$ podman run -d --group-add keep-groups --device /dev/ttyACM0:/dev/arduino -p 2560:2560 dcc/connector
|
|
```
|
|
|
|
### Test with a simulator
|
|
|
|
A [QEMU AVR based simulator](daemons/simulator/README.md) running DCC++ EX is bundled togheter with the connector
|
|
into a container. To run it:
|
|
|
|
```bash
|
|
$ cd connector/simulator
|
|
$ podman build -t dcc/connector:sim .
|
|
$ podman run --init --cpus 0.1 -d -p 2560:2560 dcc/connector:sim
|
|
```
|
|
|
|
> [!WARNING]
|
|
> The simulator is intended for light development and testing purposes only and far from being a complete replacement for a real hardware.
|
|
|
|
## Screenshots
|
|
|
|
### Frontend
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
#### Dark mode
|
|
|
|
|
|
|
|
---
|
|
|
|
### Backoffice
|
|
|
|
|
|
---
|
|
|
|
---
|
|
|
|
|
|
### Rest API
|
|
|
|
|