{"id":655,"date":"2014-12-31T00:45:22","date_gmt":"2014-12-31T05:45:22","guid":{"rendered":"http:\/\/www.thegatesofdawn.ca\/wordpress\/?p=655"},"modified":"2021-04-13T00:11:22","modified_gmt":"2021-04-13T05:11:22","slug":"programming-the-insteon-powerlinc-modem-2412s","status":"publish","type":"post","link":"https:\/\/www.thegatesofdawn.ca\/wordpress\/posts\/2014\/12\/31\/programming-the-insteon-powerlinc-modem-2412s\/","title":{"rendered":"Programming the INSTEON PowerLinc Modem 2412S"},"content":{"rendered":"

I’ve been writing some code to drive the INSTEON PowerLinc Modem<\/a>.\u00a0 It’s not the newest generation of INSTEON interfaces, but it’s the one I have in my system.<\/p>\n

It’s been kind of a miserable experience.\u00a0 This thing could serve as a textbook example of how not<\/span> to design a serial protocol.<\/p>\n

<\/p>\n

Framing<\/h3>\n

Messages from the modem always begin with an ASCII STX (“Start of Text”) character.\u00a0 So far so good.\u00a0 So, you’d think the message would end with an ETX (“End of Text”).\u00a0 But no.\u00a0 They just… end.\u00a0 There’s no end-of-message marker of any sort.\u00a0 There’s no message-length field.\u00a0 The only way to know when the message has ended is to look up the message-type, which follows the STX, and deduce the expected number of bytes from that.\u00a0 Crappy.\u00a0 So now even the very lowest layer of my driver has to have detailed knowledge of the protocol.<\/p>\n

Synchronization<\/h3>\n

So, what if you’re out-of-sync with the message stream somehow?\u00a0 For example, your program just happened to start up in the middle of an unsolicited notification message.\u00a0 How do you get in-sync?\u00a0 In a well-designed protocol, you would just wait for the first STX.\u00a0 That marks the start of a message, right?\u00a0 But no.\u00a0 The protocol has no provision to escape STX characters that happen to appear by chance in the body of a message.\u00a0 So the first STX character you see might not be real.\u00a0 So now you have to write a whole lot of ugly code to figure out if an STX character you see is followed by a message-type byte that makes sense.\u00a0 And you have to hope that reasonable-looking message-type byte wasn’t fake too, because if it was you might end up waiting for a long time for enough data to fill out the fake message you’re expecting.\u00a0 You need to implement a time-out too, to guard against that.<\/p>\n

Whenever anything goes wrong (either an unreasonable-looking message-type byte, or a time-out on getting to the end of the fake message), you have to just discard a single byte (the fake STX), and then try the whole thing again.\u00a0 Because the very next byte after the fake STX might have been a real STX.<\/p>\n

There’s no guarantee that this process won’t result in your lower layers sending your higher layers a potentially unbounded series of garbage messages that happen to have a reasonable-looking message-type, and enough data bytes, but are otherwise complete gibberish.<\/p>\n

ACKs and NAKs<\/h3>\n

Commands that you send to the modem get echoed back to you, followed by an ACK or NAK.\u00a0 Usually they get echoed back verbatim, and you can just ignore the whole thing except for the ACK or NAK at the end.\u00a0 But for certain commands, the echoed response is slightly changed, or slightly longer.<\/p>\n

There’s nothing like a checksum defined in this protocol.\u00a0 What a NAK means is that the modem was too busy to handle your command, and you need to resend it a bit later.\u00a0 A primitive sort of flow-control, but OK, we can work with that.\u00a0 Or can we?<\/p>\n

No, it’s not that simple.\u00a0 Actually, NAK doesn’t always mean “I’m busy.\u00a0 Ask again later.”\u00a0 In at least one case I’ve found so far, it means something else.\u00a0 For the “Get Next Link Record” command, NAK can mean “there are no more link records.”\u00a0 So now, if I send the “Get Next Link Record” command, and get a NAK response, what should I do?\u00a0 Should I resend the command, or should I assume there are no more records?\u00a0 Who the hell knows?<\/p>\n

From what I’ve read of the INSTEON power-line protocol, it struck me as very cleverly designed.\u00a0 They seem to have thought of every weird corner case, and accounted for them all.\u00a0 How could those same people then proceed to poop out the haphazard, poorly-thought-out mishmash that is the PowerLinc serial protocol?<\/p>\n","protected":false},"excerpt":{"rendered":"

I’ve been writing some code to drive the INSTEON PowerLinc Modem.\u00a0 It’s not the newest generation of INSTEON interfaces, but it’s the one I have in my system. It’s been kind of a miserable experience.\u00a0 This thing could serve as a textbook example of how not to design a serial protocol.<\/p>\n","protected":false},"author":2,"featured_media":0,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[89,4],"tags":[],"class_list":["post-655","post","type-post","status-publish","format-standard","hentry","category-home-automation","category-tech"],"_links":{"self":[{"href":"https:\/\/www.thegatesofdawn.ca\/wordpress\/wp-json\/wp\/v2\/posts\/655"}],"collection":[{"href":"https:\/\/www.thegatesofdawn.ca\/wordpress\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.thegatesofdawn.ca\/wordpress\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.thegatesofdawn.ca\/wordpress\/wp-json\/wp\/v2\/users\/2"}],"replies":[{"embeddable":true,"href":"https:\/\/www.thegatesofdawn.ca\/wordpress\/wp-json\/wp\/v2\/comments?post=655"}],"version-history":[{"count":3,"href":"https:\/\/www.thegatesofdawn.ca\/wordpress\/wp-json\/wp\/v2\/posts\/655\/revisions"}],"predecessor-version":[{"id":763,"href":"https:\/\/www.thegatesofdawn.ca\/wordpress\/wp-json\/wp\/v2\/posts\/655\/revisions\/763"}],"wp:attachment":[{"href":"https:\/\/www.thegatesofdawn.ca\/wordpress\/wp-json\/wp\/v2\/media?parent=655"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.thegatesofdawn.ca\/wordpress\/wp-json\/wp\/v2\/categories?post=655"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.thegatesofdawn.ca\/wordpress\/wp-json\/wp\/v2\/tags?post=655"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}