updated README, LICENSE, notes

2 files changed, 199 insertions, 0 deletions

diff --git a/notes/i2c b/notes/i2c
new file mode 100644
index 0000000..c324bb2
--- /dev/null
+++ b/notes/i2c
@@ -0,0 +1,134 @@
+
+Maple -------------------------------------------------------------------------
+
+We'll probably want both HardwareI2C and SoftI2C implementations, with the
+soft being bitbanged on arbitrary pins (and possibly only master-mode; almost
+certainly not multi-master).
+
+The first simple implementation will support up to 400khz operation, only 
+7-bit addresses, no clock stretching (on our part), only blocking master
+read/write (with timeout), and only master n-write,n-read combined messages.
+
+A more advanced implementation would be event-driven, support DMA, higher
+clock speeds, handle error interrupts, etc. 
+
+Should all of these return a status code? or just fail? or fail silently?
+
+Ring buffers etc are not needed because the length of the read/write is always
+known (or handled by the application code for slave mode).
+
+// port = {1,2}
+i2c_init(port, freq)
+i2c_disable(port)
+
+// blocking/polling
+i2c_master_read(port, slave_addr, *data, len)  // wrapper around writeread
+i2c_master_write(port, slave_addr, *data, len) // wrapper around writeread
+i2c_master_writeread(port, slave_addr, *wdata, wlen, *rdata, rlen)
+
+// callbacks/interrupts
+i2c_slave_set_addr(port, addr) // enables callbacks etc if they aren't already;
+                               // set ACK high
+i2c_slave_set_rx_callback(port, *function) // takes a byte?
+i2c_slave_set_tx_callback(port, *function) // gives a byte?
+
+How to init:
+ - setup pins
+ - setup peripheral input clock: 4MHz for fast mode
+ - configure clock control registers
+ - configure rise time register
+ - configure interrupts
+ - configure I2C_CR1 to enable the peripheral
+ - set ACK flag low: won't be a slave until addr is set
+
+How to master_write:
+ - START, addr[0:7], W, ACK, DATA[0:7], ACK, DATA[8:15], ..., STOP
+ - software sets START high, which toggles M/SL to master mode
+ - when START actually happens, SB is set and interrupt happens; hardware
+   waits until address is written to DR
+ - address shifts out and an interrupt is thrown with ADDR high; if LSB of
+   address was low, in transmitter mode. TRA reflects this
+ - software writes to the first byte to DR and clears ADDR
+ - first byte shifts out and when there's an ACK an interrupt is thrown
+   with TxE high; if no new byte was written to DR since the previous
+   transmission BTF goes high
+ - software writes next byte to DR and clears BTF, or sets STOP bit to end
+   data transmission, or sets START to begin next part of combined session
+ - after STOP is set, hardware goes back to slave mode
+
+How to master_read:
+ - START, addr[0:7], R, ACK, DATA[0:7], ACK, ..., NACK, DATA[-8:-1], STOP
+ - software sets START high, which toggles M/SL to master mode
+ - when START actually happens, SB is set and interrupt happens; hardware
+   waits until address is written to DR
+ - address shifts out and an interrupt is thrown with ADDR high; if LSB of
+   address was high, in receiver mode. TRA reflects this.
+ - software clears ADDR; hardware shifts in first byte from slave and sends ACK
+   if ACK is set. interrupt is thrown with RxNE high, with BTF set
+ - if only reading one byte, ACK should be set low and STOP high; hardware will
+   then NACK and STOP after reading
+ - software reads from DR and clears BTF bit. next byte is shifted in
+ - software sets NACK low after second-to-last byte is read by setting ACK low
+   after reading from DR, and either setting STOP or START high
+ - after STOP is set, hardware goes back to slave mode
+
+How to master_writeread:
+ - [START, addr[0:7], W, ACK, WDATA[0:7], ...], 
+   [START, addr[0:7], R, ACK, RDATA[0:7], ACK, ..., NACK, RDATA[-8:-1]]
+   STOP
+ - implement the above read/write but set START high instead of STOP high at
+   the end
+
+How to slave tx (master read):
+ - if address is matched, ACK is send (if ACK flag is high) and ADDR goes high;
+   event interrupt is triggered if ITEVFEN flag is set. TRA indicates whether
+   this is a read or write request
+ - program sets DR degister and clears ADDR flag; hardware will clock stretch
+   until ADDR is low
+ - if ITVENFEN and ITBUFEN are set, the TxE interrupt is triggered after the
+   byte is sent and the master ACKs. now the hardware stretches until BTF is
+   cleared before sending again.
+ - after the STOP is sent, hardware sets STOPF, throws an event if ITEVFEN is
+   high, and waits for a read of SR1 and write CR1
+
+How to slave rx (master write):
+ - if address is matched, ACK is send (if ACK flag is high) and ADDR goes high;
+   event interrupt is triggered if ITEVFEN flag is set. TRA indicates whether
+   this is a read or write request
+ - the hardware shifts in the byte to DR and sends an ACK if ACK flag is high
+ - if ITEVFEN and ITBUFEN are set, an RxNE interrupt is sent. hardware waits
+   until the BTF flag is reset
+ - after the STOP is sent, hardware sets STOPF, throws an event if ITEVFEN is
+   high, and waits for a read of SR1 and write CR1
+
+i2c General Reference ---------------------------------------------------------
+
+http://en.wikipedia.org/wiki/I²C
+
+4 modes/roles for a given device. These designations are transaction specific;
+a device can switch roles from one transaction to the next:
+    master transmit
+    master receive
+    slave transmit
+    slave receive
+
+
+STM32 Specific Reference ------------------------------------------------------
+
+see stm32 docs: reference manual (doc 13902 rev10) pg637/1003
+
+see STM32F10x_StdPeriph_Lib_V3.2.0/Project/STM32F10x_StdPeriph_Examples/I2C/Interrupt for an example project (reading/writing between the two i2c buses) based on the stm32library
+
+>100khz is "fast mode", which goes up to 400khz. stm32 supports up to 400khz.
+    things are different in fast mode: 4mhz input clock
+
+interrupts see pg652/1003
+registers see pg654/1003
+
+PEC = packet error checking. don't think this is i2c standard
+
+each i2c port has an error and an event interrupt 
+
+the stm32 is in slave mode by default; it enters master only when executing
+a request
+
diff --git a/notes/pin-mapping.txt b/notes/pin-mapping.txt
new file mode 100644
index 0000000..c1709e8
--- /dev/null
+++ b/notes/pin-mapping.txt
@@ -0,0 +1,65 @@
+Reserved Pins:         Function
+PA11                   USBDM
+PA12                   USBDP
+PA13                   JTMS-SWDAT
+PA14                   JTCK-SWCLK
+PA15                   JTDI
+PB2                    BOOT1
+PB3                    JTDO
+PB4                    JTRST
+PC11                   USB_P
+PC12                   DISC
+PD0                    OSC_IN
+PD1                    OSC_OUT
+
+-------------------------------------------------------------------------------
+Pin    STM32 PIN   ADC    Timer          I2C        UART        SPI         F/T
+-------------------------------------------------------------------------------
+D0     PA3         ADC3   TIM2_CH4       -          USART2_RX   -           -
+D1     PA2         ADC2   TIM2_CH3       -          USART2_TX   -           -
+D2     PA0         ADC0   TIM2_CH1_ETR   -          USART2_CTS  -           -
+D3     PA1         ADC1   TIM2_CH2       -          USART2_RTS  -           -
+D4     PB5         -      -              ISC1_SMBA  -           -           -
+D5     PB6         -      TIM4_CH1       I2C1_SCL   -           -           Y
+D6     PA8         -      TIM1_CH1       -          USART1_CK   -           Y
+D7     PA9         -      TIM1_CH2       -          USART1_TX   -           Y
+D8     PA10        -      TIM1_CH3       -          USART1_RX   -           Y
+D9     PB7         -      TIM4_CH2       I2C1_SDA   -           -           Y
+D10    PA4         ADC4   -              -          USART2_CK   SPI1_NSS    -
+D11    PA7         ADC7   TIM3_CH2       -          -           SPI1_MOSI   -
+D12    PA6         ADC6   TIM3_CH1       -          -           SPI1_MISO   -
+D13    PA5         ADC5   -              -          -           SPI1_SCK    -
+D14    PB8         0      TIM4_CH3       -          -           -           Y
+-------------------------------------------------------------------------------
+Little header                                                                  
+-------------------------------------------------------------------------------
+D15    PC0         ADC10  -              -          -           -           -
+D16    PC1         ADC11  -              -          -           -           -
+D17    PC2         ADC12  -              -          -           -           -
+D18    PC3         ADC13  -              -          -           -           -
+D19    PC4         ADC14  -              -          -           -           -
+D20    PC5         ADC15  -              -          -           -           -
+-------------------------------------------------------------------------------
+External header                                                                 
+-------------------------------------------------------------------------------
+D21    PC13        -      -              -          -           -           -
+D22    PC14        -      -              -          -           -           -
+D23    PC15        -      -              -          -           -           -
+D24    PB9         -      TIM4_CH4       -          -           -           Y
+D25    PD2         -      TIM3_ETR       -          -           -           Y
+D26    PC10        -      -              -          -           -           Y
+D27    PB0         ADC8   TIM3_CH3       -          -           -           -
+D28    PB1         ADC9   TIM3_CH4       -          -           -           -
+D29    PB10        -      -              I2C2_SCL   USART3_TX   -           Y
+D30    PB11        -      -              I2C2_SDA   USART3_RX   -           Y
+D31    PB12        -      TIM1_BKIN      I2C2_SMBAL USART3_CK   SPI2_NSS    Y
+D32    PB13        -      TIM1_CH1N      -          USART3_CTS  SPI2_SCK    Y
+D33    PB14        -      TIM1_CH2N      -          USART3_RTS  SPI2_MISO   Y
+D34    PB15        -      TIM1_CH3N      -          -           SPI2_MOSI   Y
+D35    PC6         -      -              -          -           -           Y
+D36    PC7         -      -              -          -           -           Y
+D37    PC8         -      -              -          -           -           Y
+D38    PC9         -      -              -          -           -           Y
+-------------------------------------------------------------------------------
+
+