Understanding Legacy Command Protocol

Lets be honest, It took me a little time to understand what you were trying to say here.  

It came down to this, I think:  Sometimes the first 3 bytes of a multi word command could be the same as a single word command.  and if that's the case does the engine or such have some way to know which it is.  

Once I got that far I found what I think is the problem pretty quickly. well, actually two problems, this was the first one I saw:  

""- It was easy enough to come up with a case where "1 N N N N" matched up bit-for-bit with "D D D D D."  -""

 1 N N N N  can never equal D D D D D.    if the first half byte here is 1 it can not be D, 

ex in the example F8 AA AA, AA A1 01, 1D DD DD the last byte reads the binary of:

0001 1101 1101 1101 1101 1101

where as the multi word command of F8 AA AA, AA A1 01, 11 DD DD reads as:

0001 0001 1101 1101 1101 1101

The second thing that I noticed, I'm ashamed to say was not the first thing as it smacked me in the face as I was writing the reply here.  

word one, the first three bytes in a multi word command are F8 AA AA, so you need to see if this command can ever be anything else.  that translates to the engine command byte of 0xF8 then the Binary command of 1010 1010 1010 1010.  the standard commands read the first 7 bits here as the engine address, in this case, Engine # 85 ( it bay be 84 or 86 according to the remote, I forget which way it adds one.)  the the next 9 bits would be the command to the engine.  

The 9 bit engine command would be:  0, 1010, 1010

This is not a valid command according to the table on page 8 and 9 of the 1.21 spec found here:  http://www.lionel.com/lcs/reso...tocol-Spec-v1.21.pdf

So, quite simply, No.  there is never a case where the engine has to determine if a command is meant for it or for a multi word command... though engine number 85 may wonder why you are sending it a useless command, if the serial data is repeated directly to the track in legacy.  

Edit:  

I think there may be a mixup in terminology or understanding as you said the first 3 bytes were: 0xF8 + A A A A   A A A 1  +  0 1 1 1   N N N N

0xF8 + A A A A   A A A 1  +  0 1 1 1   N N N N is 9 bytes, not 3.

Hi John. 

Just a quick THANK YOU for posting your thoughtful response to my question about Legacy protocol.  Based on the absence of replies until now, this is something that not a lot of folks have tried to figure out -- it's not nearly as trivial as the old TMCC protocol.  But it's a fun challenge, and I think the greater control -- especially over voice queues -- will be worth the effort for my Arduino project.

I have not been able to quite understand your points, but I'm still working on it and will post back as soon as I can comment intelligently ;-)  But I wanted to let you know that I did receive it and appreciate it and will get back to you as soon as I can get my head around your response.

Thanks again!

Randy

Hi John (and anyone else who'd care to chime in),

Yes we'd better get on the same page before we decipher each other's bit patterns ;-)

You said "0xF8 + A A A A   A A A 1  +  0 1 1 1   N N N N is 9 bytes, not 3."

I don't follow. 0xF8 is one byte.  The "A"s and "N"s and "D"s in my example represent individual bits -- the protocol spec, and my example, uses these letters to make it clear what those bit positions represent, helpful especially since they fall across byte boundaries.

So, eight bits to a byte... 0xF8 is byte #1, "AAAA AAA1" is byte #2 (for example "0000 0011 which would be hex 0x03), and "0111 NNNN" is byte #3 (for example "0111 0010 which would be hex 0x72.)  Thus: 0xF8, 0x03, 0x72.  Three bytes, not nine by my count.

How are we seeing this differently?  Thanks in advance for your patience if I'm not seeing something that's hitting me in the head ;-)

Randy

I see now that you were interpreting the "AA" "01" "11" etc. in my examples to be hex.  Sorry for mixing bases...  I was using hex specifically for the first byte because it's always 0xF8, but the rest of the command (bytes 2 and 3) were in binary, with equivalent hex written below it (if you look at my scan that I included with my post.)

But since I have your attention, if you would be kind enough to look at my example once more with this new understanding, I would be very much in your debt.

Randy

Randy

just about all things related to science.

Wow....Heavy stuff for a simple train nut like me.

But. it's fun to read Randy.

Larry

Sorry I was unable to reply until now.  give me a moment and I'll try to make a reply that makes sense.  And yes I see where we had some misunderstanding about the bytes and bits.  

Ok, Lets throw away everything I said before because of the misunderstanding of what was going on.  

The question still seems to be, can a standard 3 byte command ever be the same as the first 3 bytes of a multi word command?  

And now I see what you are talking about, set absolute speed (32) could have the same data as any of the parameters available for multi word commands.  

I would guess that, that being the case, the engines know how long to wait for the data.  For example the code in the engine would read the incoming data and say "If I get more data in the next X miliseconds, and IF that data starts wit 0XFB, then I have a multi word command.  Otherwise, set speed step.  

The other thing that comes to mind is that I Think all legacy engines are capable of the 200 speed steps, so it would be less common for someone to be running them with 32 steps.  This would allow the engine to normally assume that the data of 0x03 0x72 from your example is the start of a multi word command,  most of the time.  In addition only half of the possible speed steps are valid parameters for multi word commands, so it can can know it's a speed step if it gets one of the ones that is not a parameter.  

It seems to make the job harder for whoever had to write the code inside the engines here and I am quite confused why they would not have used a "bit 9 = 0" command to define a multi word command, but someone must have thought it was simpler this way.

I looked at the legacy command base manual and a manual for the VL Big boy and from what I can tell, the only time a  absolute speed command with 32 steps would be sent is when using a Cab 1L as I don't see anywhere in the cab2 commands to set to 32 steps, so it may be that the engine assumes it is a multi word command trigger, then if it doesn't get any more data it passes it on as a speed step.  

In any case, you are right, and it is weird.  Two operations can have the same command.  

Since after more than 200 views, nobody really seems to know the key to this mystery, I've forwarded my question to Lionel LCS developer support.  If I receive an answer, I'll post the solution here.

I'd like to see what, if anything, they have to say.  I don't, however, think it matters much for development purposes so long as the engines read commands correctly.  When sending the multi word commands have you ever had an issue where it has set a speed step instead?  If not, I think the software in the engines knows to look for a second word starting with 0xFB, then only to apply the set speed command if it does not get the 0xFB data as the next byte of data.  

You're probably navigating uncharted waters.

Since I know of 2 LCS partners, I suspect others have already crossed this bridge.  The LCS developer support is probably your best route.

One wonders how eager the other LCS partners are going to be to help you compete with them.

Thanks for the suggestion, Jon.  I am already able to send and receive raw data to/from an Arduino and a Legacy base -- but interpreting the raw incoming data is what prompted my question in the first place.

I sent LCS developer support another email asking for information on how to become an "official" LCS partner.

Looking forward to hearing back from them, and of course I will post whatever I am able to here, for you folks who are interested.

Obviously I don't know exactly what you're trying to accomplish here, but for your code I think you would have to do something like this to read incoming data:  

at the top before commands are processed but after your Serial.read of incoming data you would check if it is a standard, 3 byte, command.  If so continue on as normal.  if it is a multi word command, you would have a separate routine to handle that. in psudo-code as follows.  

If (serialData = 0xf8 + AAAA AAA1 0111 NNNN)

     Then: check serial for more data.  

           If (newSerialData = 0xFB)

                   Then: run multi word void loop  

           else:  run single word command loop

the actual code would involve some bit shifting and such to only look at the needed parts of the data, and would also need to include 0xF9 byte I think.  

Hi John,

You are exactly right.  And I can use bit masks for most commands to easily determine if they are one-word 3-byte commands, or extended three-word 9-byte (or longer) commands.  However in the example I cited (and others) you can't tell just by looking at the first set of three bytes -- unless there is something I'm overlooking or don't understand (which I'm kind of hoping is the case.)

Unfortunately, I can't simply wait for the next byte to see if it starts with 0xFB, for two reasons:

1. There may not be a next byte for a while.  I suppose I could do a time-out, but no idea how long I should wait.

2. More importantly, even if I'm looking at the first word of a three-word command, there is no guarantee that the next word will begin with 0xFB, or if it does, that it is part of the previous command.  The partner doc specifically states that the words do not need to be contiguous, as long as they are in order.  Other commands, both three-byte and nine-byte, could be in the mix, as long as they all remained in relative logical order.  That's an important point, and it makes things much more challenging.

I'm not comfortable with the idea that I just need to keep reading bytes for some random amount of time before I can be certain what type of command it is, and then take action.  And I can't believe that's how Lionel does it -- after all, you want a locomotive to respond instantly, without lag times.

I received a very nice response from Lionel this morning, and they have offered to provide me with further details regarding all of this.  To the extent that I am able, per the terms of their NDA, I will share the answer to this mystery here.

Ahhh.  This makes me very happy ;-)  Makes my job a lot easier!

Thank you so much for looking into this, Rudy!

Randy

Honestly

This type of thread is what makes this forum so outstanding and interesting.

Larry

Keep having fun guys/gals

Yup! You're right Larry. Good Job Randy! We can name you the official Lionel Error Checker.

Ron

So, for clarification, this is a documentation error?  Is the bit pattern NOT a set speed step command? 

I'm also a little confused, Randy, on what you said where multi word commands could have other commands sent between words. I suppose it would not matter if you know that 0xfb tags it as part of multi word, and that you got the start byte.  I guess I need to know if the 0xf8 + AAAA AAA1 0111 NNNN) is not a valid single word command, or what the deal is before going deeper.  

John, it was an error in the LCS Partner Documentation because Legacy will never issue a 32-step speed command, but would always use the 200-step command - which is totally different.

If they DID use the 32-step command as described in the manual, then there would in fact be an ambiguity in that a loco would not know if it was receiving a speed command or a sound command (in the example above.)

The solution would seem to be, to simply remove the "Set Absolute Speed 32" command from page 9 of the document.

I've looked at all of the other commands and I'm not seeing anything else that could be potentially ambiguous.

As far as my understanding goes (which may not be 100% correct,) multi-word commands are sent in packets of three bytes each.  Generally three packets per command (9 bytes total.)  But if there is more than one device sending commands, it's possible that the 3-byte packets could be interlaced.  The partner doc says that it's okay to intermingle packets being sent to different addresses, so long as the packets for each address remain in logical order.  Their terminology of "words" when they're talking about 3-byte packets is, I assume, because bytes #2 and #3 form a logical "word" which is computer-speak for two bytes.  The first byte is just sort of an identifier.  So they call a three-byte packet a "word."  It's a little confusing, but once you've read it fifty times as I have in the past few days, anything will start to make sense ;-)

I would be delighted to discuss bit masks and other considerations and intricacies of the Legacy protocol with anyone else who is interested in understanding it, but I suggest we create a new thread.  Thanks to Rudy, this one has been resolved.

We can now move on to more interesting and intriguing aspects of the spec., such as whether momentum is built-in to Legacy locos or if it is handled by the CAB-2 spitting out progressively higher (or lower) speed commands over some period of time.  I think I'm going to have to figure that one out by hands-on experimentation, because it's an important factor in my autonomously-controlled layout.

Randy

I'll look forward to a new thread in the coming days or weeks as things pop up.  This question has me intrigued.  I may have to fork out some money for legacy just to play with the electronics...  Arduinos and Legacy sure seem like more fun than than my commodore 64 and lots of shift registers from the old layout.  Good Luck.

Just a quick update: A corrected version of the Legacy Protocol document can be found at:

http://www.lionel.com/lcs/reso...tocol-Spec-v1.22.pdf

-Rudy

Thank you Rudy, I'm going to grab it!

Excellent!.  Thank you.