dcc-ex / dcc-ex.github.io Goto Github PK

@cjmayo, @Condo-Colin Making this an issue instead of a thread in the PR since when you close it, it doesn't make sense to keep a conversation going there. I don't fully understand autosectionlabel_prefix_document. Right now, every title is a link which for the first "make github" command you will get a lot of "duplicate label" warnings. But they go away until some other action happens. Not sure what that is. From the quick read, it looks like autosection label puts a prefix on the front of every title automatically? Or do you have to do it? Ex: hardware:how to, software:how to. Perhaps it is manualy, which is why you added this:

"If you agree I can probably add a commit here that adds the document to these :doc: and :ref: targets (not something I want to do if it isn't going to be used."

I think we should use it and make that a standard just like we have for which character underline is use for which heading, how we use "note", etc.

Write some basics about how to safely interface a current sensor with either proportional current or proportional voltage to an ADC pin.

There is a way to add google analytics to sphinx, @FrightRisk can we possibly get an analytics tracking ID through the team email?

https://discord.com/channels/713189617066836079/873794422993727568/900129225594515507

And Rico's diagram etc.

A bit more feedback on the SS49E Linear Hall Effect transducer for the general enlightenment. I measured the thresholds on a Mega's GPIO digital pins, and I get a transition to '1' state on the digital input when the signal goes up above 516 as read on analogue pin A5 (50.4% of max), and a transition to '0' state when it drops below 473 (46.2% of max). Compare this to the 2560 datasheet, figures 32-26 and 32-27, which shows threshold voltages of ~2.6V (52%) and ~2.3V (46%) at 5V supply.

I hooked an SS49E up to my Mega, to a digital input. It's also connected to analogue pin A5 which, when the transducer is quiescent (no magnetic field), reads 519. This is slightly higher than half-scale of 512, and just over the GPIO input pin threshold of 516 I measured earlier - by 14mV, very marginal! The digital input is triggered (<Q ...> message) when a button-magnet is placed about 1cm away, and clears when the magnet moves about 2cm away.

If I configure the digital input with pullup, there is very little difference. Pin A5 reads 525 when the transducer is quiescent (an increase of about 29mV caused by the pull-up). The magnet still triggers the input when about 1cm away. With pull-up, at 0.5cm, pin A5 reads about 350 (~1.7V), and when closer, it goes down to 250 (~1.2V), even with the pull-up.

So my experience is that transducer output when quiescent is only just over the threshold of the digital input without pullups, but with pull-up the margin is increased and the sensor should be more reliable.

These are the kind of support questions we need examples and details for, especially with regard to JMRI integration.

"Where do I define my servo?"

"Show me an example sketch on a single servo for a turnout used in conjunction with jmri and a PCA9685."

"How would you calibrate the throw for a servo?
I currently am using little wicket sketch for servos.
But am curious as to the dccex automation programming."

It'd be handy to have a page dedicated page to capture the various tips and tricks resulting from questions in Discord, especially to get Chris' ideas out from his head in a way that he doesn't have to keep repeating himself and can get on with what he needs to.

Here's some copy/pasted notes from various conversations where Chris' key tip of thinking from the engineer's or train's perspective when designing automation sequences:

Yes you're right on the money....
It's the difference between looking at a layout from above and trying to coordinate everything... and driving a route from the drivers perspective.
Using point sensors has always seemed to me to be so much more powerful than block occupancy... "I know where I'm going and when I get to sensor 123 I know i must reserve blocks 6 and 9"

It always struck me that block occupancy was not a great place to start ... because I came across so many automation things it didn't help with.
Reversing into a siding for example. Just because a block is empty doesn't mean you can drive into it because sometimes a block will physically cross over 1 or more others or you may have a blocked exit with a train coming the other way.
I think, for the most part, point sensors seem more useable for automation and block sensors more suitable for mimic panels.
(especially if you think automation from the drivers perspective)
Now I do have some nags about point sensors... it just seems such a pain that one needs so much wire and cheap IR sensors suffer from sunlight etc. Now what would be so super would be a tiny sensor that looked like the real thing and sat between the tracks, ran on track power, and used bluetooth or something to broadcast its events to a central unit. Alternatively the video-cam sensing would be really cool!

What about a script that uses an enter and exit sensor but you need to know which direction the train is going? Is it as simple as just having 2 sequences? AT sensor 1 do something and stop doing it AFTER sensor 2 triggers and resets. But if you go the other way, now sensor 2 triggers the action and you wait for 1 to trigger or to trigger and then reset to stop the action?

UKBloke (AKA Chris) — 02/18/2022
That's a problem because you are not in a position to enter a section like that just because it's empty... because a train coming the other way in the next block will be blocking yoyr exit...
To handle a situation like this you need to reserve well ahead ... ie before you block the exit for a train coming he other way.
This means you will know which way things are happening in the block in question BEFORE any train can enter it.
This is easy to do if your scripts run from the drivers perspective... but a PITA if you run from the signalman perspective.

What I mean is that its POSSIBLE to create a sequence to take any train from somewhere to somewhere and then send any particular loco on that journey... BUT in reality we don't tend to model a real railway with 20 identical trains running up and down a main line... we model a variety of trains and each one has its characteristics like sounds or realistic speeds, or loco direction or train length or rolling-stock types.

So rather than creating generic routes, think from the trains perspective like .....
This is a passenger train with carriage lights and a diesel sound loco with a XXX decoder which requires switching on with F4 and has a fancy station announcement on F19.
It will sit in siding A quietly until xxx happens (may be a random wait) and then it will warm up the engine and move to platform B where it will stop, turn on the carriage lights one by one and make an announcement. 60 seconds later it will set off at speed blah blah to station C where it will stop for 30 seconds and than contiunue.... At some point (random or switch) it will switch off the lights and return to its siding and shut down.

Autostart starts a process or task... there is an implied autostart at the beginning of the script so everything down to the first DONE is performed in order at startup.

Add HTML list, plus:
ATTIMEOUT
IFTIMEOUT
ELSE

There's a whole heap of info captured in the CommandStation repo Wiki, which should really be on the public website instead, with the Wiki simply directing to the public website which should be the single source of truth.

Need to review all the existing Wiki content, make sure it's captured in the public website, and then clean it up.

• more long Amazon links here:
  https://dcc-ex.com/reference/tools/serial-monitor.html#otg-cable

• broken image links
  https://dcc-ex.com/advanced-setup/wifi-config.html#ap-mode

See Discord convo in #motor-shields from 26 Jan '22.

From Ash:
Understanding the R -- what resistor to use. In this diagram, it looks like 10k/1k is a voltage divider. And reduces the voltage to pin A0 ~10%. But with IBT_2, the parallel resistance is 3.3k, so 3.3k/1k. @haba can explain my confusion about what value to use for R2. I think R2 is there to limit current; we have already added R1 to adjust voltage. Perhaps a low value for R2 would be better, e.g. 100 ohms.

The Mega+WiFi unit is an Arduino Mega clone design with an ESP8266 WiFi chip on one board. Since they are hard-wired together, they needed to have a way for you to be able to use both devices separately. So the TXRX01/03 switch needs to be there so you can choose which serial port on the Mega, the ESP connects to. We want 3. This is the equivalent of you using 2 jumpers on a discrete ESP-8266 board and connecting them to serial 3 on a regular Mega.
The dip switches are there because you need to program 2 different devices and you only have one USB port. They could have used jumpers, but that would be even more confusing and have dangling wires. So you flip the switches one way so that the USB port on the Mega is rewired on the board to connect to the ESP instead. You then have to switch it back so that you are talking to the Mega. Once you program the ESP chip, you don't have to mess with the switches again unless you need to update the ESP.

Issues with use on Mac & Linux?
Possible issues using on Windows?

From @Springlake:
Before the release I have some documentation concerns.

1. I notice several cmds in RMFTMacros.h are not in the reference documentation such as POWEROFF, SERIAL(msg) +1,2,3, SERVO2(id,position,duration).
   2.ALIAS(“name”, value) * See note! —> name should not have quotes around it. (I mentioned this before)
   Mike

Details:
l : lower case letter "L"
CABID: The loco number which is controlled
SLOTID: Ignore this.
SPEED: Speed in DCC encoded format. 0 stop, 1 emergency stop, 2 to 127 speed steps, 128 stop, 129 emergency stop, 130-255 speed steps. 128 to 255 is the other direction compared to 0 to 127
FUNCTIONS: You need to think binary.

Should this be added to a "Contributing" or "Devs" page?

From Chris on Discord:

Some things to watch out for in porting code for Teensy and others..

1. the length of the int data type can change between processors.

2. Wifi can be very different.... our current Wifi code does NOT use the standard libraries because they were unsuitable or inefficient or RAM gobblers, interrupt blockers, or simply didn't work. Where a processor needs to use its own wifi libraries, then its necessary to provide the hooks to that (probably using something similar to our Ethernet interface code as a model) and use compiler provided CPU type #defines to automatically choose which code to compile.

3. Our DCC Waveform generator requires a single interrupt and may operate in high-accuracy mode if the CPU supports PWM on the appropriate pins from the timer. (These pins differ even between Uno and Mega) In high accuracy mode, the waveform changes are prepared in advance but triggered by the hardware. If the configuration chooses pins that can't do that, then the pins are manipulated directly in the software interrupt which may have been delayed by timer ticks, Serial traffic or analogReads.

4. timer interrupot settings and other CPU specific tricks like reading a cpu-identity are all in DCCTimer but that file has become messy as more and more CPUs are supported. I plan to separate that again so that there will be different versions compiled for different CPUs.

5. we use FLASH,FSH, GETFLASH, GETFLASHW macros to refer to PROGMEM, FlashStringHelper, pgm_read_byte etc because we found some runtimes did not correctly port the uno/mega code to processors that have a linear addressing architecture so we had to adjust the macros on an architecture choice.

Suggestions & Edits; Sorting EXRAIL Commands and adding /slash
from
EXRAIL Functions Description
<D EXRAIL ON|OFF(addr,subaddr)>


</>
</ ROUTES>
</ START [loco_addr] route_id>
</ KILL task_id>
.>/ RESERVE block_id<
</ FREE block_id>
</ LATCH sensor_id>
</ UNLATCH sensor_id>

To

EXRAIL Functions Description
<D EXRAIL ON|OFF(addr,subaddr)>


</ START [loco_addr] route_id>
</>
</ KILL task_id>
</ RESERVE block_id>
</ FREE block_id>
</ LATCH sensor_id>
</ UNLATCH sensor_id>
</ ROUTES> //Under Development with a future JMRI integration release

add /slash to /PAUSE & /RESUME
change from > RESERVE block_id< to

Also search for and replace the following;
'Seria2' with 'Serial2'
'Disconnect prog track from main' with 'Disconnect Prog track from Main'
'command Station' with 'Command Station'
'logo' with 'loco'
'THROW( id )' with 'THROW( turnout_id )'

Add to EXRAIL Command References page missing command
Reboot the Command Station (edited)

Write a little more clearly somewhere that the signal pin is the DIR pin and not as usual the PWM pin.

This will allow text wrapping in browsers, to show all/extra detail for each command.
Another column may need to be added for expected inputs/outputs?

In Various techniques section at end
"Use the ALIAS() command in your script file. This must come BEFORE the EXRAIL command."
is no longer valid and should be something like
"Use the ALIAS() command in your script file. Can go anywhere in the script."

Note that EXRAIL/ENDEXRAIL is no longer required.

I think this mostly applies to layouts using boosters, but we need to make sure users are using floating power supplies, not grounded supplies. If they start adding boosters, they could blow something up really fast (TM).

See https://dccwiki.com/Grounds

Add clickable pins to take you to another page or popup for each pin.
Find where to put this on the web page.

https://dcc-ex.com/reference/hardware/motor-boards.html#yfrobot-l298p-motor-shield

Do these all have solder jumper pads on pins A0 & A1? On reverse of board.

From Springlake:
There are several places where the cmds are discussed. In
Reference » DCC++ EX Command Reference Commands
Reference » DCC++ EX Command Summary Commands
Reference » Diagnostics Command
The first 2 have most of the cmds, the last one seems to only have the original cmds from version 3.0 but has its own TOC entry.

Maybe eliminate the 3rd section entirely, but keep the TOC entry on the left side of the web page but have it point to
Reference » DCC++ EX Command Reference Commands
Also all references are missing the exrail cmd
<D EXRAIL ON|OFF> Turns on/off diagnostic traces for EX-RAIL events

KC:
USB Serial0 comm for Firmware updates, and Mega+ESP WiFi Combo Board defaults to Serial3 Tx Rx for WiFi, Leaving Serial1 & Serial2 for User options.
Plus the shortest wire from a MakerFab WiFI Shield and Mega WiFi TxRx would also be the Serial3 pins.

From Chris:

To do pin pulse turnouts with exrail do this:

To create a turnout on pins 20,21 use a PIN_TURNOUT with an id of 20 but a pin of 0.
This will appear as a turnout to throttles etc but will not change pin 0 because the hal protects that.

Then you can use ON event handlers like this

ONCLOSE (20)
SET(20) DELAY(250) RESET(20) DONE

ONTHROW(20)
SET(21) DELAY(250) RESET(21)
DONE

From Haba:

Start with a delay of say 25.
But if this is a 298N, you first need to set DIR and then pulse the enable.

ONCLOSE(20)
RESET(DIR)
SET(ENABLE) DELAY(25) RESET(ENABLE)
DONE

ONTHROW(20)
SET(DIR)
SET(ENABLE) DELAY(25) RESET(ENABLE)
DONE

For example:

#define KATOTURNOUT(t,p1,p2)
ONCLOSE(t)
RESET(p1)
SET(p2)DELAY(25)RESET(p2)
DONE
ONTHROW(t)
RESET(p2)
SET(p1)DELAY(25)RESET(p1)
DONE

and use as
KATOTURNOUT(20,33,35)
KATOTURNOUT(21,37,39)

@ukbloke (AKA Chris) Correct???

We are using networking primarily for allowing direct connection from a Throttle to the Command Station to avoid the need for any other software. Some people in the past connected the CS to JMRI via the network instead of using a USB Cable from a Raspberry Pi or some other computer. Address the issues in doing this.

notes
https://discord.com/channels/713189617066836079/720107530176561164/907147694194163743 and https://discord.com/channels/713189617066836079/724648686214447115/890288265243021353 and https://discord.com/channels/713189617066836079/720107530176561164/890326441064038440

WiFi Connection Sequence

Soliciting comments, answers, clarfications, and corrections.

config.h has the following defines we can use for WiFi:

WIFI_SSID "your network name"  // SSID of the router for Station Mode
WIFI_PASSWORD "your network password" // Password of the router for Station Mode
WIFI_MAC                                        // Mac address you wish to assign to the ESP8266
WIFI_IP                                            // If defined, the static IP address, if not DHCP assigns an address
WIFI_PORT                                      // The port we connect to
WIFI_BAUD                                     // connection speed for ESP8266. USB baud must be set to match
WIFI_AP_NAME                               // ????? Is this the "hostname"?
WIFI_USE_SOFTWARE_SERIAL       // for softwareSerial Setup
WIFI_SERIAL_RX                             // for softwareSerial setup
WIFI_SERIAL_TX                             // for softwareSerial setup

///// Question: aren't the strings, "your network name" and "your network password" a lot of bytes lost in flash?

///// Question: what does the "first check" do? What "data may be in the pipeline"?

///// Question: If you "shortcut the setup", then how do you change settings? For example, my AP name didn't change change when we changed the software and added the DCCEX_ab48uc8 identifier. I uploaded new firmware, but since it sees I have a setup, it ignores everything and moves past all the setup. We at least need good docs and tech support checklists here because you could get stumped as to why a change isn't being accepted. Must we do AT+RST or something more?

///// Question: What about saving settings in EEPROM as was posted on Discord?

///// Question: How does softwareSerial impact this?

1. Activate the first serial port (Serial1) and set its speed to WIFI_BAUD. Check to see if we get a response from the WiFi hardware

2. If we get a response, ???????? what happens?

3. If there is no response, try Serial2 and if still no response, try serial3

4. If no response after serial3, ?????? What happens?

5. If we get a response, set the WiFi hardware to station mode and check to see if it has been configured by looking at the WIFI_PASSWORD string to see if the defalt, "your network " is still in the password setting.

6. If there is no configuration, then check to see if it may have already been configured and is using settings saved in the WiFi device to try and connect to a previous network. We do this by waiting 8 seconds and then sending the command to check for an IP address.

7. We then check to see if there is a MAC? And if we have one? What if we don't?

8. If there IS a valid IP address already we skip to 10

9. If there is NO valid private IP address (indicating we connected to an AP as a client/station), we attempt to setup the WiFi device as an AP.we check to see if the WiFi device has older or newer firmware.

a. If we detect OLD firmware, we check to see if there is an SSID set, and if so, we use the SSID
and password to try and connect to the local network router. We then ALSO try to setup a software
AP mode creating an SSID of DCCEX_123456 and PASS_123456 where "123456" is the last 6 characters
of the MAC.

b. If we detect NEW firmware, we set the hostname, check if there is an SSID set, and if so, use the
SSID and PW to change the CURRENT settings and connect to a local network router. We then ALSO setup
a soft AP with an SSID of DCCEX_123456 and PASS_123456 where "123456" is the last 6 characters
of the MAC. Finally, we set the TCP recieve mode to "active mode", which sends all data instantly to
the Command Station without being held in a buffer.

///// Question: What is the difference between SSID and Hostname as it relates to what we see on our network
list and ED? Is only "hostname" available to substitute for IP address in something like ED?

10. We set a TCP server to be able to handle multiple connections
11. We enable the TCP server
12. We display the IP addresses and MAC addresses for the Station (Client) and AP

///// Question: We are calling this in the main .ino sketch. Should more of this be done inside the library? In particular the checking off each serial port to find a device? I see why it works here, devices could have different numbers of serial ports. But thoughts?

Serial1.begin(WIFI_BAUD);
  wifiUp = WifiInterface::setup(Serial1, wifiESSID, wifiPassword,dccex,port);
#if defined(ARDUINO_AVR_MEGA) || defined(ARDUINO_AVR_MEGA2560)
  if (!wifiUp) {
    Serial2.begin(WIFI_BAUD);
    wifiUp = WifiInterface::setup(Serial2, wifiESSID, wifiPassword,dccex,port);
  }
  if (!wifiUp) {
    Serial3.begin(WIFI_BAUD);
    wifiUp = WifiInterface::setup(Serial3, wifiESSID, wifiPassword,dccex,port);
  }
#endif

Rico is working on this already.

Neil posted a great collection of info on Discord from 3rd Oct in the CommandStation-EX / #issues channel, over a couple of days.

This is a compilation of Discord conversations about updates to the online docs.
Hopefully it is easy to scroll thru and find things to work on!

Maybe we need to separate these out into individual Issues?

EX-RAIL docs updates.txt

The pictures at the begining of EX-RAIL intro page on how to make a myAutomation.h are missing.

These are .JPG files, and are in the same folder as .PNG track diagrams that correctly display further down the page.

These images have previously worked fine.

https://dcc-ex.com/reference/hardware/wifi-boards.html

Latest version does broadcast sensors and power state but the warning about performance still stands.
Diagnostics are NOT sent over wifi connections primarily because most of them are for diagnosing wifi problems!

[Ash++ on Discord]https://discord.com/channels/713189617066836079/907288524158558299/929849585151660114

I am now careful to see that I am getting the model that says WROOM-32. It is the low-cost version and available.
--- ESP32 pins are more scarce than expected; using WiFi may preclude use of all the ADC2 pins and other pins are potentially reserved. In other words, don't plan on connecting accessories to anything except I2C modules, and use an external transistor/inverter circuit for motor boards.
--- There is a WROOM-32 board in UNO form factor. It may provide the plug-n-play option with standard motor shield; add jumpers to put current sense pins at A2/A3 locations. Also 2A is 3.3V, so a question of whether to add voltage divider or zener. The onboard antenna might be an issue as it is located below the motor shield.
--- Using Arduino IDE for ESP32 is a different experience than with a Mega. Even after you get the environment installed, it is questionable on whether you have the correct board selected. And compiling/uploading takes several minutes longer than it does for a Mega. (Or I need a new laptop?)

The link to the 12V power supply is malformed.

https://dcc-ex.com/reference/hardware/shopping-list.html

Brackets are all in wrong places at this spot.

Supply for the Track <connects to the motor shield)](https://www.amazon.com

MRC(?) decoder required over-long ACK to communicate.
This also caused INT overflow in the Diag readout, showing -ve numbers.
https://discord.com/channels/713189617066836079/932108977372803123/932338796454871080

Defining a SERVO_TURNOUT requires the profile to be specified as text as defined in IODevice.h rather than an integer, which is a bit ambiguous in the documentation and could use some clarification.

From KC:
To use OLED displays on your Mega Command Station, you can save line LCD5 used for Port# id and combine it with line LCD4 IP address.

But be Aware that the two combined IP Address and Port# can easily exceed 20 characters depending on your IP and port length.
Since I use 10 for IP and 4 digits for Port, It works for me.

First edit and combine the two lines in
WifiInterface.cpp tab, on about lines 313 and 317 comment out the existing LCD4 and replace it.
// LCD(4,F("%s"),ipString); // There is not enough room on some LCDs to put a title to this
LCD(4,F("%s:%d"),ipString,port); // *** Single IP:Port added by KCSmith 1-8-22. Comment Out //LCD(5,F("Port=%d") Below
// Suggest using an OLED 20x plus screens.
}
// suck up anything after the IP.
if (!checkForOK(1000, true, false)) return WIFI_DISCONNECTED;
// LCD(5,F("PORT=%d"),port);

Then add what ever you like in your mySetup.h file, This is from mine.
// Display Special Information on LCD 16x2 or OLED 20x4 and greater screens.
// note change config.h address depending on the device PCF8574 is addresses 0x20-0x27, but the NXP PCF8574A is 0x38-0x3f
// LCD(0 thru 5 are normally reserved for the Command Station reports, but you can use them if you wish
// Send a Message Directly to a LCD or OLED screen lines 0 thru 7
// LCD(4) // Is Reserved for IP Address and LCD(5) Was Port# In the WifiInterface.cpp tab between about lines 313 and 317
LCD(5,F("DCC++EX 3.2.0 MASTER")); // line 5 Detail Firmware Version Info
LCD(6,F("EXRAIL Jcmd Beta 1")); // Line 6 Detailed Firmware Version Info continued
LCD(7,F("mySetup by KCSmith")); // Line 7 mySetup.h built by whom

A people may use either Platform IO and VSC or PlatformIO on Atom or the Arduino IDE it would be very helpful to have a section on how to build the CommandStation from within each of those. Maybe VSC/PlatformIO and Arduino IDE would be sufficient though.

https://dcc-ex.com/reference/hardware/i2c-displays.html#controlling-brightness

1. 1 or 2 byte loco address not 2,4
2. Whats new list not sub indented
3. No railcom cutout

KC using a HC-05/HC-06 Bluetooth module on Serial0 {Tx0 Rx0} Mega+ WiFi shield [Makerfab8266] CS connected Bluetooth to a PC JMRI for Operations, and a second USB cable to a Mega+Wifi Combo CS to the same PC JMRI for Programming Station and Testing. The Serial Bluetooth connection works over 25ft+ as well as the serial USB.

You can also directly connect to the first CS with either a WiFi WiThrottle App and with a Bluetooth capable WiThrottle App.
The HC-05 would be more flexible with the ability to be either a master or a slave.

Discord convo with MLS on 6? Jan 22 in #jmri, recorded in conversation.txt file.

1. BROADCAST("text")
   broadcasts the text to all connected <> throttles, JMRI etc. over serial and Wifi.

2. POWERON
   Switches power ON for the main track and disconnects any JOIN.

There is a slight risk where you join the 2 back-to-back turnouts with one button because someone using a throttle could alter one of them without altering the other and then they're out of sync.

It might be best to write the interlinked ones slightly differently to a standard turnout but it depends on your level of confidence with code...

Perhaps I would have used this technique:
Assuming my interlinked turnouts are A and B

• DON'T define B as a turnout, so nobody could THROW B from a throttle because it would be invisible.

in the ONTHROW(A) or ONCLOSE(A)
use a SERVO command to move B to match A correctly.

(For info of other readers: The same technique works if you are using pin or DCC turnouts)

You cant use a generic CLEVER macro for this, because its a special case so just write the script for A as you did before.

E.g. the world-famous CLEVER macro.

Also can now include AUTOSTART in macro def, so each child will.... autostart.