Ozeki Line Protocol

Introduction

The protocol is developed in order to make it possible for a PC to communicate with a microcontroller through a serial port.

Points of view designing a protocol:

  • More devices can be served by a microcontroller
  • The microcontroller signs in and informs the PC about which devices are installed on it
  • The communication have to be short (less byte is needed on the microcontroller for storing the received PDUs)
  • The PC only sends one message at the same time to the microcontroller (as many microcontroller does not support parallel processing)

Message types:

  • Event = The microncontroller informs the PC (e.g. welcome, heaterinfo)
  • Command = The PC orders the microcontroller (e.g. setpushinfo, setswitch)
  • Command resp = The microcontroller accepts the order from the PC (e.g. setpushinfo_resp,setswitch_resp)
Note: The command resp always contain the name of the order and always end with '_resp'.

Rules:

  • After building of a connection the microcontroller starts the connection with sending one or more welcome event. This is how the PC is informed about the connected devices.
  • Every message starts in a form of 'c=nameoforder'.
  • Every message is one row.
  • The message parameters consist of a name and a value with an equal sign between them.
  • The message parameters are separated with a '&' sign.
  • Every message is ended with a "\n" sign (ascii code: 10, 0x0A).
  • The maximal length of the message sent by the PC: 64 byte (the value of the Arduino serial buffer, in case of sending more data and the Arduino can not read them out quickly enough then the end of the data is lost).
  • Message parameter name cannot contain space. Possible characters in the name: [a-z0-9].
  • Message paramater value is urlencoded string. The character set is UTF8. (urlencode, utf8)
  • All the devices connected to the microcontroller have an individual ID.
  • In case of every newer message the 't' is increased with 1 value (except the 'ack' messages, if we ask for 'ack').
  • The last parameter of the event, command, command resp is the checksum parameter, if the checksum is switched on. e.g. "...&s=abe4\n" (Calculating with Fletcher 16 algorithm
    (checksum and ack switch off/switch on here)

Sample communication (checksum OFF, ack OFF):

<-  c=welcome&id=0uAAly&type=OzekiIDManager&pos=1&version=1.0.0
<-  c=welcome&id=6O1KiA&type=OzekiStepperMotorMultiController&pos=2&version=1.0.0
<-  c=welcome&id=3Mx14T&type=OzekiButtonController&pos=3&name=StopYmin&version=1.0.0
<-  c=welcome&id=xvnuu3&type=OzekiButtonController&pos=4&name=StopYmax&version=1.0.0
<-  c=welcome&id=1988L4&type=OzekiButtonController&pos=5&name=StopZmin&version=1.0.0
<-  c=welcome&id=M1F910&type=OzekiTemperatureController&pos=6&name=HeaterExt1&version=1.0.0
<-  c=welcome&id=9o5qzg&type=OzekiSwitchController&pos=7&name=FanExt1&version=1.0.0
<-  c=motorsnumber&count=4&id=6O1KiA&t=0
<-  c=motordetails&axis=x&velocity=9600.00&stepangle=1.80&stepanglediv=16
	&acceleration=131072&id=6O1KiA&t=0
<-  c=motordetails&axis=y&velocity=9600.00&stepangle=1.80&stepanglediv=16
	&acceleration=131072&id=6O1KiA&t=0
<-  c=motordetails&axis=z&velocity=9600.00&stepangle=1.80&stepanglediv=16
	&acceleration=131072&id=6O1KiA&t=0
<-  c=motordetails&axis=a&velocity=9600.00&stepangle=1.80&stepanglediv=16
	&acceleration=131072&id=6O1KiA&t=0
<-  c=welcome&type=Ozeki3DPrinterDisc&id=OZPDSC&version=1.0.0
->  c=setpushinfo&interval=2000&state=1&t=0&id=M1F910
<-  c=setpushinfo_resp&state=1&interval=2000&id=M1F910&t=1
<-  c=heaterinfo&temp=110.44&desiredtemp=-1000.00&state=0&id=M1F910&t=2
<-  c=heaterinfo&temp=121.01&desiredtemp=-1000.00&state=0&id=M1F910&t=3
<-  c=heaterinfo&temp=125.93&desiredtemp=-1000.00&state=0&id=M1F910&t=4
<-  c=heaterinfo&temp=128.28&desiredtemp=-1000.00&state=0&id=M1F910&t=5
<-  c=heaterinfo&temp=129.48&desiredtemp=-1000.00&state=0&id=M1F910&t=6
<-  c=heaterinfo&temp=129.87&desiredtemp=-1000.00&state=0&id=M1F910&t=7
<-  c=heaterinfo&temp=130.47&desiredtemp=-1000.00&state=0&id=M1F910&t=8
<-  c=heaterinfo&temp=131.15&desiredtemp=-1000.00&state=0&id=M1F910&t=9
<-  c=heaterinfo&temp=131.15&desiredtemp=-1000.00&state=0&id=M1F910&t=10
->  c=setswitch&state=1&t=11&id=9o5qzg
<-  c=setswitch_resp&state=1&pwm=254&id=9o5qzg&t=12
<-  c=heaterinfo&temp=131.71&desiredtemp=-1000.00&state=0&id=M1F910&t=13
->  c=setswitch&state=0&t=14&id=9o5qzg
<-  c=setswitch_resp&state=0&pwm=254&id=9o5qzg&t=15
<-  c=heaterinfo&temp=131.65&desiredtemp=-1000.00&state=0&id=M1F910&t=16
<-  c=heaterinfo&temp=132.22&desiredtemp=-1000.00&state=0&id=M1F910&t=17

Avoiding wrong orders

The microcontroller receives wrong orders due to serial buffer overflow or failure of the USB-RS232 chip. The solution for this error:

  • In case of every newer order, event, resp the 't' has to be increased from 0 to 255 and again from 0. This helps to keep count of data traffic. The 't' of ACK is the same with the 't' of the order which it is referred to.
  • Solutions:
    • In case of switching on Checksum:
      Every order gets a short and quickly calculatetable checksum (Fletcher 16 algorithm). The microcontroller checks whether the checksum is correct. If not, then an onerror pdu is sent with a checksum error code. In this case the PC repeats the order. This is the most secure solution for the problem.
    • In case of switching on ACK :
      The microcontroller sends an ACK for every order. If the PC does not get an ACK then it repeats the order. If the checksum is switched on then the ACK contains the checksum. If the checksum is turned off then it is an insecure solution.
      e.g.: 
      //checksum is turned on
c=ack&checksum=d293&t=255&id=M1F910
//checksum is turned off
c=ack&checksum=null&t=255&id=M1F910

For detailed examples please click here

"Link Setup" command

With this command you can toggle the acknowledge message after each command. Also, you can select the checksum algorithm used to validate the commands.

If the checksum algorithm is activated there is a "...&s=abe4\n" on the end of each command. The checksum "abe4" is an example. Be aware that there is no s parameter comming from the microcontroller (command resps events), because the communication in that direction is very stable.

Example

c=linksetup&ack=on&checksum=fletcher16&t=2&id=sf6z34

Parameters

Parameter Type Range Functionality
c String "linksetup" Identifies the command.
windowsize Unsigned Int 0-65535 Optional parameter. The default value is 1. This is the maximum number of commands set in a list on the .net side, so if the microcontroller sends a resp then the next command can be instantly sent to it.
ack String on/off Turn on or off the acknowledgement feature.
checksum String fletcher16/none Selects checksum algorithm.
t Byte 0-255 Counts the number of commands and events sent combined. The 't' of the command is equal to the 't' of its response. Counts from 0 to 255 then from 0 again.
id String 6 characters (numbers, uppercase and lowercase characters) The ID of the IDManager.

ACK

c=ack&checksum=d293&t=2&id=sf6z34

Response

c=linksetup_resp&ack=on&checksum=fletcher16&id=sf6z34&t=3

Parameters

Parameter Type Range Functionality
c String "linksetup_resp" Identifies the response.
windowsize Unsigned Int 0-65535 Optional parameter. The default value is 1. This is the maximum number of commands set in a list on the .net side, so if the microcontroller sends a resp then the next command can be instantly sent to it.
ack String on/off On if acknowledgement feature is on, otherwise off.
checksum String fletcher16/none Shows which algorithm is selected.
id String 6 characters (numbers, uppercase and lowercase characters) The ID of the IDManager.
t Byte 0-255 Counts the number of commands and events sent combined. The 't' of the command is equal to the 't' of its response. Counts from 0 to 255 then from 0 again.

There is no ACK from the PC

The communication from the Arduino to the PC has nearly no mistake. This is why we don't need any ACK.



III. Event from the device

"Link Setup" event

It is basically the same as the "linksetup" command. The difference is that this event is sent from the microcontroller usually at the bootup (you can set it in the .ino file).

Example

c=linksetup&windowsize=1&ack=on&checksum=fletcher16&t=2&id=sf6z34

Parameters

Parameter Type Range Functionality
c String "linksetup" Identifies the command.
windowsize Unsigned Int 0-65535 The default value is 1. This is the maximum number of commands set in a list on the .net side, so if the microcontroller sends a resp then the next command can be instantly sent to it.
ack String on/off Turn on or off the acknowledgement feature.
checksum String fletcher16/none Selects checksum algorithm.
t Byte 0-255 Counts the number of commands and events sent combined. The 't' of the command is equal to the 't' of its response. Counts from 0 to 255 then from 0 again.
id String 6 characters (numbers, uppercase and lowercase characters) The ID of the IDManager.

More information