Communication Protocol

Description

Communication message formats and Brownie status codes (EBrStatus).

This section contains all definition related to the generic request-reply protocol used by the Home2L Brownies for TWI (aka i2c) communication. Background information on the protocol can be found in the Home2L Book.

Notes on flash programming:

• A flash page (SPM_PAGESIZE) usually contains multiple memory blocks (of size BR_MEM_BLOCKSIZE).
• The page is written back (only) when the last block of a page is written.
• During flash programming, no EEPROM writes are allowed.
• Flash writes to dangerous addresses (own code) are usually blocked out (brForbidden).

Collaboration diagram for Communication Protocol:

Classes
struct	SBrRequest
	Request message. More...
struct	SBrReply
	Reply message. More...

Macros
#define	BR_MEM_BLOCKSIZE   (1 << BR_MEM_BLOCKSIZE_SHIFT)
	Block size for 'memRead'/memWrite' operations. Note: This value is an integral part of the communication protocol and must not be changed.
#define	BR_REQUEST_SIZE_MAX   ((int) sizeof (TBrRequest))
	Maximum length of a request.
#define	BR_REQUEST_SIZE_MIN   2
	Mminimum length of a valid request.
#define	BR_REPLY_SIZE_MAX   ((int) sizeof (TBrReply))
	Maximum length of a request.
#define	BR_REPLY_SIZE_MIN   1
	Minimum length of a valid reply.
#define	BR_REPLY_SIZE_STATUS   1
	Length of a status-only reply.
#define	BR_OP_REG_READ(REG)   ((0x00 | (REG)))
	Build "register read" opcode.
#define	BR_OP_REG_WRITE(REG)   ((0x40 | (REG)))
	Build "register write" opcode.
#define	BR_OP_MEM_READ(BLKADR)   (0x80 | ((BLKADR) >> 8))
	Build "memory read" opcode.
#define	BR_OP_MEM_WRITE(BLKADR)   (0x90 | ((BLKADR) >> 8))
	Build "memory write" opcode.

Typedefs
typedef struct SBrRequest	TBrRequest
	Request message.
typedef struct SBrReply	TBrReply
	Reply message.

Enumerations
enum	EBrStatus {   brOk = 0 , brIncomplete , brUnchecked , brRequestCheckError ,   brReplyCheckError , brIllegalOperation , brForbidden , brNoBrownie ,   brNoDevice , brNoBus , brNoReply = 0x0f , brEND }

Functions
int8_t	BrRequestSize (uint8_t op)
	Get the size of a request message in bytes, depending on the operation.
void	BrRequestPackage (TBrRequest *msg)
	Complete the message for sending (i.e. add checksum).
EBrStatus	BrRequestCheck (TBrRequest *msg, int8_t bytes)
	Check received message. 'bytes' is the number of valid bytes in the beginning of the message.
int8_t	BrReplySize (uint8_t op)
	Get the size of a reply message in bytes, depending on the operation.
void	BrReplyPackage (TBrReply *reply, int8_t len)
	Complete the reply for sending (i.e. add checksum).
EBrStatus	BrReplyCheck (TBrReply *reply, uint8_t op, int8_t bytes)
	Check received message. 'bytes' is the number of received bytes.

Enumeration Type Documentation

EBrStatus

enum EBrStatus

Communication status.

Enumerator
brOk	Last command executed successfully.
brIncomplete	No or incomplete message/reply received.
brUnchecked	Message complete, but not yet checked for checksum.
brRequestCheckError	Checksum of request incorrect or message too short.
brReplyCheckError	Checksum of reply incorrect or message too short.
brIllegalOperation	Non-existing operation.
brForbidden	Operation not allowed.
brNoBrownie	(for masters) No brownie can be reached under a given address (wrong magic number)
brNoDevice	(for masters) No device can be reached under a given address
brNoBus	(for masters) General I/O error when accessing the TWI bus
brNoReply	A device did not respond anything (SDA remained pulled up -> 0x[f]f)

Definition at line 121 of file interface.h.