From dc9ddc76a7fc872189a613ffeaacdc6dc71565ce Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?King=20K=C3=A9vin?= <kingkevin@cuvoodoo.info>
Date: Tue, 22 Mar 2016 11:16:47 +0100
Subject: [PATCH] read specific address over I2C, read seconds, use doxygen
 documentation

---
 lib/rtc_ds1307.c | 60 ++++++++++++++++++++++++++++++++++--------------
 lib/rtc_ds1307.h | 17 ++++++++++----
 2 files changed, 55 insertions(+), 22 deletions(-)

diff --git a/lib/rtc_ds1307.c b/lib/rtc_ds1307.c
index ce4c7c6..12acd3c 100644
--- a/lib/rtc_ds1307.c
+++ b/lib/rtc_ds1307.c
@@ -12,9 +12,12 @@
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  *
  */
-/* Copyright (c) 2016 King Kévin <kingkevin@cuvoodoo.info> */
-/* this library handles communication with the I2C RTC IC Maxim DS1307 */
-/* peripherals used: I2C (check source for details) */
+/** @file rtc_ds1307.c
+ *  @author King Kévin <kingkevin@cuvoodoo.info>
+ *  @date 2016
+ *  @brief this library handles communication with the I2C RTC IC Maxim DS1307
+ *  peripherals used: I2C @ref rtc_ds1307_i2c
+ */
 
 /* standard libraries */
 #include <stdint.h> // standard integer types
@@ -28,18 +31,28 @@
 #include <libopencm3/cm3/nvic.h> // interrupt handler
 #include <libopencmsis/core_cm3.h> // Cortex M3 utilities
 
+#include "global.h" // global utilities
 #include "rtc_ds1307.h" // RTC header and definitions
 
-/* which I2C to use */
+/** @defgroup trc_ds1307_i2c I2C port used to communication with the DS1307 RTC IC
+ *  @{
+ */
+/** I2C peripheral */
 #define I2C I2C1
+/** I2C peripheral clock */
 #define I2C_RCC RCC_I2C1
+/** I2C peripheral interrupt */
 #define I2C_IRQ NVIC_I2C1_IRQ
+/** I2C peripheral port */
 #define I2C_PORT GPIOB
-#define I2C_PIN_SDA GPIO_I2C1_SDA // on PB7
-#define I2C_PIN_SCL GPIO_I2C1_SCL // on PB6
-#define I2C_ADDR 0b1101000 // DS1307 fixed slave address
+/** I2C peripheral data pin (PB7) */
+#define I2C_PIN_SDA GPIO_I2C1_SDA
+/** I2C peripheral clock pin (PB6) */
+#define I2C_PIN_SCL GPIO_I2C1_SCL
+/** @} */
+/** DS1307 I2C address (fixed) */
+#define I2C_ADDR 0b1101000
 
-/* setup communication with RTC IC */
 void rtc_setup(void)
 {
 	/* enable peripheral */
@@ -57,23 +70,35 @@ void rtc_setup(void)
 	i2c_peripheral_enable(I2C); // enable I2C after configuration completed
 }
 
-/* read memory from RTC IC
- * read <len> data into <data>
- * return if read succeeded */
-static bool rtc_read_memory(uint8_t* data, size_t len)
+/** @brief read memory from RTC IC
+ *  @param[in] addr start address for memory to read
+ *  @param[out] data buffer to store read memory
+ *  @param[in] len number of byte to read from the memory
+ *  @return if read succeeded
+ */
+static bool rtc_read_memory(uint8_t addr, uint8_t* data, size_t len)
 {
 	bool to_return = false; // return if read succeeded
 	if (data==NULL || len==0) { // verify there it data to be read
 		goto error;
 	}
 	i2c_send_start(I2C); // send start condition to start transaction
-	while (!(I2C_SR1(I2C) & I2C_SR1_SB)); // wait until start bit is transmitted
+	while (!(I2C_SR1(I2C) & I2C_SR1_SB)); // wait until start condition is transmitted
 	if (!(I2C_SR2(I2C) & I2C_SR2_MSL)) { // verify if in master mode
 		goto error;
 	}
-	i2c_send_7bit_address(I2C, I2C_ADDR, I2C_READ); // transmit address
+	i2c_send_7bit_address(I2C, I2C_ADDR, I2C_WRITE); // select slave
 	while (!(I2C_SR1(I2C) & I2C_SR1_ADDR)); // wait until address is transmitted
-	if (I2C_SR2(I2C) & I2C_SR2_TRA) { // verify we are in receive mode (and read SR2 to clear ADDR)
+	if (!((I2C_SR2(I2C) & I2C_SR2_TRA))) { // verify we are in transmit mode (and read SR2 to clear ADDR)
+		goto error;
+	}
+	i2c_send_data(I2C, addr); // send memory address we want to read
+	while (!(I2C_SR1(I2C) & I2C_SR1_TxE)); // wait until byte has been transmitted
+	i2c_send_start(I2C); // send restart condition to switch from write to read mode
+	while (!(I2C_SR1(I2C) & I2C_SR1_SB)); // wait until start condition is transmitted
+	i2c_send_7bit_address(I2C, I2C_ADDR, I2C_READ); // select slave
+	while (!(I2C_SR1(I2C) & I2C_SR1_ADDR)); // wait until address is transmitted
+	if ((I2C_SR2(I2C) & I2C_SR2_TRA)) { // verify we are in read mode (and read SR2 to clear ADDR)
 		goto error;
 	}
 	for (size_t i=0; i<len; i++) { // read bytes
@@ -95,10 +120,11 @@ error:
 	return to_return;
 }
 
-/* read seconds (0-59) from RTC IC */
 uint8_t rtc_read_seconds(void)
 {
 	uint8_t to_return = 0; // seconds to return
-	rtc_read_memory(&to_return, 1); // read a single byte to test
+	uint8_t data[1] = {0}; // to read data from I2C
+	rtc_read_memory(0, data, LENGTH(data)); // read a single byte to test
+	to_return = ((data[0]&0x70)>>4)*10+(data[0]&0x0f); // convert BCD coding into seconds
 	return to_return;
 }
diff --git a/lib/rtc_ds1307.h b/lib/rtc_ds1307.h
index e6c6c68..a408a4c 100644
--- a/lib/rtc_ds1307.h
+++ b/lib/rtc_ds1307.h
@@ -12,12 +12,19 @@
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  *
  */
-/* Copyright (c) 2016 King Kévin <kingkevin@cuvoodoo.info> */
-/* this library handles communication with the I2C RTC IC Maxim DS1307 */
-/* peripherals used: I2C (check source for details) */
+/** @file rtc_ds1307.h
+ *  @author King Kévin <kingkevin@cuvoodoo.info>
+ *  @date 2016
+ *  @brief this library handles communication with the I2C RTC IC Maxim DS1307
+ *  peripherals used: I2C @ref rtc_ds1307_i2c
+ */
 #pragma once
 
-/* setup communication with RTC IC */
+/** @brief setup communication with RTC IC
+ *  configure the I2C port defined in the sources
+ */
 void rtc_setup(void);
-/* read seconds (0-59) from RTC IC */
+/** @brief read seconds (0-59) from RTC IC
+ *  @return the number of seconds of the current time
+ */
 uint8_t rtc_read_seconds(void);