Hinweis für die Textformat-Version; um diese Version im PDF Format zu lesen, laden Sie bitte https://www.dk1ri.de/myc/Reserved_tokens.pdf

MYC Reserved Commands

Author: DK1RI
Version V01.20.14 20260616
This paper is published in https://github.com/dk1ri as well

Introduction

This paper describes the reserved commands of the MYC protocol.
For introduction to the MYC system and additional documentation see https://dk1ri.de/myc/MYC.pdf  (german) and https://dk1ri.de/myc/MYC.en.pdf
For details of the commands see https://dk1ri.de/myc/commands.txt or https://dk1ri.de/myc/commands.pdf

Definitions and formats

see https://dk1ri.de/myc/Definitions.txt or https://dk1ri.de/myc/Definitions.pdf

Overview

Every MYC device should provide reserved command tokens and understand them, if applicable. Some are  mandatory.
The set of announcements of a MYC device should be in numerical sequence, start with the reserved basic command 0x00 and end with the other reserved tokens 0xxxf0 - 0xxxff. Rules lines may follow. In the full anouncment-list of CR the last line of each device is the I-announcement. This is necessary, to identify commands in systems with hierarchical (stacked) command-routers.

Fourteen of the reserved tokens are used and defined now: 0x00, 0xxxf0, 0xxxf1 and 0xxxf4 – 0xxxff.
Some reserved word are used. They should use uppercase characters.

Basic Command 0x00

The one byte 0x00 basic command is mandatory for all MYC devices.

The basic announcement is called with the one byte command 0x00.
announce:	0;<dt>;MANUFACTURER;DEVICEDESCRIPTION;VERSION;NUMBER_OF_DEVICES;LINELENGTH; COMMAND_BYTES;NUMBER_OF_ANNOUNCEMENTS;SPEC_VERSION

command:	0x00
answer / info:	0x00<basic announcement line>	<basic announcement line> as string <s> (with one byte length)	

The announcement is fixed and therefore the announce-line do not describe the format of the command but is the content, which is transmitted as answer of the command 0x00.
The length of the string is a one byte string-length. The 0x00 announcement is limited therefore to 255 Bytes.

MANUFACTURER, DEVICEDESCRIPTION and VERSION are combined to a devicegroupname and are used in file names, so not all character are allowed. Preferred is a-z, A-Z, 0-9, _ . Others will be not allowed by use with the CR.		
These devicegroupnames are unique to a device and its firmware and announcelist. A (published) device / firmware combination with a devicegroupname must not be changed. If changes are necessary, a new version must be used. Each device with its individualization belongs to a devicegroup. So, this is valid also for controlled programs, but not for controlled CR and not for all controlling devices.
For a normal FU  NUMBER_OF_DEVICES is 1, For CR it is CR + all FU + RU + number given by lower level CR. This value is important for the command-router as info for a higher level CR.
LINELENGTH is the maximum line-length of the announcement lines.
COMMAND_BYTES  is the number of bytes used for command transmiision. Allowed values are 1 to 8; usually one or two are used.
NUMBER_OF_ANNOUNCEMENTS includes “R” “L” and “I” lines. This is the number of all announcements. An announcement can have more than one line. The length for transmiison may bedifferent from COMMAND_BYTES.
 A different transmission length of this number result in a CR startup procedure: see http://dk1ri.de/myc/Description.pdf.
A (translated) 0x00 command of a device is answered by the CR itself and not send to the device for answer.
SPEC_VERSION is the version of specification, the device is designed for: <branch>-<version>. <version> is a set of specification defined in [13]. Within a branch the CR must be compatible to a specific <version> and all lower  <versions>.

Announcement Command 0xxxf0

The 0xxxF0 announcement command is mandatory for all MYC devices.  ANNOUNCEMENTS must be the 1st <des>.

announce:	240;an,ANNOUNCEMENTS,<des>...<des>;<LINELENGTH>:<START_AT>;<NUMBER_OF_ANNOUNCELINES>	
															(240 for 1 byte command-token)
command:	0xxxf0<n><m>											ask for m announcement lines starting at 
															position n
answer / info:	0xxxf0<n><m><data>

<n> is a positional parameter of the memory. The number of bytes for <m> and <n> must not exceed <NUMBER_OF_ANNOUNCELINES>.
< NUMBER_OF_ANNOUNCELINES> is the number of the announcement lines including those for the reserved commands, rules and for the CR the I-lines. The length of <m> and <n> is defined by NUMBER_OF_ANNOUCEMENTS, The length may be higher than the length of commands.

The length of  each announceline is limited to 254 Byte. If a command require more bytes, the line must be splitted to more lines with identical command-token and command-type.
The CR will ask for the full announce-lists of all devices using the 0xxxf0 command once and store them, if it do not have them already. The CR knows the number of lines by the basic command. It will drop the 0xxxf0 command of other devices when building the complete list. The command-router answers all announcement commands by itself using the full list with translated command-token. The CR will  ignore 0xxxf0 infos of devices; 
The CR will not include “r” and “s” commands in the full list but skip these numbers instead. The command-token are reserved for the delivering devices. Exception: the LD will get the list with the complete “r” and “s” commands.

Announcement Command 0xxxf1

The 0xxxf1 announcement command is used by the CR only. BASIC ANNOUNCEMENTS must be the 1st <des> . The CR delivers the basic anoouncmnts of attached devices.
 Announce:
241;an,BASIC ANNOUNCEMENTS;>LENGTH;<NUMBER_OF_DEVICES>;<NUMBER_OF_DEVICES>
command:
0xxxf1<n><m>			ask for basic m announcement lines start at n (“0” based)  and  must not exceed <NUMBER_OF_DEVICES> 
answer / info:
0xxxa1<n><m><data>
 
Feature for SK 0xxxf9

This is command of the CR and used by the SK only for information for the CR . SK-FEATURE must be the 1st <des>.

Announce: 249;oa,SK-FEATURE[,<des>];<ty>,<OPTION>[,<des>]...
command;	0xxxF9<n><data>
answer / info:	-

defined <OPTION>:
<b>,STOP					The SK will send 0xf90xxx0xf01 to signal, that the input buffer is full and further data 
						are ignored. Default: 0x00
<s>,  BASIC ANNOUNCEMENTS		CR will send a string with length of <S>, containing all basic announceline, each strtin with its length.
						The length of  the length of the commands is that for the cpmplete string
<s>,ADMIN  ANNOUNCEMENTS		as above for admin  announceline

Features Command 0xxxfa

This is not a command but a description announcement of optional additional feature and properties of a device-group, which cannot be modified.
This line is optional and not forwarded by the CR, if all <OPTION> are used by the CR only.
The command announcement has the 1st <des> "FEATURE". Non default OPTIONS are set only.
The device will not answer to this command.

announce:	250;ia,FEATURE[,<des>]...[,<des>];<ty>,<OPTION>,[<des>..][;...]
command:	-
answer / info	-

Defined <OPTION> are:
b,INFO,<DEFAULT>				FU only. Optional, can be used, if infos are send; must not be defined otherwise
						0:	info used, but no polled interface
						other:	requested info polling time in 10ms. <DEFAULT> is 10 (means 100ms)
<sm>,INFOCOMMANDS			FU  only. The CR should poll the commands given in this ls list
a,MULTI_ANSWER,<DEFAULT>		FU only, Optional, 1, if device can handle multiple answer commands, DEFAULT: 0 for polled devices as
						 I2C, 1 for others. For polled devices with default, the master must get the answer within 1 second. After 
						that time the FU may delete the answer.

w,COMMANDDELAY,<DEFAULT>	in ms, DEFAULT is 100. The CR will wait for this time, before sending another command. This will 
						allow slow devices to handle commands. 0 means, that the device can buffer commands. The FU will not 
						accept commands during that time. The FU will also do so, until all data are sent to the master.
b,ACK,<DEFAULT>				set to “1”: info for HI, that FU will send an answer for all operating commands as an acknowledge.
	
		 
Logon Command 0xxxfb

This LOGON command is a command of the RU only. The SK (user) send the LOGON request and the RU will check the data. Than the RU will send the result on request of the CR using an “aa” command of the RU: 0: granted, 1 denied.  The CR will store the input device of the userand act accord to the “Q” rules.
For more details see http://dk1ri.de/myc/Rules_device.pdf
The command announcement has the first command-type description "LOGON".
NAME and PASSWORD is limited to 255 characters (1 byte length of string), All parameters must be transmitted at the same time.

announce:	251;ob,LOGON[,<des>];a,mode;<s>,NAME;<s>, PASSWORD
mod:		0	log on	
		1	log out
		2	new user passwd or change passwd. Change only, when logged in.
answer	/ info	-

Example:
&HFB0002HGK03ABC

The RU send an info to the CR:
xx: aa,LOGIN_DATA;b	will send 0|1|2
Example:
&H0E02  	

Last Error Command 0xxxfc

This command is mandatory for FU and delivers the last error the device detected. 
The command announcement has the 1st <des>  "LAST ERROR" to identify them in a list with the translated command-token, which is sent by the command-router.
announce:	252;aa,LAST ERROR[,<des>];<s><,des>
command	0xxxfc
answer / info:	0xxxfc<s>
Devices may send error infos. CR do checks on positional and string overflow for data from SK and may send error infos if applicable.
Out of range		sent by CR in case of  positional and string overflow of SK
Other messages to be defined.

Administrative Data Command 0xxxfd

This command deliver administrative data of the device.
Multiple <OPTION> are addressed by position.
The command announcement has the 1st <des>  "MYC INFO".

announce:	253;aa,MYC INFO[,<des>]...[,<des>];<ty>,<OPTION>,[<des>..][;...}
command:	0xxxfd<n><data>		<n> omitted for one element array
answer / info:	253<n><s>|<n>		send info of position m

defined <OPTION>s		Values:
b,ACTIVE					mandatory as first element
				01		not yet ready (after startup)
				03		busy
				04		ready and active
				other <n>	try again in <n> seconds, default try again is 10s
b,ANNOUNCELIST		<n>		(new) list <n> available; for CR only
b,ANSWERTIMEOUT	<n>		for polled devices: After timeout output data are deleted and new commands are executed.
						In 100ms, Default is 10 (1s)	
b,CHANNELTIMEOUT	<n>		used by CR multi-channel interfaces only in seconds.
B, CHANNELNUMBER	<n>		used by CR multi-channel interfaces only default is 0: public channel.
	
more  to be defined.

Individualization Commands 0xxxfe and 0xxxff

The individualization commands are mandatory for all devices except for SK.
These commands write and read the individual properties of a device as names. Names und number differentiates different devices of the same device-group in a system. It also provide availability of communication with the command-router.
The command announcements have the 1st <des>  "INDIVIDUALISATION.

For security reasons the 0xxxfe command should have the OPTION ADMINISTRATION, and is dropped in the full command-list, which is generated by the CR or should be blocked by rules. So these properties cannot not be written during normal usage. They can be written for individualization before the normal usage. 
In systems with more than one hirarchy levels the higher level SK may need some some information about the CR, a command is belonging to.as the devicename of the CR. The CR will add CRname>@<devicename>@ before the original command description, if no “@” is found in the name.
The CR will not change the command-tokens during runtime,  but may do this at new start,  if the sequence of devices within the config file of the CR is modified or lower level CR deliver different data. 

announce:	254;oa,INDIVIDUALISATION[,des];<ty>,<OPTION>,<DEFAULT>…;22,CHAPTER,ADMINISTRATION
command	254<m><data>							<m> is the sequence number of the OPTION (0 based)
answer	/ info:	-

announce:	255;aa,INDIVIDUALISATION[,des];<ty>,<OPTION>[<DEFAULT>]..22,CHAPTER,ADMINISTRATION	
command	255<m>								<m> is the sequence number of the OPTION (0 based))
answer / info:	255<m><data>							parameter <m>

The following is a list of defined OPTIONS; This list is not complete; updates may follow.
The interfaces are the “listen” interface, where commands are accepted. So SK has no interface mentioned.
The FU/CR/RU must privied the interface, but the can be deactivated by setting a bit during individualization. A device will ignore inputs from deactivated interfaces except for the 0xxxfe command.
There maybe <DEFAULT> values for the 255 command. The CR do not use the data for connection to devices, it connects to devices, given in commandrouter_config/connection_of_devices. This may be changed later. The CR listen on interfaces given in the 255announcement.
Multiple interfaces of the same type are allowed. Therefore additional parameters for an interface must directly follow the OPTION for activatition.

<OPTION> optional unless otherwise mentioned		comment:
l is maximum stringlength
l,NAME							actual name, mandatory write/read; < 256 characters must be 1st parameneter
b,NUMBER							actual number, mandatory write/read; must be 2nd parameter
l,DISPLAYSIZE,{<size1>,..}				sizex> something like 16x2, 1024p
a,I2C|RS232|CAN|RC5|RC6|SPI				
 USB|TELNET|HTTP|HTTPS|TERMINAL|			
 SSH|RADIO|FILE						Activation of interfaces 0: not active; 1:  active
								The CR may add a “Mn” to the label if it supports multiuser access (1<n<128)
b,I2CADRESS						{1 to 127}
a,SPI_DATA_ORDER					0:MSB first, 1: LSB first
a,SPI_POLARITY,>						when idle: 0:clock low, 1: clock high
a,SPI_PHASE			

b.RS232_BAUD,{0,19200,...}				Baudrate,. 0 is auto, the CR use auto as default
3,RS232:BITS,{8N1}						something like this, the CR use 8N1  as default
b.RS232_COMPORT						COM Port number

b.USB_BAUD						Baudrate,. 0 is auto
b.USB_COMPORT						COM Port number
											
w,ETH_PORT;						portnumber, (for all ethernet protcols)
s,ETH_ADRESS						IP address or DNS name					
b,ETH_TIMEOUT						Timeout				

l,FILENAME							name for file interface from CR  to device/SK  / from device/SK to CR
								the real used name is: to_name / from_name

b,RC5_ADRESS,{1 to 32}			

b,RC6_ADRESS,<DEFAULT>,{1 to 64}	

b,CAN_ADRESS,<DEFAULT>				

b,RADIO_FREQ,<DEFAULT>				
l,RADIO_NAME,<DEFAULT>				
b,RADIO_TYPE,<DEFAULT>				

I-announcements

One line is added to the end of the full command list. The content should give an indication of the state of the list tho the higher level CR, So the CR will know, that the announcelist is mad by a CR and myx ask for a new  announcelist. The content a string with length and may be a date
“I”;12;202512171610”

Not valid command token

If the output buffer of a device is polled by the CR – in case of I2C for example – and the are no valid data, the    
device will answer with the not valid command token. This token is &H80 for one byte command token; &H8080 for 2 byte …
This token is not used otherwise by the device and not mentioned  in the announcement list.

Copyright

Dieses Dokument darf unverändert kopiert werden.
Die Ideen in diesem Dokument unterliegen der GPL (Gnu Public Licence,V2) soweit keine früheren, anderen Rechte betroffen sind.
Die Verwendung der Unterlagen erfolgt auf eigene Gefahr; es wird keinerlei Garantie übernommen.
This document can be copied without changes.
The ideas of this document can be used under GPL (Gnu Public License, V2) as long as no earlier other rights are affected.
The usage of this document is on own risk, there is no warranty.