interface.h

Go to the documentation of this file.

/*
 *  This file is part of the Home2L project.
 *
 *  (C) 2015-2021 Gundolf Kiefer
 *
 *  Home2L is free software: you can redistribute it and/or modify
 *  it under the terms of the GNU General Public License as published by
 *  the Free Software Foundation, either version 3 of the License, or
 *  (at your option) any later version.
 *
 *  Home2L is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *  GNU General Public License for more details.
 *
 *  You should have received a copy of the GNU General Public License
 *  along with Home2L. If not, see <https://www.gnu.org/licenses/>.
 *
 */
 
 
#ifndef _INTERFACE_
#define _INTERFACE_
 
 
#include <stdint.h>
#include <stdbool.h>
 
 
 
 
 
// *************************** General Device Settings *************************
 
 
#define BR_CPU_FREQ 1000000         
 
#if AVR && BR_CPU_FREQ != F_CPU
#error "The CPU frequency (F_CPU) must be set to 1 MHz / BR_CPU_FREQ"
#endif
 
 
#define BR_TICKS_PER_SECOND (((float) BR_CPU_FREQ) / 1024.0)
#define BR_TICKS_PER_MS (BR_TICKS_PER_SECOND / 1000.0)
#define BR_MS_PER_TICK (1.0 / BR_TICKS_PER_MS)
 
#define BR_TICKS_OF_MS(T) ((T) * BR_TICKS_PER_MS)
#define BR_MS_OF_TICKS(T) (((float) (T)) * BR_MS_PER_TICK)
 
#define BR_TICKS_NEVER 0
 
 
 
 
 
 
 
// *************************** Protocol ****************************************
 
 
#define BR_MEM_BLOCKSIZE_SHIFT 4
#define BR_MEM_BLOCKSIZE (1 << BR_MEM_BLOCKSIZE_SHIFT)
 
 
 
typedef enum {
  brOk = 0,             
  brIncomplete,         
  brUnchecked,          
  brRequestCheckError,  
  brReplyCheckError,    
  brIllegalOperation,   
  brForbidden,          
  brNoBrownie,          
  brNoDevice,           
  brNoBus,              
 
  brNoReply = 0x0f,     
  brEND
} EBrStatus;
 
 
typedef struct SBrRequest {
  uint8_t check;        
  uint8_t op;           
  union {
    struct {            // Register write data ...
      uint8_t val;                    
    } regWrite;
    struct {            // Memory read data ...
      uint8_t adr;                    
    } memRead;
    struct {            // Memory write ...
      uint8_t adr;                    
      uint8_t data[BR_MEM_BLOCKSIZE]; 
    } memWrite;
  };
} TBrRequest;
 
 
typedef struct SBrReply {
  uint8_t status;         
  union {
    struct {              // Register read ...
      uint8_t val;                    
    } regRead;
    struct {              // Memory read ...
      uint8_t data[BR_MEM_BLOCKSIZE]; 
      uint8_t dataCheck;              
    } memRead;
  };
} TBrReply;
 
 
 
 
 
// ***** Macros *****
 
 
// Request-related ...
#define BR_REQUEST_SIZE_MAX ((int) sizeof (TBrRequest))   
#define BR_REQUEST_SIZE_MIN 2                             
 
// Reply-related ...
#define BR_REPLY_SIZE_MAX ((int) sizeof (TBrReply))       
#define BR_REPLY_SIZE_MIN 1                               
#define BR_REPLY_SIZE_STATUS 1                            
 
 
// Contructing operation words ...
#define BR_OP_REG_READ(REG)  ((0x00 | (REG)))             
#define BR_OP_REG_WRITE(REG) ((0x40 | (REG)))             
#define BR_OP_MEM_READ(BLKADR)  (0x80 | ((BLKADR) >> 8))  
#define BR_OP_MEM_WRITE(BLKADR) (0x90 | ((BLKADR) >> 8))  
 
// Analyzing operation words ...
#define BR_OP_IS_REG_READ(OP)  (((OP) & 0xc0) == 0x00)
#define BR_OP_IS_REG_WRITE(OP) (((OP) & 0xc0) == 0x40)
#define BR_OP_IS_MEM_READ(OP)  (((OP) & 0xf0) == 0x80)
#define BR_OP_IS_MEM_WRITE(OP) (((OP) & 0xf0) == 0x90)
 
 
 
 
 
// ***** Functions *****
 
 
// Requests ...
int8_t BrRequestSize (uint8_t op);
#if !AVR
void BrRequestPackage (TBrRequest *msg);
#endif
EBrStatus BrRequestCheck (TBrRequest *msg, int8_t bytes);
 
 
// Replies ...
int8_t BrReplySize (uint8_t op);
void BrReplyPackage (TBrReply *reply, int8_t len);
#if !AVR
EBrStatus BrReplyCheck (TBrReply *reply, uint8_t op, int8_t bytes);
#endif
 
 
 
 
 
 
 
// ************ Brownie Memory Organization and Data Records *******************
 
 
 
// Memory base pages ...
#define BR_MEM_PAGE_FLASH  0x0  
#define BR_MEM_PAGE_SRAM   0x8  
#define BR_MEM_PAGE_EEPROM 0x9  
#define BR_MEM_PAGE_VROM   0xa  
 
// Identifying memory space region ...
#define BR_MEM_ADR_IS_FLASH(ADR)   (((ADR) >> (BR_MEM_BLOCKSIZE_SHIFT+8)) <= BR_MEM_PAGE_FLASH + 7)
#define BR_MEM_ADR_IS_SRAM(ADR)    (((ADR) >> (BR_MEM_BLOCKSIZE_SHIFT+8)) == BR_MEM_PAGE_SRAM)
#define BR_MEM_ADR_IS_EEPROM(ADR)  (((ADR) >> (BR_MEM_BLOCKSIZE_SHIFT+8)) == BR_MEM_PAGE_EEPROM)
#define BR_MEM_ADR_IS_VROM(ADR)    (((ADR) >> (BR_MEM_BLOCKSIZE_SHIFT+8)) == BR_MEM_PAGE_VROM)
 
// Building the address from offset inside a region ...
#define BR_MEM_ADR_FLASH(OFS)  ((OFS) | (BR_MEM_PAGE_FLASH  << (BR_MEM_BLOCKSIZE_SHIFT+8)))
#define BR_MEM_ADR_SRAM(OFS)   ((OFS) | (BR_MEM_PAGE_SRAM   << (BR_MEM_BLOCKSIZE_SHIFT+8)))
#define BR_MEM_ADR_EEPROM(OFS) ((OFS) | (BR_MEM_PAGE_EEPROM << (BR_MEM_BLOCKSIZE_SHIFT+8)))
#define BR_MEM_ADR_VROM(OFS)   ((OFS) | (BR_MEM_PAGE_VROM   << (BR_MEM_BLOCKSIZE_SHIFT+8)))
 
// Getting the offset inside a region ...
#define BR_MEM_OFS(ADR) ((ADR) & ((BR_MEM_ADR_IS_FLASH(ADR) ? 0x7ff : 0x0ff) << BR_MEM_BLOCKSIZE_SHIFT))
 
 
 
// Flash ...
#define BR_FLASH_PAGESIZE 0x40
#define BR_FLASH_BASE_MAINTENANCE  0x0040
#define BR_FLASH_BASE_OPERATIONAL  0x0a00
 
 
// VROM ...
#define BR_VROM_SIZE        sizeof (TBrFeatureRecord)   
 
 
// EEPROM ...
#define BR_EEPROM_ID_BASE   0x0000                      
#define BR_EEPROM_ID_SIZE   sizeof (TBrIdRecord)        
 
#define BR_EEPROM_CFG_BASE  0x0000 + BR_EEPROM_ID_SIZE  
#define BR_EEPROM_CFG_SIZE  sizeof (TBrConfigRecord)    
 
 
 
 
 
// *************************** Brownie Data Records ****************************
 
 
 
 
#define BR_MAGIC 0xb1    
 
 
typedef struct SBrFeatureRecord {
 
  // Firmware version ...
  uint8_t   versionMajor;     
  uint8_t   versionMinor;
  uint16_t  versionRevision;
 
  // Feature presence ...
  uint16_t  features;         
 
  uint16_t  gpiPresence;      
  uint16_t  gpiPullup;        
  uint16_t  gpoPresence;      
  uint16_t  gpoPreset;        
 
  uint8_t   matDim;           
 
  uint8_t   reserved[3];      
 
  // Written firmware name ...
  char      fwName[12];       
 
  // MCU model ...
  uint8_t   mcuType;          
 
  // Magic byte (for verification) ...
  uint8_t   magic;            
 
} __attribute__((packed)) TBrFeatureRecord;
 
 
#define brFeatureRecordRcVec0 offsetof (TBrFeatureRecord, features)
#define brFeatureRecordRcVec1 offsetof (TBrFeatureRecord, reserved)
 
 
 
#define BR_FEATURE_MAINTENANCE  0x0001  
#define BR_FEATURE_TIMER        0x0002
#define BR_FEATURE_NOTIFY       0x0004  
#define BR_FEATURE_TWIHUB       0x0008  
#define BR_FEATURE_ADC_0        0x0010  
#define BR_FEATURE_ADC_1        0x0020  
#define BR_FEATURE_ADC_PASSIVE  0x0400  
#define BR_FEATURE_UART         0x0040  
#define BR_FEATURE_TEMP         0x0080  
#define BR_FEATURE_SHADES_0     0x0100  
#define BR_FEATURE_SHADES_1     0x0200  
 
 
 
#define BR_MATDIM_ROWS(X) ((X) >> 4)
#define BR_MATDIM_COLS(X) ((X) & 0x0f)
 
 
#define BR_MCU_NONE       0     
#define BR_MCU_ATTINY85   1     
#define BR_MCU_ATTINY84   2     
#define BR_MCU_ATTINY861  3     
 
 
 
 
 
 
 
typedef char TBrIdRecord[32];
 
 
 
 
 
 
 
typedef struct SBrConfigRecord {
  uint8_t   adr;                  
  uint8_t   magic;                
 
  uint8_t   oscCal;               
  uint8_t   reserved1;
 
  int8_t    hubMaxAdr;            
  uint8_t   hubSpeed;             
 
  uint8_t   shadesDelayUp[2];     
  uint8_t   shadesDelayDown[2];   
  uint8_t   shadesSpeedUp[2];     
  uint8_t   shadesSpeedDown[2];   
 
  uint8_t   reserved[2];          
 
} __attribute__((packed)) TBrConfigRecord;
 
 
 
 
 
 
 
 
 
// *************************** Brownie Registers *******************************
 
 
// ***** General Organization *****
 
 
#define BR_REGISTERS         0x40     
 
 
 
// ***** Register Map *****
 
 
#define BR_REG_CHANGED       0x00     
 
#define BR_CHANGED_CHILD     0x01     
#define BR_CHANGED_GPIO      0x02     
#define BR_CHANGED_MATRIX    0x04     
#define BR_CHANGED_ADC       0x40     
#define BR_CHANGED_UART      0x08     
#define BR_CHANGED_SHADES    0x10     
 
#define BR_CHANGED_TEMP      0x20     
 
 
 
#define BR_REG_GPIO_0        0x02     
#define BR_REG_GPIO_1        0x03     
 
#define BR_REG_TICKS_LO      0x04     
#define BR_REG_TICKS_HI      0x05     
 
#define BR_REG_TEMP_LO       0x06
#define BR_REG_TEMP_HI       0x07     
 
 
 
#define BR_REG_ADC_0_LO      0x08     
#define BR_REG_ADC_0_HI      0x09     
 
#define BR_REG_ADC_1_LO      0x0a     
#define BR_REG_ADC_1_HI      0x0b     
 
 
 
#define BR_REG_UART_CTRL     0x0c       
#define BR_REG_UART_STATUS   0x0d       
#define BR_REG_UART_RX       0x0e       
#define BR_REG_UART_TX       0x0f       
 
#define BR_UART_CTRL_RESET_RX     0x01  
#define BR_UART_CTRL_RESET_TX     0x02  
#define BR_UART_CTRL_RESET_FLAGS  0x04  
 
#define BR_UART_STATUS_RX_MASK    0x07  
#define BR_UART_STATUS_RX_SHIFT      0  
#define BR_UART_STATUS_TX_MASK    0x38  
#define BR_UART_STATUS_TX_SHIFT      3  
#define BR_UART_STATUS_OVERFLOW   0x40  
#define BR_UART_STATUS_ERROR      0x80  
 
 
 
 
#define BR_REG_MATRIX_0      0x10
#define BR_REG_MATRIX_1      0x11
#define BR_REG_MATRIX_2      0x12
#define BR_REG_MATRIX_3      0x13
#define BR_REG_MATRIX_4      0x14
#define BR_REG_MATRIX_5      0x15
#define BR_REG_MATRIX_6      0x16
#define BR_REG_MATRIX_7      0x17     
#define BR_REG_MATRIX_EVENT  0x18     
#define BR_REG_MATRIX_ECYCLE 0x19     
 
#define BR_MATRIX_EV_VAL_SHIFT  6     
#define BR_MATRIX_EV_ROW_SHIFT  3     
#define BR_MATRIX_EV_COL_SHIFT  0     
#define BR_MATRIX_EV_EMPTY    0x80    
#define BR_MATRIX_EV_OVERFLOW 0x81    
 
 
 
#define BR_REG_SHADES_STATUS 0x20     
#define BR_REG_SHADES_0_POS  0x22     
#define BR_REG_SHADES_0_RINT 0x23     
#define BR_REG_SHADES_0_REXT 0x24     
#define BR_REG_SHADES_1_POS  0x25     
#define BR_REG_SHADES_1_RINT 0x26     
#define BR_REG_SHADES_1_REXT 0x27     
 
#define BR_SHADES_0_ACT_UP   0x01     
#define BR_SHADES_0_ACT_DN   0x02     
#define BR_SHADES_0_BTN_UP   0x04     
#define BR_SHADES_0_BTN_DN   0x08     
#define BR_SHADES_1_ACT_UP   0x10     
#define BR_SHADES_1_ACT_DN   0x20     
#define BR_SHADES_1_BTN_UP   0x40     
#define BR_SHADES_1_BTN_DN   0x80     
 
 
 
#define BR_REG_DEBUG_0       0x38     
#define BR_REG_DEBUG_1       0x39     
#define BR_REG_DEBUG_2       0x3a     
#define BR_REG_DEBUG_3       0x3b     
 
 
 
#define BR_REG_FWBASE        0x3d     
#define BR_REG_CTRL          0x3e     
#define BR_REG_MAGIC         0x3f     
 
#define BR_CTRL_UNLOCK_EEPROM     0x01  
#define BR_CTRL_UNLOCK_FLASH      0x02  
#define BR_CTRL_HUB_RESURRECTION  0x04  
 
#define BR_CTRL_REBOOT            0xe0  
#define BR_CTRL_REBOOT_NEWFW      0xa0  
 
 
 
 
 
 
#endif // _INTERFACE_