KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #developer-tools #ai-agent #claude-code #codex #typescript #ai-agents #deepseek-harness #mcp #cli #rust

OpenMRNLite

★ 20 Open GitHub ↗

Arduino library for the OpenMRN core using the simplified drivers and programming model of the Arduino environment.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# OpenMRNLite Arduino Library
This library implements network protocols for model railroading. In the center
is the OpenLCB protocol suite (Open Layout Control Bus), which has been adopted
by the NMRA and referenced as LCC (Layout Command Control): a high-performance
and highly extensible communications protocol suite for model railroad
control. OpenMRN is one of the most extensible implementation of this protocol
suite. This Lite version has been adapted to work with the programming model and
drivers of the Arduino ecosystem.

## Supported platforms/architectures
At this time the only supported platforms are:

* ESP32 using the [arduino-esp32](https://github.com/espressif/arduino-esp32)
core as the underlying stack, version 1.0.1 or 1.0.2-rc2.
* STM32, but no examples are available at this time.

Additional platforms may be added in the future.

## Where to get the library

- by using the Arduino Library Manager to download a released version from the
  global Arduino index.
- by downloading a released source code ZIP file from GitHub
  (https://github.com/openmrn/OpenMRNLite/releases) and importing that ZIP file
  into the Arduino UI.
- by exporting directly from the OpenMRN source tree (under linux also symlinks
  are supported)

# ESP32 supported hardware
At this time the ESP32 supports both WiFi and hardware CAN adapters. Almost
all variants of the ESP32 boards can be used except the ESP32-SOLO-1 based
boards are not supported by [arduino-esp32](https://github.com/espressif/arduino-esp32).
For the hardware CAN support they will require two additional GPIO pins. WiFi
does not require any additional GPIO pins.

## ESP32 WiFi support
The Esp32WiFiManager should be used to manage the ESP32's WiFi connection to
the SSID, create a Soft AP (max of 4 clients connected to it) or to create both
a Soft AP and connect to an SSID. See the ESP32IOBoard example for how to use
the Esp32WiFiManager for how to connect to an SSID and have it automatically
establish an uplink to a GridConnect based TCP/IP Hub. Additional configuration
parameters can be configured via the CDI interface.

## Using an SD card for configuration data
When using an SD card for storage of the OpenMRN configuration data it is
recommended to use an AutoSyncFileFlow to ensure the OpenMRN configuration
data is persisted to the SD card. The default configuration of the SD virtual
file system driver is to use a 512 byte per-file cache and only persist
on-demand or when reading/writing outside this cached space. The
AutoSyncFileFlow will ensure the configuration file is synchronized to the SD
card on a regular basis. The SD VFS driver will check that the file has pending
changes before synchronizing them to the SD card and when no changes are
necessary no action is taken by the synchronization call.

Note that the Arduino-esp32 SPIFFS library and the underlying SPIFFS VFS driver
does use a cache but the AutoSyncFileFlow is not necessary due to the nature of
the SPIFFS file system (monolithic blob containing all files concatenated).

## ESP32 Hardware CAN support
The ESP32 has a built in CAN controller and needs an external CAN transceiver
only. There are two types of transceivers recommended by Espressif:
1. SN65HVD23x, also known as VP230, this is a 3.3V transceiver that typically
is only available as a breakout board with on board termination resistor.
2. MCP2551, this is a 5V transceiver that is available as a DIP-8, SMD or as a
breakout board. This does not include a termination resistor and for this
reason is preferred over the SN65HVD23x boards.

Connecting the CAN transceiver to the ESP32 requires four connections:
1. 3v3 or 5v to the VCC/VDD pin on the transceiver. Make sure to use the right
voltage for the transceiver.
2. GND to the GND pin on the transceiver.
3. GPIO for RX to the RX pin on the transceiver. This can be any unused GPIO
pin. Note, if you are using a 5V transceiver (ie: MCP2551) it is recommended to
use a 1k or higher resistor between the RX pin on the transceiver and the ESP32
GPIO pin to prevent damage to the ESP32.
4. GPIO for TX to the TX pin on the transceiver. This pin must be usable as an
output pin, GPIO 34-39 on the ESP32 are input only.

If you are using the MCP2551 transceiver and the ESP32 will be at the end of the
CAN bus, you should include a 120ohm resistor across the H and L lines to
terminate the CAN bus. This is necessary on the two ends of the CAN-bus.

## Powering the ESP32
It is not recommended to directly connect the CAN bus `PWR_POS` (7) to the VIN
pin on the ESP32 as the CAN bus will not supply the necessary current for the
ESP32 and the PWR_POS can be up to 15V DC which is more than the power
regulator on most ESP32 boards can handle. For these reasons, a DC-DC
step-down / buck converter is required to bring the voltage down to 3.3V DC or
5V DC before connecting it to the ESP32 VIN pin.

For standalone power supply it should be a regulated 3.3V DC or 5V DC 750mA
power supply. If multiple ESP32 devices will be supplied by this power supply
the amperage may need to be higher.

Some ESP32 boards may not have a pin marked as VIN, in these cases the VIN pin
would be either 5V or 3v3 depending on the voltage provided by the step-down /
buck converter. Some boards also have a BAT/VBAT pin, this is typically a 3.3V
DC pin. Some boards will have a pin marked USB, this is typically a 5V DC pin.
Be sure to consult the specification sheet for the ESP32 board you are using
before supplying power to it from the CAN bus or a standalone power supply.

The ESP32 devices will detect under current situations and will shutdown and
restart automatically and include the message "ESP_RST_BROWNOUT" as part of the
start-up messages.

## GPIO restricted and bootstrapping pins
There are a handful of GPIO pins on the ESP32 that have some restrictions on
their use.

GPIO 6-11 are connected to the on-board flash chip and can not be used by
application code.

IF GPIO 0 and 2 are LOW (GND) at the time the ESP32 is powered-up it will
enter "code download mode," this is used as part of the code flashing process.
GPIO 0 has an internal pull-up resistor and GPIO 2 has an internal pull-down
resistor. After power-up these pins can safely be used.

GPIO 12 (MTDI) controls the VDD_SDIO voltage, there is an internal pull-down
resistor on this pin. This pin *MUST* not be held HIGH at power-up otherwise
damage to the ESP32 flash is likely. After power-up this pin can safely be used.

GPIO 15 (MTDO) controls the debug printing on UART0 during power-up, there is an
internal pull-up resistor (enables debug output). This pin is also used in
conjunction with GPIO 5 to set the SDIO Slave timing. GPIO 5 also has an
internal pull-up resistor. After power-up both GPIO 5 and 15 can safely be
used.

Additional details on the GPIO pin restrictions can be found in this
(document)[https://www.espressif.com/sites/default/files/documentation/esp32-wroom-32_datasheet_en.pdf]

OpenMRNLite

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README