Difference between revisions of "KONNEKTING Protocol Specification 0x01"

From KONNEKTING Wiki
Jump to navigation Jump to search
Line 7: Line 7:
 
{{#drawio:Protocol0x01WorkflowProgMode}}
 
{{#drawio:Protocol0x01WorkflowProgMode}}
  
−
=== Start ProgMode ===
+
== Read&Prepare 'System' ==
−
 
 
−
There are two ways to get into prog mode:
 
−
 
 
−
==== Program with existing IA ====
 
−
 
 
−
# Check that no device is in prog mode: [[#0x0B ProgrammingModeRead]] 
 
−
## If a device responds: fail with error message: If we want to program with help of IA, no device must be in prog-mode 
 
−
## if no device responds: all fine, continue.
 
−
# Enable ProgMode on device: [[#0x0A ProgrammingModeWrite]]
 
−
## Ensure that only one device responds
 
−
### if more than one, fail with error message: More than one device with this address
 
−
### if just one: all fine, continue
 
−
 
 
−
 
 
−
==== Program with help of ProgButton ====
 
  
−
# Check that '''exactly one''' device is in prog mode: [[#0x0B ProgrammingModeRead]] 
+
{{#drawio:Protocol0x01WorkflowTables}}
−
## If no device responds: fail with error message: No device in prog-mode found
 
−
## If more than one device responds: fail with error message: More than one device in prog mode found. This is not allowed.
 
−
## If '''exactly one''' device responds: all fine, continue
 
−
 
 
−
=== Verify correct device ===
 
−
 
 
−
# Check Device Info: [[#0x01 PropertyPageRead]] -> [[#0x00 Device Info]]
 
−
# Check manufacturer-id, device-id and revision
 
−
## If no match: Fail with error: Device does not match
 
−
## If match: Fine, continue
 
−
 
 
−
== Read&Prepare 'System' ==
 
  
 
# Read system memory: [[#0x1F MemoryRead]] -> [[#System Table]]
 
# Read system memory: [[#0x1F MemoryRead]] -> [[#System Table]]

Revision as of 13:24, 31 July 2018

Workflow

Start Procedure

It's all about getting the device in prog mode and checking that device is matching.

drawio: Protocol0x01WorkflowProgMode

Read&Prepare 'System'

drawio: Protocol0x01WorkflowTables
  1. Read system memory: #0x1F MemoryRead -> #System Table
  2. store locally
  3. put in updated information, like IA, ...
  4. Write system memory, if changes are detected: #0x1E MemoryWrite

Write CommObjects

  1. Write Address Table, if changes detected
  2. Write Assoc Table, if changes detected
  3. Write CommObj Table, if change detected

Write Params

  1. Write Parameter Table, if change detected

Message Types for Protocol-Version 0x01

--- DRAFT ---
This is the second protocol version (version=0x01), starting with 1.0.0 beta5
--- DRAFT ---

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 no error / no error code available
0x01 PropertyPage not available/invalid
0x02 Memory adress not available/invalid

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 IndividualAddress HI
3 IndividualAddress LO
4 property page num, 0x00..0xFF, see #Property Pages for more details
4..13 0xFF, unused

Property Pages

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 1
Default 		Up to:
  • 256 GAs
  • 256 GA-ComObj relations
  • 256 ComObjects
  • 256 Parameters
0x01 System 2
Simple 		Up to:
  • 128 GAs
  • 128 GA-ComObj relations
  • 128 ComObjects
  • 128 Parameters
0x02 System 3
Extended
DRAFT 		Up to:
  • 65535 GAs (32*8*256)
  • 65535 GA-ComObj relations
  • 65535 ComObjects
  • 65535 Parameters

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

0x01 Table Addresses

  • Property Page Number: 1 dec / 0x01 hex
  • Property Page Name: Information about table addresses
Byte no# Description
2 systemtable HI
3 systemtable LO
4 addresstable HI
5 addresstable LO
6 associationtable HI
7 associationtable LO
8 comobjecttable HI
9 comobjecttable LO
10 parametertable HI
11 parametertable LO
12..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

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: ?? dec / 0x?? 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[1] HI
4 Address uint16[0] LO
5..13 1..9 bytes of Data, depends on "Count". Remaining bytes: 0xFF

0x1F MemoryRead

  • Message Name: MemoryRead
  • Message-Type-ID: ?? dec / 0x?? 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.

System Table

  • Total table size in bytes: 32 bytes, fixed
Table Byte Index Description
0 Device Flags, see below
1 IndividualAddress HI
2 IndividualAddress LO
3..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..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
... ...

CommObjectTable

  • 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 TODO
b6..b0 n/a unused

Parameter Table

  • Total table size in bytes: depends on actual by device provided parameters
Table Byte Index Description
0 ...
1 ...
2 ...
3 ...
... ...

0x20 MemoryResponse

  • Message Name: MemoryResponse
  • Message-Type-ID: ?? dec / 0x?? 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 DataPrepare

  • Message Name: DataPrepare
  • Message-Type-ID: 40 dec / 0x28 hex
  • Direction: Suite -> Device
  • Expected Response: #0x00 Acknowledge
  • Description: prepare update
  • 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]: 1..11 bytes
3..13 1..11 bytes of Data, depends on "Count". Remaining bytes: 0xFF

Notes:

  1. ↑ required to determin the end of data in last DataWrite message

0x2A DataFinish

  • Message Name: DataFinish
  • Message-Type-ID: 42 dec / 0x2A hex
  • Description: finish writing data
  • Requires Programming Mode: yes
Byte no# Description
2 CRC32[0] [1]
3 CRC32[1]
4 CRC32[2]
5 CRC32[3]
6..13 unused, 0xFF

Notes:

  1. ↑ https://github.com/bakercp/CRC32

0x2B DataRemove

  • Message Name: DataRemove
  • Message-Type-ID: 43 dec / 0x2B hex
  • Direction: Suite -> Device
  • Expected Response: #0x00 Acknowledge
  • Description: remove previously stored data
  • Requires Programming Mode: yes
Byte no# Description
2 Data Type
0x01..0xFF[1]
3 Data ID
unique identifier for the data
4..13 unused, 0xFF

Notes:

  1. ↑ 0x00 is reserved for UPDATE
Retrieved from "http://wiki.konnekting.de/index.php?title=KONNEKTING_Protocol_Specification_0x01&oldid=555"