ARDURAIL

ARDURAIL
Introduction
- Hardware options
Installation
Documentation
Tested Hardware

Introduction

This library allows you to create a digital Märklin(tm)-Motorola(tm) compatible signal for driving model-rail locomotives and track switches. You also need:

a booster (a kind of digital amplifier, see http://en.wikipedia.org/wiki/Digital_model_railway_control_systems#Booster)
some external controller (light pots, switches, buttons, ...) or
some external hard/software which speaks the Märklin(tm) P50-protocol over a serial interface (like [RocRail (http://wiki.rocrail.net) or [srcpd (http://srcpd.sourceforge.net/) in conjunction with the derived Ardurail_P50 class.

Supported protocols are:

M1: The first (old) Märklin(tm) Motorola(tm) I protocol (14 speedsteps, only function f0, no absolute direction switching)
M2: The original Märklin(tm) Motorola(tm) II protocol (14 speedsteps, functions f0,f1-f4)
M2_28_80A: Märklin(tm) Motorola(tm) II protocol (like MM2, 28 speedsteps)
M2_14_256A: Märklin(tm) Motorola(tm) II protocol (like MM2, 256 addresses)
M2_28_256A: Märklin(tm) Motorola(tm) II protocol (newer Märklin decoder) (like MM2, 28 speedsteps, 256 addresses)
Märklin(tm) Motorola(tm) for selenoids

This library claims to be an emulation of the Märklin(tm) 602x central unit in combination with the 605x Interface.

The library is tested on Arduino Uno and Arduino Mega 2560.

Hardware options

You need to reserve:

one digital pin for the digital signal (default pin 6)
(optional) one digital pin for the shortcut detection of the booster
(optional) one digital pin for go signalisation for the booster
(optional) four analog pins (default A0-A3, can be changed in Ardurail.h) for S88 usage.
Timer2 interrupt is used!

Installation

To use it, download the library, unzip it, and place the resulting folder in the hardware/libraries directory of your Arduino application directory. Then restart Arduino.

Example 1: Simple driving a locomotive

#include "Ardurail.h"

#undef USE_S88

Ardurail MM;

#define KOeF 23                      // the locomotive has address 23

void setup(void)
{
  Serial.begin(9600);                // for debugging output
  MM.init(6);                        // use pin 6 and no shortcut detection
  MM.add_loco(KOeF,MM2);
  MM.set_power(true);
}

void loop(void)
{
  Serial.println("Waiting 5 secs for starting...");
  delay(5000);

  // switch light on
  MM.set_function(KOeF,0,true);     // lights on
  MM.commit(KOeF);
  delay(1000);

  // switch light off
  MM.set_function(KOeF,0,false);    // lights off
  MM.commit(KOeF);
  delay(1000);

  MM.set_dir(KOeF, true);           // forward
  MM.set_function(KOeF,0, true);    // lights on
  MM.set_speed(KOeF, 6);            // speed 6
  MM.commit(KOeF);
  delay(5000);

  MM.set_speed(KOeF, 0);            // speed 0
  MM.commit(KOeF);
  delay(1000);

  MM.set_function(KOeF,0, true);    // lights on
  MM.commit(KOeF);
}

Example 2: P50 compatible central station

#include "Ardurail_P50.h"

#define MAX_S88 2               // maximum of 2 S88 modules installed

Ardurail_P50 P50_CENTRAL;

void setup(void)
{
  P50_CENTRAL.init(6,7,8);      // use pin 6 for digital signal,
                                // pin 7 as shortcut detection and
                                // pin 8 as "GO" signal
}

void loop(void)
{
  P50_CENTRAL.p50();            // That's all... really nice!!!
}

Compile time options

The S88 bus is enabled by default on pins A0-A3. If you don't want to use it you can disable it using

#undef USE_S88

The default is also to use the maximum of 31 modules. This means that memory for all 31 modules is reserved - even if you have only one module connected! You should change this using

#define MAX_S88 <YOUR_NUMBER_OF_DEVICES>

Documentation

Constructor

Ardurail()

Initializes a new Ardurail object for direct using with the object methods. You have to include Ardurail.h and can only use one Ardurail instance per sketch.

Ardurail_P50()

Initializes a new Ardurail object for mainly using the P50()-method. You have to include Ardurail_P50.h and can only use one Ardurail instance per sketch.

Control Methods

void init(byte pin)

Sets the pin for the digital signal. The init()-method has to be called once inside the setup()-funtcion. This method should be used if the booster has no shortcut-detection.

void init(byte pin,byte shortcut_pin,byte go_signal_pin)

Set the pin for the digital signal and also the pins for the shortcut-detection.

void set_power(boolean power)

Enables the creation of the output signal on the desired pin for the digital signal.

boolean get_power(void)

Get the status if a digital signal is generated or not.

void set_go(void)

Normaly not used in user programs, because the library should handle this inside. This sets the go-signal for the booster to HIGH. This method can change to be private in further versions of Ardurail.

void set_stop(void)

Normaly not used in user programs, because the library should handle this inside. This sets the go-signal for the booster to LOW. This method can change to be private in further versions of Ardurail.

boolean get_shortcut(void)

Reads the status of the boosters shortcut-detection.

Locomotive methods

void add_loco(byte addr)

Adds a locomotive by address to the internal refresh cycle. This is normaly not necessary because the locomotive is added by default when first accessing it. The used protocol is Motorola(tm) II by default.

void add_loco(byte addr,byte protocol)

Adds a locomotive by address to the internal refresh cycle. This method is needed if the protocol for the locomotive should something else of the default protocol. See "Supported protocols" at the beginning of this document.

void set_speed(byte addr, byte speed)

Sets the speed for the given address. This method does not control if the given speed is in range of the used protocol!

byte get_speed(byte addr)

Gets the last written speed for the given address.

void set_dir(byte addr, boolean direction)

Sets the direction for the given address. Warning! For protocol M1 the direction information is not absolute due to protocol limitations!

boolean get_dir(byte addr)

Gets the current direction for the given address. Warning! For protocol M1 the direction information is not absolute due to protocol limitations!

void change_dir(byte addr)

Changes the current direction for the given address.

void set_function(byte addr, byte function, boolean state)

The function f0..f4 is set to the given state. Note: For protocol M1 function f1..f4 won't do anything due to protocol limitations.

boolean get_function(byte addr, byte function_nr)

Reports the state of the functions f0..f4. Note: For protocol M1 function f1..f4 won't return anything usable to protocol limitations.

void emergency_stop(byte addr)

Stops the locomotive given address without brake retardation.

Selenoid methods

void set_track(byte addr, byte sub_addr, boolean state)

Switches a selenoid at the given address/subaddress to the given state.

Common methods

void commit(void)

After setting values with locomotive methods a commit() is necessary. This method generates a commit for all used locomotives in the internal refresh cycle. This means that a changed value of a locomotive may be transmitted with a few milliseconds delay. When ever possible use void commit(byte addr) for only one address.

void commit(byte addr)

After setting values with locomotive methods a commit() is necessary. This method commit the values for only one address and tries to transfer the data immediately.

void S88(byte numberofdevices)

This method must be called at a regular basis for getting the state of the repeater connected to the S88 bus. The values of the repeaters are transmitted via serial port at 2400 bps. If you do not want to use the S88 bus you can add #undef USE_S88 at the beginning of your sketch.

The default pins for the S88 bus are:
S88_Data A0
S88_Clock A1
S88_PS A2
S88_Reset A3

You should set the numberofdevices as low as possible because it takes much more time for reading more devices than really connected.

When using Ardurail_P50 the S88 bus is enabled an used inside the P50() method.

Tested Hardware

Decoder for locomotives

Märklin 60760
Märklin 60901
Märklin 519090
ESU LokPilot V3.0 M4 61601
ESU LokSound V4.0 M4 64446
Kühn T145
Kühn N025
Uhlenbrock AnDi (w/o light switching with f0)
Uhlenbrock 75200
Tams LD-W-1

Decoder for track switches

Märklin k 83 6083
Märklin 74460
Viessmann 5211
Viessmann 5231

Booster

Märklin 6015
Littfinski DatenTechnik DigitalBooster DB-2
Tams B-2 (RS-232 I/O)

Repeater modules

Märklin S88 6088
Littfinski DatenTechnik RM-88-N

Last edit: janvonnebenan 2013-08-02