david284 / ModuleDescriptor

VLCB/CBUS Module descriptor format & examples
1 stars 3 forks source link

CANCMD v4f firmware request #37

Open swinguk opened 3 weeks ago

swinguk commented 3 weeks ago

There's a new BETA firmware (v4f) of the CANCMD (and CANCSB). Renaming the current CANCMD-A50A-4d.json to CANCMD-A50A-4f.json confirms that this will support the current beta (Note that a CANCSB supplied direct from RME is likely to come with v4f as standard, hence the need for support, and also see issue #36 for a request to support the CANCSB), although there are additional NVs to support new functions (listed below).

The CANCMD BETA notes include the following data on the new NVs supported in v4f:

NV17 to NV76 – Shuttle Table Version 4f contains a hard coded “proof of concept” shuttle facility, with fixed hard coded event values, which makes some use of the shuttle table. Each shuttle reverses, with a pause of 20-30 seconds or so, on receipt of CBUS events which can be generated by any CBUS module connected to any type of train detector. At present the events are hard coded (see the events section) but will be teachable in version 5. CMDFW issues an F0 on and F1 on for each shuttle at startup, to turn on lights and sound if fitted. Each of the 15 shuttle table entries contains 4 bytes. Software that allows the user to set up the shuttle entries can hide the complexity of which NVs are which shuttle entry. At the time of writing, this needs to be done using FCU generic mode, or similarly using JMRI node manager or Web FCU. Bytes 1 and 2 – Default Loco Address – Setting this value is one way of setting up which loco is to operate a particular shuttle. There is also a mechanism to override this at run time by releasing a loco into a shuttle. A future possible enhancement would be to set a loco into a shuttle by an RFID detection or Railcom. Byte 3 - Default speed - If the speed is not modified by other shuttle events, this is the speed which will be set for a loco in this shuttle. The speed is a value from 0 to 127. Set the most significant bit to initiate this shuttle loco in the reverse direction Byte 4 – Shuttle Flags • Bit 0 - Valid. This bit is set to 1 when the shuttle entry is used – if set to zero then this shuttle entry is ignored. • Bit 1 - Started. Set to 1 in memory when the shuttle is active • Bit 2 - Autostart. Set this bit to automatically start this shuttle whenever the command station starts. • Bit 3 – Manual Set to run this shuttle train manually (not currently implemented) • Bits 4-6 Used internally during shuttle operations • Bit 7 - Initialised Set to zero means this entry is not in use, set this bit if you have initialised this entry These 4 bytes are repeated in groups of 4 Nvs up to the maximum of 15 shuttles currently supported. At the time of writing, this has been tested with a maximum of 4 shuttles running simultaneously, with another 5 or so trains running on the main line manually. There are hard coded events which are used for the shuttle reverse sensors, and to start or stop all shuttles. See the events section for details of these events. Version 5 will allow these to be taught as consumer events.

NV77 to NV216 – DCC Accessory routes table Version 4 contains a table of NVs that can be populated to provide a limited number of “Routes” of DCC accessory commands triggered by a single CBUS event. Please note that at the time of writing, this feature has NOT been tested. (Because the author doesn’t own any DCC accessories!) This complements the feature that allows short events, or long events of a specific node number, to be mapped to DCC accessory events for those who wish to use the CBUS command station with DCC accessories, instead of accessories directly operated by CBUS events which would be the norm for a CBUS based layout. In version 5, this capability will be possible by teaching the same CBUS event for multiple accessory command actions. Each accessory route table contains a 2 byte header, and then 6 accessory command entries. These are repeated, starting from NV77, to provide up to 10 routes, each with up to 6 DCC accessories operated together. If 6 accessories is not enough, you can use more than one route with the same CBUS event number. The 2 header bytes are the CBUS event number that will trigger this route. The node number must match NV11 & NV12. If they are set to zero, a short event will trigger the route. If a CBUS event triggers a route from this table, it will not be mapped to its own DCC accessory address. ie: The route overrides the normal mapping. Each of the 6 accessory entries in a route consists of 2 NV bytes, which are the accessory address and some flags. The first byte contains the accessory address. Note that the use of a single byte to specify the accessory address means that this route feature can only be used with DCC accessory addresses up to 255. The second bye contains 2 flags in bits 0 and 1. The first flag in bit 0 is set to 1 to show that this entry is in use. Entries with this flag cleared to 0 will have no effect. The second flag in bit 1 is set to 1 for accessory ON when this route is activated, and cleared to 0 for accessory OFF when this route is activated. The mapping of CBUS events to DCC accessory addresses is the same as described on page 6 for the single mapped node.

SvenRosvall commented 3 weeks ago

Two items here:

  1. Add new files for new version and for CANCSB. Happy to add this. We have more requests for these.
  2. Add support for the shuttle feature and DCC accessory support.

Do you use the shuttle feature in CANCMD/CSB ? If not, are you happy if we produce new files without the shuttle feature? Even Pete Brownlow who implemented the shuttle feature doesn't use it. So I'd like to find the people who use it and who can test the shuttles. The same question goes for the DCC Accessory support. If there is noone to test this then I prefer to leave it out.

swinguk commented 3 weeks ago

I don't use either feature personally, so new files without the feature wouldn't affect me; I think getting the files out there is more important than having every feature configured. To clarify, I think Pete does use (or at least has tested) the shuttle feature, but I agree the DCC accessory routing is both untested, and possibly has issues right now (Pete noticed a bug in it over the weekend, so it most likely needs an updated firmware to even work; I know when I tried the route feature when it first came out, it didn't work for me).

david284 commented 3 weeks ago

I'm updating my simulator for CANCMD & adding CANCSB - so i was hoping one you guys could tell me, for each version 4d, 4e, & 4f, the following node parameters (I'm assuming CANCMD & CANCSB are the same) param4 - number of events supported param5 - number of event variables param6 - Number of node variables I've tried looking at the source code, but struggling to work it out, and I'm guessing one of you has an actual example

swinguk commented 3 weeks ago

I'm out at the moment, but https://www.merg.org.uk/forum/viewtopic.php?p=218197 should have a CANCMD v4d NV export and a CANCSB v4f NV export in separate messages if that helps. V4e was only released as a beta, and I believe would mirror the v4d settings as the new NVs all came with v4f, so unless requested, it may not be necessary to add support for v4e?

david284 commented 3 weeks ago

Thank you, exactly what I needed

SvenRosvall commented 3 weeks ago

... I think Pete does use (or at least has tested) the shuttle feature ...

I heard Pete say that he doesn't use the shuttle feature himself but implemented it for a friend. I don't know who this friend is. Pete uses JMRI for most of his automation. I don't think Pete will complain if the shuttle feature is missing. :)

david284 commented 3 weeks ago

I think I see where my confusion comes from from earlier in this thread "At present the events are hard coded" But the parameter values suggest it supports up to 255 events and 10 event variables? And there are no entries in the MDF for events, which suggest they aren't supported?

swinguk commented 3 weeks ago

Also possibly not helped by me linking to the wrong BETA NOTES file (now linking to the correct file that documents the NVs as well as the various hard coded events available on a CANCMD, including things like Emergency Stop on page 10). I wonder if the MDF could / should list these hard coded events to allow them to be taught to other nodes? (but only listed against v4f which introduced them; eg v4d does not support the Emergency STOP CBUS event).

I wonder if MDF / MMC can actually work with hard coded events (especially where the node number used in the event is not the node number of the module) - eg the CANCMD will have a node number of 65534, but responds to events such as node 167 event 103. Certainly I've tested this in that if you teach node 167 event 103 to another device to issue, the CANCMD / CANCSB will invoke an ESTOP.

david284 commented 3 weeks ago

In MMC you can either add an event with the actual event identifier (event nodenumber/event number), or it can capture the event 'off the bus' if it's been sent, and can be taught from that - so yes there are ways of doing this in MMC There are several other modules that have 'default' events that can't be read from the module, these are treated the same

I assume if the events are 'hard coded' then you can't change the event variables either If that's the case, then I think the module is incorrect in saying it supports 10 event variables - if they can't be changed then they aren't variable by definition But we are where we are

I'm thinking that maybe there ought to be a generic 'information' element in the MDF, so that 'quirks' in a module can be described and displayed to the end users - e.g. in this case we could have "information":"Although this firmware version defines 10 event variables, they are not changeable" which could be displayed before the event variables

swinguk commented 3 weeks ago

Right now, as I understand it, the shuttle uses the NVs to configure the movement, and then some hard coded events (page 10) to start / stop the shuttles. Whist the document also talks about firmware v5 (page 11 onwards) and what may come with the ability to learn events to configure, I think as v4 stands, the module can't learn / be taught any events at all, despite (as you've noticed) defining that capability within the parameters, so the only events that the module will respond to are those hard coded events (across nodes 167, 162, 120, 163 and 164, and produce 2 hard coded short events; ACON event 0 and ACON2 event 1 if either have been configured to be sent). I agree an informational message may be useful here, and/or can the MDF format support "here's a list of hard coded events, there are no user configurable events" (ie like a read only list of events, rather than the more usual EV options with the ability to change them)?

Thanks for the explanation of how to add the event; I guess my query was more should the MDF for the CMD/CSB provide those hard coded events to save someone having to know that they exist and what they are to be able to use them?

RichardCrawshaw commented 3 weeks ago

We need to think about how it can be made easy for people to create MDFs. Some sort of editor, or some sort of template, perhaps a "wizard", a series of questions and steps. (I'm not saying any of those are the right answer, more thinking points.)

JSON files are great for holding data. But creating them is not the easiest or most straightforward thing to do. I've created JSON files by hand in the past, but it's not something that would I want to insist that first time users have to do. Particularly if this is also the first time that they may have done anything with NVs or EVs.

RichardCrawshaw commented 3 weeks ago

We need to be aware of the difference between three types of hard coded events.

Then there are Events that aren't reported when the module is queried, and presumably have no EVs, but which it produces under the appropriate conditions. Aka hidden Events. These could also be one of the above types, but not necessarily.

To deal with an Event that has one or more EVs that cannot be changed, I think a "Fixed" EV type is needed. That way the EV can exist in the MDF along with the others, can be made visible to the user, and is explicit to them that they cannot change it. This approach will remove the opaqueness that would otherwise exist for those EVs.

For hidden Events it would be helpful if their details could be exposed in the MDF in some way, but that is a whole new section in the file, and probably needs its own issue and discussion separate to this.

david284 commented 3 weeks ago

Richard, agreed an editor of some kind would be useful - hopefully someone will accept that challenge

Regarding events, My first thoughts would be a fairly straightforward approach You could have an 'event' element, with a key of the eventIdentity (event nodenumber & event number) And each event entry then has it's own attributes, addressing the different types you mentioned

RichardCrawshaw commented 3 weeks ago

David, yes that sounds like it would work. I feel that two 16 bit numbers would be easier than one 32 bit number for the Event Identity. Also only one would be needed where the Event is relative to the Node itself. The details of the attributes probably need to be worked through a bit more thoroughly than I did in my comment.

david284 commented 3 weeks ago

The nice thing is that we can add the attributes as we need them,..

The problem I've run into where two 16 bit number are used is that people get confused about the first one - it's not the node number of the module storing the event - it's part of the identity of the event, and it's not necessarily the node sending it either, as quite a few modules can 'spoof' events, so really it is a 32 bit number unique to that event, hence I've chosen to call it an eventIdentifier Note that the current cbusLib version gets this wrong as well, if you try to read short events using the full event number (not index), you get the node number back instead of 0, only reading by index works properly

david284 commented 3 weeks ago

Started a new issue about events to capture this

RichardCrawshaw commented 3 weeks ago

I like "event identifier".

The reason I would prefer two 16 bit numbers over one 32 bit number is the separation of the two parts. I have node 268 and node 379 where the latter spoofs event 77 from the former. It's much easier to understand 268 77 and to ensure it is right than 17563725.

Perhaps: "eventIdentifier": { "high": 268, "low": 77 }

It would be so much easier if the convention was for Nodes and Events to be given hex values rather than decimal ones! 0x010C004D is just easier all round.