Inspector datagram

From Java4c

Contents 1 Telegram-structure 1.1 Basic elements used in the datagram for inspector-data-communication 1.2 Presentation of string-given pathes 1.3 Items in datagrams, commands and its answer 1.4 Request the structure of data 1.5 Request a value 1.6 Set a value 1.7 Store sets of pathes in a target or reflection unit (agents) 1.7.1 Create a file for agent items 1.7.2 Get a value and save 1.7.3 Set a value and save (persistent) 1.7.4 Request the content of a agent 1.7.5 Closes a file for persist values 1.8 General Syntax of a whole telegram

[edit] Telegram-structure

If Ethernet is present, UDP-telegrams are used. The same informations as datagram can be transfered inside a hardware with dual-port-RAM-access, or in older or cheeper systems with serial link (RS232), or adequate.

Any datagram consist of a unified header of 16 Byte. After them so named //information units// are disposed. Any information unit consists of a header of 8 byte, following by different data. The header contains the length of the information unit.

The components of the datagram are defined for C/C++-usage in the headerfile //DataExchange_Inspc.h//.

cJ8LJ2 I subscribed to RSS, but for some reason, the messages are written in the form of some hieroglyph (How can it be corrected?!...

[edit] Basic elements used in the datagram for inspector-data-communication

//**InspcDatagram::=<@HEADSIZE=16> <@0+2:SIZE?nrofBytes> <@2+2?entrant="> <@4+4?encryption> <@8+4?seqnr> <@12+1?" answerNr=" <@13+3?reserve>.**//

It is the head of any datagram.

• entrant: is an identifier of the instance inside a target which should be addressed. TODO: Note: It is a negative number yet, to distinguish to the headless telegrams.
• encryption: is an information for encryption of the content after this head. Note: The encryption is planned but not designed yet.
• seqnr: identifies a telegram and its associated answer telegram. In generally, a command-datagram should use any number which is unique for a longer time. The answer should mirror this same number. This is the only contract. In addition, the number can be built with the current timestamp. The bits 31..4 contains the current milliseconds after 1970 (fractional part) and the bits 3..0 may be count more as one telegram in the same millisecond. The same sequence number can be occured after 4 days, this is a long enough distance of time. The time information can be used for debugging.
• answerNr: A answer telegram may be consist of more as one UDP-Telegram. The first telegram in numbered by 1. The next telegram is countered here. The last telegramm is dedicated by set bit 7. It means, if the answer consists of one telegram, it has the value 0x81 here. If the answer consists of 2 telegrams, there are numbered here with 0x01, 0x82. If the receiver doesn't get all telegrams (lost telegrams), than the command should be repeated.

//**Item::=<@HEADSIZE=8> <@0+2:SIZE?nrofBytes> <@2+2?cmd> <@4+4?order>.**//

It is the head for any information unit inside a <InspDatagram>...</InspDatagram>. An <Item> can have children. So the general form of a datagram may be written as

//**<InspDatagram><Item:>...<:Item><Item:>...<:Item></Datagram>.**//

The superior componentes with <Item> as head are subtly differentiated and named with an own syntactical name. See for example <cmdValueByPath>.

//**ItemAckn::=<Item cmd=1 />.**//

//**ItemNackn::=<Item cmd=1 />.**//

Acknowledge or non-acknowledge answer to a request. If the answer should have data, the data are returned, or the <ItemNackn> is returned if the cmd isn't able to proceed. The <ItemNack> contains the order-number to assign the request. Especially if a path is false, a <ItemNackn> is returned.

//**Value8byte::=<@SIZE=8> [ <@0+4:float?float> | <@0+8:double?double> | <@0+8?long> | <@4+4?int> | <@6+2?short> | <@7+1?byte>].**//

A <Value8byte>-value is a pure value in 8 bytes. In case of float, 4 bytes are unused. In case of integer with less bytes as 8, it is the same as long in big-endian-presentation. TODO setting of char16? The type of data isn't described in this element. Normally the operator (GUI) knows the type of the element inside the target and prepares the proper type for the target.

//**TypeId::=<@SIZE=1?> <@0+0?id>**//

It is one byte which contains the identification for a type.

//**int64Value ::=<@SIZE=9?> <TypeId id=0xe2> <@1+8?value>.**//

//**uint64Value::=<@SIZE=9?> <TypeId id=0xe3> <@1+8?value>.**//

//**int32Value ::=<@SIZE=5?> <TypeId id=0xe4> <@1+4?value>.**//

//**uint32Value::=<@SIZE=5?> <TypeId id=0xe5> <@1+4?value>.**//

//**int16Value ::=<@SIZE=3?> <TypeId id=0xe6> <@1+2?value>.**//

//**uint32Value::=<@SIZE=3?> <TypeId id=0xe7> <@1+2?value>.**//

//**int8Value  ::=<@SIZE=2?> <TypeId id=0xe8> <@1+1?value>.**//

//**uint8Value ::=<@SIZE=2?> <TypeId id=0xe9> <@1+1?value>.**//

//**floatValue ::=<@SIZE=5?> <TypeId id=0xec> <@1+4:float?value>.**//

//**doubleValue::=<@SIZE=9?> <TypeId id=0xed> <@1+8:double?value>.**//

//**char8Value  ::=<@SIZE=2?> <TypeId id=0xee> <@1+1?value>.**//

//**char16Value  ::=<@SIZE=3?> <TypeId id=0xef> <@1+2?value>.**//

//**boolValue  ::=<@SIZE=2?> <TypeId id=0xf6> <@1+1?value>.**//

They are representations of the primitive values. The values are the image of the bit representation of the type in the hardware. It is written in big-endian always! The first byte is the type-identifier-byte.

//**StringValue::= <TypeId id:SIZE=1..0xbf> { <@*?char> }</TypeId>.**//

The length of the StringValue is the number of chars +1, because the length-information counts the length-byte too.

[edit] Presentation of string-given pathes

//**PathValue::=[{ <$?fieldIdent> [**// {{{[}}}//**<#?index>**//{{{]}}}//** | [<?questCollectionSize> **//{{{[?]}}}//** | **//{{{<?>}}}//** ] |]**// {{{.}}}//** }| **//{{{.}}}//** ].**//

The <PathValue> describes the access to any element inside the structure of data. It is given as string of chars. Examples for valid paths are:

• ".": The first node
• "myAppl.data.": deeper node.
• "myAppl.x[10]." : an element of an array
• "myAppl.x[10].a." : an element inside an array-element
• "myAppl.x[?]." : The container x is asked to his collection size.
• "myAppl.x<?>." : The same above, the <> should associate a non-array-container, a List or Map

ZBNF-syntax-notification:

• The <$?fieldIdent> denotes an //identifier// with the meaning //fieldIdent//.
• An index is optional for any <$fieldIdent>. The notification in [...] means an option, like usual in BNF.
• The notification of \[ and \] means the brackets as characters in the text. <#?index> denotes a number with meaning //index//.
• {...} is a repetition, passing at least one time. [...|...] is the choiceable-option.

[edit] Items in datagrams, commands and its answer

[edit] Request the structure of data

//**cmdGetFields::=<Item cmd=0x10:><PathValue><:Item>.**//

/**anwerFields::={ <Item cmd=0x14:><$?Fieldident>[ \[ <#?fixArraySize> | ? <?dynamicArray> \] | \<?\> <?container> |]<:Item> }.**//

The command supplies a path. The answer consists of more as one Item, all with the same order-id, one item describes one field of the requested data structure. TODO the real-type is not answered. it is only able to guess from the elements and from the type of the reference. If the reference is the same, it may be ok. But for derived classes the type should be returned too.

[edit] Request a value

//**cmdValueByPath::=<Item cmd=0x30:><PathValue><:Item>**//

//**answerValue::=<Item cmd=0x26:> [ <int64Value> | <uint64Value> | <int32Value> | <uint32Value> | <int16Value>| <uint16Value> | <int8Value> | <uint8Value> | <floatValue> | <doubleValue> | <char8Value> | <boolValue> | <StringValue> ] <:Item>.**//

<cmdValueByPath> is a part inside <InspDatagram>...<cmdValueByPath />...</InspDatagram>, which is send from the operator to the target. The targets sends an answer telegram which contains <InspDatagram>...<answerValue />...</InspDatagram>. The Item.order is reflected from the cmd to the answer. The InspDatagram.seqnr is reflected from the cmd telegram to the answer telegram. There can be more as one command in one Datagram from operator to target, which is anwered in one datagram with all answers.

<cmdValueByPath> requests the value of the given path. The answer is given in the form <answerValue>. If the last element of the path is a primitive numeric value, then its value is answered in the binary representation. If the element is a character string, the contained String is returned, but maximal the first 191 characters. If the element is a complex one and it based on Object, the toString()-method is invoked which returns a string. In the other case the address of the element is returned as String in form "@address".

[edit] Set a value

//**SetValueByPath::=<Item cmd=0x35:> <Value8byte /> <PathValue /> <:Item>**//

//**<answerValue>**//

The answer is <answervalue> where the re-read value is returned. The type of value should be correct given. The value is set in the target with the given bytes in <Value8byte> without conversion.

[edit] Store sets of pathes in a target or reflection unit (agents)

A target may store some pathes, which is a agent at the GUI. It is possible that this are set-values (path + value), which are executed in the target device on startup automatically to set initial values or parameter.

[edit] Create a file for agent items

//**cmdCreateAgentFile::=<Item: cmd=0x50 > <$/\.?filepath> <:Item>. **//

//**answerCreateAgentFile: <Item cmd=0x51 :> <@8+2?nrFile> <:Item>.**//

It opens respectively creates a file to store persistent values. An existing file will be deleted. It means the stored persistent pathes with their values are removed from the target. The intension is, send newly. The filepath may consist of / as separator of directories and dots for extension. The possibilities of filepath-notifications depends on the ability of the target system. There may be a simple file system which accepts only deterministic names.

The answer returnes a number in positive range as handle, which have to be used for the items of the agent.

If the command is repeated by the same source, it is repeately executed. If the command is sent from another source, while the same file is opened, a negativ acknowledge is returned.

If a negativ acknowlege is returned, the same answer but with nrFile = -1 is sent.

[edit] Get a value and save

//**cmdGetAgentValueByPath::=<Item cmd=0x56:> <@8+2?nrFile> <Value8byte /> <PathValue /> <:Item>**//

//**<answerValue>**//

The answer is <answerValue> with the actual content. Additinally the Item is stored in the file of agent.

[edit] Set a value and save (persistent)

//**cmdSetPersistValueByPath::=<Item cmd=0x54:> <@8+2?nrFile> <Value8byte /> <PathValue /> <:Item>**//

//**<answerValue>**//

The answer is <answervalue> where the re-read value is returned. The type of value should be correct given. The value is set in the target with the given bytes in <Value8byte> without conversion. This Item is registered in a persistent-agent-file inside the target device. Its number is given in nrFile in the datagram. The file should be opened and closed with extra items in another datagrams.

[edit] Request the content of a agent

//**cmdRequestAgent::=<Item cmd=0x58:><$/\.?filepath> <:Item>. **//

The answer consists of

//**answerRequestAgent::={<InspcDatagram:>{<answerAgentSetItem>|<answerAgentGetItem>}<:InspcDatagram>}**/

It means, all stored <answerAgentItem> in the requested file are returned in one or more Datagrams.

//**answerAgentSetItem::=<Item cmd=0x59:> <@8+2?nrFile> <Value8byte /> <PathValue /> <:Item>**//

The value is the value which is stored. The answer doesn't access to data.

//**answerAgentGetItem::=<Item cmd=0x5b:> <@8+2?nrFile> <PathValue /> <:Item>**//

The item contains only the path. The answer doesn't access to data.

[edit] Closes a file for persist values

//**cmdCloseAgentFile::=<Item cmd=0x52:> <@8+2?nrFile> <:Item>. **//

//**answerCloseAgentFile::= <Item cmd=0x53>. **//

The file is closed now. Following requests <SetPersistValueByPath> are answered with <ItenNackn> and they are not executed. TODO should they set non-persistent?

The file will be closed automatically if no close command is received in a timeout time, which depends on the target. It is about a few seconds. It means, if the communication is aborted, no problem occurs. The behaviour of the target is **stateless**, after the timeout. But the agent file may be confuse then because not all items are stored.

[edit] General Syntax of a whole telegram

WholeInspDatagramToTarget::=<InspDatagram> { <cmdValueByPath> | <cmdGetFields> | <TODO> } </InspDatagram>.

WholeInspDatagramFromTarget::=<InspDatagram> { <answerValue> | <TODO> } </InspDatagram>.