pifcamp-2021/osc32_9255/RTArduLink/RTArduLinkDefs.h

200 lines
9.1 KiB
C
Raw Normal View History

2022-05-27 14:57:30 +02:00
///////////////////////////////////////////////////////////
//
// This file is part of RTArduLink
//
// Copyright (c) 2014-2015 richards-tech
//
// Permission is hereby granted, free of charge,
// to any person obtaining a copy of
// this software and associated documentation files
// (the "Software"), to deal in the Software without
// restriction, including without limitation the rights
// to use, copy, modify, merge, publish, distribute,
// sublicense, and/or sell copies of the Software, and
// to permit persons to whom the Software is furnished
// to do so, subject to the following conditions:
//
// The above copyright notice and this permission notice
// shall be included in all copies or substantial portions
// of the Software.
//
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF
// ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
// TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
// PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
// THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
// CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
// OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR
// IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
// DEALINGS IN THE SOFTWARE.
// The RTArduLink communications protocol works by exchanging frames across the host <-> subsystem interface.
// The structure RTARDULINK_FRAME defines the frame structure. There is a 4 byte header for frame level control
// while the remainder is available for higher level message. Note that the structure implies fixed length
// buffers which works well with the subsystem however only the number of bytes actually used are transferred
// across the interface.
//
// Note that there is no flow control at the frame level - it is assumed that the higher level interactions host -> subsystem
// are window 1 acknowledged transfers so that the maximum possible unprocessed frames is equal to the number
// of higher level services. Subsystem -> host transfers are always either responses to host commands or else regular
// status updates so the rate from subsystem to host is controlled by configuration.
//
// The frame integrity is protected by a single byte checksum. To keep things very simple, it is the 2s complement
// of the 8 bit sum of all the bytes in the message array. This is used in conjunction with 0xAA and 0x55 bytes
// to determine correct sync (in case of lost bytes which should not really happen!).
//
// Frame sync is obtained by reading bytes until the 0xAA pattern is seen. If the next byte is not 0x55, keep
// scanning. If it is, assume this byte is messageLength and the next one is the frameCksm value. Read in the
// message array based on messageLength and then calculate the checksum. If the checksum is correct, sync has been
// obtained and the message is valid. Otherwise, start looking for an 0xAA value again.
#ifndef _RTARDULINKDEFS_H
#define _RTARDULINKDEFS_H
// Some defines to cope with compiler differences
#ifndef __cplusplus
#ifndef false
#define false 0
#endif
#ifndef true
#define true 1
#endif
typedef unsigned char bool;
#endif
#ifndef NULL
#define NULL 0
#endif
// Some general purpose typedefs - used especially for transferring values greater than
// 8 bits across the link and avoids endian issues. Assumes processor has 32 bit ints!
typedef unsigned char RTARDULINK_UC2[2]; // an array of two unsigned chars
typedef unsigned char RTARDULINK_UC4[4]; // an array of four unsigned chars
// Port speed codes
#define RTARDULINK_PORT_SPEED_OFF 0 // port is unused
#define RTARDULINK_PORT_SPEED_9600 1 // 9600 baud
#define RTARDULINK_PORT_SPEED_19200 2 // 19200 baud
#define RTARDULINK_PORT_SPEED_38400 3 // 38400 baud
#define RTARDULINK_PORT_SPEED_57600 4 // 57600 baud
#define RTARDULINK_PORT_SPEED_115200 5 // 115200 baud
#define RTARDULINK_PORT_SPEED_COUNT 6 // six codes total
extern unsigned long RTArduLinkSpeedMap[];
//------------------------------------------------------------------------------------------------------
//
// Frame level defs and structure
#define RTARDULINK_FRAME_MAX_LEN 64 // maximum possible length of a frame
#define RTARDULINK_FRAME_HEADER_LEN 4 // 4 bytes in frame header (must correspond with the structure below!)
#define RTARDULINK_MESSAGE_HEADER_LEN 4 // 4 bytes in message header (must correspond with the structure below!)
#define RTARDULINK_MESSAGE_MAX_LEN (RTARDULINK_FRAME_MAX_LEN - RTARDULINK_FRAME_HEADER_LEN) // max length of message
#define RTARDULINK_DATA_MAX_LEN (RTARDULINK_MESSAGE_MAX_LEN - RTARDULINK_MESSAGE_HEADER_LEN)// max length of data field
#define RTARDULINK_MESSAGE_SYNC0 0xAA
#define RTARDULINK_MESSAGE_SYNC1 0x55
#define RTARDULINK_MY_ADDRESS 0 // the subsystem address for local processing
#define RTARDULINK_BROADCAST_ADDRESS 0xffff // the subsystem address for all subsystems
#define RTARDULINK_ADDRESSES 0x1000 // number of addresses
// RTARDULINK_MESSAGE is carried in the RTARDULINK_FRAME
//
// The messageAddress field allows subsystems to be daisy-chained. Valid addresses are 0 to 65534.
// Address 65535 is a broadcast and goes to all subsystems.
// Every message has the messageType and messageParam bytes but there can be from 0 to 56 bytes of data
typedef struct
{
RTARDULINK_UC2 messageAddress; // subsystem message address
unsigned char messageType; // message type code
unsigned char messageParam; // an optional parameter to the message type
unsigned char data[RTARDULINK_DATA_MAX_LEN]; // the actual data! Length is computed from messageLength.
} RTARDULINK_MESSAGE;
// RTARDULINK_FRAME is the lowest level structure used across the RTArduLink
typedef struct
{
unsigned char sync0; // sync0 code
unsigned char sync1; // sync1 code
unsigned char messageLength; // the length of the message in the message field - between 4 and 60 bytes
unsigned char frameChecksum; // checksum for frame
RTARDULINK_MESSAGE message; // the actual message
} RTARDULINK_FRAME;
// RTARDULINK_RXFRAME is a type that is used to reassemble a frame from a stream of bytes in conjunction with RTArduLinkReassemble()
typedef struct
{
RTARDULINK_FRAME *frameBuffer; // the frame buffer pointer
int length; // current length of frame
int bytesLeft; // number of bytes needed to complete
bool complete; // true if frame is complete and correct (as far as checksum goes)
} RTARDULINK_RXFRAME;
// Message types
// RTARDULINK_MESSAGE_POLL
//
// The host should poll the RTArduLink at every RTARDULINK_POLL_INTERVAL.
// The subsystem will respond by echoing the poll message as received.
#define RTARDULINK_MESSAGE_POLL 0 // poll message
// RTARDULINK_MESSAGE_IDENTIFY
//
// The host can send this message to request an identity string from the subsystem.
// Only the messageType field is used in the request host -> subsystem. The subsystem
// responds with an identity string in the data field.
#define RTARDULINK_MESSAGE_IDENTITY 1 // identity message
// RTARDULINK_MESSAGE_DEBUG
//
// This can be used to send a debug message up to the host. The data field contains a debug message
#define RTARDULINK_MESSAGE_DEBUG 2 // debug message
// RTARDULINK_MESSAGE_INFO
//
// This can be used to send an info message up to the host. The data field contains the message
#define RTARDULINK_MESSAGE_INFO 3 // info message
// RTARDULINK_MESSAGE_ERROR
//
// This code is returned by the subsystem if it received a message with an illegal message type
// The first byte of the data is the error code. The rest of the data field depends on the error.
#define RTARDULINK_MESSAGE_ERROR 4 // illegal message type response
// RTARDULINK_MESSAGE_ECHO
//
// This message can be used to test link performance. The addressed subsystem just returns
// the entire message to the host.
#define RTARDULINK_MESSAGE_ECHO 5 // echo message
// RTARDULINK_MESSAGE_CUSTOM
//
// This is the first message code that should be used for custom messages 16-255 are available.
#define RTARDULINK_MESSAGE_CUSTOM 16 // start of custom messages
// RTArduLink response codes
#define RTARDULINK_RESPONSE_OK 0 // means things worked
#define RTARDULINK_RESPONSE_ILLEGAL_COMMAND 1 // not a supported message type, data[1] has offending type
#endif // _RTARDULINKDEFS_H