KONNEKTING Protocol Specification 0x01

Workflow

The following describes the workflow for programming a KONNEKTING device. The diagrams show the required actions the programming device (f.i. KONNEKTING Suite) needs to do in order to program a KONNEKTING device.

Start Programming Mode

Before the programming can start, the KONNEKTING device needs to be in "programming mode" (short: ProgMode). The following diagram describes the two possible ways to achive ProgMode.

Do Programming

After ProgMode has been achived, it's time to do the actual device programming. For getting an answer for the "... changed?" decision-blocks, a comparison between the "DeviceMemory" section (see: https://gitlab.com/konnekting/KonnektingXmlSchema/blob/develop/src/main/xsd/KonnektingDeviceV0.xsd) of .kconfig.xml with the data the application wants to write. If there are any differences, data has to be written. Either complete, or only the blocks with changes (will speed up programming a lot, especially for small changes).

The parts for "Program CommObjects" and "Program Parameters" are optional an depend on what the user want to program. So you can skip or include them, as you like.

Working with files

This is about working with files, means transfering files to the device, including firmware upgrade

todo ...

Device Memory Layout

The device's memory is divided in multiple sections:

Hints:

• The AddressTable is sorted by the GroupAdress ascending by its integer value.
• The AssociationTable is sorted by the GroupAddress ID ascending by its integer value.

System Table

• Total table size in bytes: 32 bytes, first 16 bytes: fixed, read only; next 16 bytes: variable, readable/writeable

Access Mode	Table Byte Index	Description
R	0	version byte HI
R	1	version byte LO
R	2	#Device Flags
R	3	#GroupAddress Table address HI
R	4	GroupAddress Table address LO
R	5	#Association Table address HI
R	6	Association Table address LO
R	7	#CommObject Table address HI
R	8	CommObject Table address LO
R	9	#Parameter Table address HI
R	10	Parameter Table address LO
R	11..15	0xFF, unused
R/W	16	IndividualAddress HI
R/W	17	IndividualAddress LO
R/W	18..31	0xFF, unused

Device Flags

b7 ist the left most bit, b0 is the right most bit.

bit	hex mask	Description
b7	0x80	Factory Flag: 1 = factory settings 0 = stored settings
b6		IA set
b5		CO set
b4		Params set
b3		data storage in use
b2..b0	n/a	unused

GroupAddress Table

• Total table size in bytes: 1+(n*2) bytes, where n = GroupAddress limit, see #System_Type

Table Byte Index	Description
0	number of filled entries in table
1	GroupAddress 0 HI
2	GroupAddress 0 LO
3	GroupAddress 1 HI
4	GroupAddress 1 LO
5	GroupAddress 2 HI
6	GroupAddress 2 LO
...	...

Association Table

• Total table size in bytes: 1+(n*2) bytes, where n = GA-CommObj relation limit, see #System_Type

Table Byte Index	Description
0	number of filled entries in GA<->CommObj relations table
1	GroupAddress ID Nr.1
2	CommObj ID Nr.1
3	GroupAddress ID Nr.2
4	CommObj ID Nr.2
5	GroupAddress ID Nr.3
6	CommObj ID Nr.3
...	...

CommObject Table

• Total table size in bytes: 1+(n) bytes, where n = CommObjects limit, see #System_Type

Table Byte Index	Description
0	number of existing CommObjects
1	config byte (see below) of CommObject ID 0
2	config byte of CommObject ID 1
3	config byte of CommObject ID 2
...	...

CommObject config byte

b7 ist the left most bit, b0 is the right most bit.

bit	hex mask	Description
b7	0x80	unused, 0x00
b6		unused, 0x00
b5		C: the Communication flag
b4		R: the Read flag
b3		T: the Transmit flag
b2		W: the Write flag
b1		U: the Update flag
b0		I: the Initialization flag

Parameter Table

• Total table size in bytes: depends on actual by device provided parameters

Table Byte Index	Description
0	...
1	...
2	...
3	...
...	...

User Space

This is the space where user data can be stored. The KONNEKTING Device Library provides an API to query the start address for this user space in memory.

Property Pages

Property pages are blocks information with up to 12 bytes of length. Property pages are read-only and do not directly belong to the device's memory (f.i. EEPROM or Flash). The information is mostly stored in the device firmware.

0x00 Device Info

• Property Page Number: 0 dec / 0x00 hex
• Property Page Name: Device Information

Byte no#	Description
2	Manufacturer-ID HI
3	Manufacturer-ID LO
4	Device-ID
5	RevisionID
6	Device Flags, see below
7	System Type, see below
8..13	0xFF, unused

Device Flags

b7 ist the left most bit, b0 is the right most bit.

bit	hex mask	Description
b7	0x80	Factory Flag: 1 = factory settings 0 = stored settings
b6..b0	n/a	unused

System Type

hex	Name	Description
0x00	System 0 Simple	Up to: 128 GAs 128 GA-ComObj relations 128 ComObjects 128 Parameters Supports Default Frame
0x01	System 1 Default	Up to: 255 GAs 255 GA-ComObj relations 255 ComObjects 255 Parameters Supports FOTB (firmware-over-the-bus) Supports Extended Frame (DRAFT)
0x02	System 2 Extended DRAFT	Up to: 65535 GAs (32*8*256) 65535 GA-ComObj relations 65535 ComObjects 65535 Parameters Supports FOTB (firmware-over-the-bus) Supports Extended Frame

GAs = Unique GroupAddresses
GA-ComObj relations = Assignments of GAs to ComObjects
ComObjects = Number of ComObjects
Parameters = Number of Parameters

Message Types for Protocol-Version 0x01

These are the messages KONNEKTING uses to communicate between the programming device and the KONNEKTING device.

0x00 Acknowledge

• Message Name: Acknowledge
• Message-Type-ID: 0 dec / 0x00 hex
• Direction: Device -> Suite
• Expected Response: n/a
• Description: Sent by device as answer to most WRITE messages
• Requires Programming Mode: n/a

Byte no#	Description
2	Acknowledge Type
3	Error Code
4..13	0xFF, unused

Acknowledge Type

hex	Description
0x00	ACK
0xFF	NACK

Error Code

hex	Description
0x00	ERR_CODE_OK
0x01	ERR_CODE_NOT_SUPPORTED
0x02	-
0x03	-
0x04	-
0x05	-
0x06	-
0x07	-
0x08	} 0x01 PropertyPageRead Message Name: PropertyPageRead Message-Type-ID: 1 dec / 0x01 hex Direction: Suite -> Device Expected Response: #0x02 PropertyPageResponse Description: Read one page of property data Requires Programming Mode: no Byte no# Description 2 addressflag: 0x00=only reply when progmode is set; 0xFF=only reply if following IA does match 3 IndividualAddress HI; 0xFF/unused if b[2]=0x00 4 IndividualAddress LO; 0xFF/unused if b[2]=0x00 5 property page num, 0x00..0xFF, see #Property Pages for more details 6..13 0xFF, unused 0x02 PropertyPageResponse Message Name: PropertyPageResponse Message-Type-ID: 2 dec / 0x02 hex Direction: Device -> Suite Expected Response: n/a Description: One page of property data Requires Programming Mode: no Byte no# Description 2..13 12 bytes of property page data, see #Property Pages for more details 0x08 Unload Message Name: Unload Message-Type-ID: 8 dec / 0x08 hex Direction: Suite -> Device Expected Response: #0x00 Acknowledge Description: Unload device Requires Programming Mode: yes Byte no# Description 2 Unload Indivdual Address, 0x00 = false, 0xFF=true 3 Unload ComObjects, 0x00 = false, 0xFF=true 4 Unload Parameters, 0x00 = false, 0xFF=true 5 Unload data storage (see: #0x28 DataWriteprepare etc), 0x00 = false, 0xFF=true 6..13 0xFF, unused 0x09 Restart Message Name: Restart Message-Type-ID: 9 dec / 0x09 hex Direction: Suite -> Device Expected Response: #0x00 Acknowledge Description: Restart device (device reboot, no memory reset) Requires Programming Mode: no Byte no# Description 2 IndividualAddress HI 3 IndividualAddress LO 4..13 0xFF, unused 0x0A ProgrammingModeWrite Message Name: ProgrammingModeWrite Message-Type-ID: 10 dec / 0x0A hex Direction: Suite -> Device Expected Response: #0x00 Acknowledge Description: Sets/Unsets Programming-Mode for device with given individual address. Device will respond with a "Acknowledge" message. Requires Programming Mode: no Byte no# Description 2 IndividualAddress HI 3 IndividualAddress LO 4 Mode: 0x00 = OFF 0x01 = ON 5..13 0xFF, unused 0x0B ProgrammingModeRead Message Name: ProgrammingModeRead Message-Type-ID: 11 dec / 0x10 hex Direction: Suite -> Device Expected Response: #0x0C ProgrammingModeResponse Description: Reads current programming mode of all listening devices. If more than one device is in programming-mode, you will get more then one #0x0C ProgrammingModeResponse messages. Requires Programming Mode: no Byte no# Description 2..13 0xFF, unused 0x0C ProgrammingModeResponse Message Name: ProgrammingModeResponse Message-Type-ID: 12 dec / 0x11 hex Direction: Device -> Suite Expected Response: n/a Description: Response to ProgrammingModeRead message. Requires Programming Mode: n/a Byte no# Description 2 IndividualAddress HI 3 IndividualAddress LO 4..13 0xFF, unused 0x1E MemoryWrite Message Name: MemoryWrite Message-Type-ID: 30 dec / 0x1E hex Direction: Suite -> Device Expected Response: #0x00 Acknowledge Description: Write data to device memory Requires Programming Mode: yes Byte no# Description 2 Count: Number of bytes to write to memory, starting at "Address" 3 Address uint16[0] HI 4 Address uint16[1] LO 5..13 1..9 bytes of Data, depends on "Count". Remaining bytes: 0xFF 0x1F MemoryRead Message Name: MemoryRead Message-Type-ID: 31 dec / 0x1F hex Direction: Suite -> Device Expected Response: #0x20 MemoryResponse Description: Reads data from device memory Requires Programming Mode: yes Byte no# Description 2 Count: Number of bytes to read from address. Range 1..9 3 Address HI 4 Address LO 5..13 0xFF, unused Memory Tables With help of #0x1F MemoryRead and #0x1E MemoryWrite one can access the device's memory (EEPROM, flash, ...). The memory stores different tables for different usage. As both messages access memory by memory address, one has to know at which address which table starts. To get the start addresses of all tables, see #0x01 PropertyPageRead and #0x01 Table Addresses. 0x20 MemoryResponse Message Name: MemoryResponse Message-Type-ID: 32 dec / 0x20 hex Direction: Device -> Suite Expected Response: n/a Description: Response to MemoryRead Requires Programming Mode: yes Byte no# Description 2 Count: Number of bytes that have been read from address 3 Address HI 4 Address LO 5..13 1..9 bytes of Data, depends on "Count". Remaining bytes: 0xFF 0x28 DataWritePrepare Message Name: DataWritePrepare Message-Type-ID: 40 dec / 0x28 hex Direction: Suite -> Device Expected Response: #0x00 Acknowledge Description: prepare writing data Requires Programming Mode: yes Byte no# Description 2 Data Type, see below 3 Data ID unique identifier for the data 4 size of data uint32[0] 5 size of data uint32[1] 6 size of data uint32[2] 7 size of data uint32[3] 8..13 unused, 0xFF Data Type hex Name Data ID range Description 0x00 UPDATE always 0x00 Firmware update for KONNEKTING device 0x01 DATA 0x00..0xFF f.i. additional configuration, images, sounds, ... 0x29 DataWrite Message Name: DataWrite Message-Type-ID: 41 dec / 0x29 hex Direction: Suite -> Device Expected Response: #0x00 Acknowledge Description: Writing data Requires Programming Mode: yes Byte no# Description 2 Count: 1..11 bytes 3..13 1..11 bytes of Data, depends on "Count". Remaining bytes: 0xFF Notes: 0x2A DataWriteFinish Message Name: DataWriteFinish Message-Type-ID: 42 dec / 0x2A hex Description: finish writing data Requires Programming Mode: yes Byte no# Description 2 CRC32[0] 3 CRC32[1] 4 CRC32[2] 5 CRC32[3] 6..13 unused, 0xFF Notes: 0x2B DataRead Message Name: DataRead Message-Type-ID: 43 dec / 0x2B hex Direction: Suite -> Device Expected Response: #0x2C DataReadResponse, providing the size, followed by n times #0x2D DataReadData until end of data and finally again #0x2C DataReadResponse, providing the CRC32 Description: trigger reading data Requires Programming Mode: yes Byte no# Description 2 Data Type range: 0x01..01FF (0x00 can't be read, as this is firmware) 3 Data ID unique identifier for the data to read 4..13 unused, 0xFF 0x2C DataReadResponse Message Name: DataReadResponse Message-Type-ID: 44 dec / 0x2C hex Direction: Device -> Suite Expected Response: n/a Description: meta data about the requested data. The actual data will follow in separate messages (#0x2D DataReadData) Requires Programming Mode: yes Byte no# Description 2 Data Type 3 Data ID unique identifier for the data 4 size of data uint32[0] 5 size of data uint32[1] 6 size of data uint32[2] 7 size of data uint32[3] 8 CRC32[0] 9 CRC32[1] 10 CRC32[2] 11 CRC32[3] 12..13 unused, 0xFF 0x2D DataReadData Message Name: DataReadData Message-Type-ID: 45 dec / 0x2D hex Direction: Device -> Suite Expected Response: #0x00 Acknowledge Description: packet of requested data from device. Device will send several messages of this type until whole data is transferred Requires Programming Mode: yes Byte no# Description 2 Count: 1..11 bytes 3..13 1..11 bytes of Data, depends on "Count". Remaining bytes: 0xFF 0x2E DataRemove Message Name: DataRemove Message-Type-ID: 46 dec / 0x2E hex Direction: Suite -> Device Expected Response: #0x00 Acknowledge Description: remove previously stored data Requires Programming Mode: yes Byte no# Description 2 Data Type range: 0x01..0xFF 3 Data ID unique identifier for the data 4..13 unused, 0xFF Notes: