README.md

Django Railroad Assets Manager (django-ram)

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.

Components

Project is based on the following technologies and components:

• Django: the web framework
• Django REST: API for the lazy
• Bootstrap: for the web frontend
• Arduino: DCC hardware; you must get one, really
• DCC++ EX Command Station: DCC firmware; an amazing project
• DCC++ EX WebThrottle: the DCC++ EX web throttle, a slightly modified version

It has been developed with:

• vim: because it rocks
• arduino-cli: a mouse? What the heck?
• vim-arduino: another IDE? No thanks
• podman: because containers are fancy
• QEMU (avr): QEMU can even make toast!

Requirements

• Python 3.11+
• A USB port when running Arduino hardware (and adaptors if you have a Mac)

Web portal installation

Using containers

coming soon

Manual installation

Setup your virtualenv

$ python3 -m venv venv
$ source ./venv/bin/activate

Install dependencies

$ pip install -r requirements.txt
# Development stuff
$ pip install -r requirements-dev.txt

Bootstrap Django

$ cd ram
$ python manage.py migrate
$ python manage.py createsuperuser

Run Django

$ 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 capable board, like when using an ESP8266 module, a Mega+WiFi board, or an ESP32 (recommended).

Manual setup

You'll need namp-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:

$ 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

$ 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 running DCC++ EX is bundled togheter with the connector into a container. To run it:

$ 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