From 7cc7a52e10f25603cac2bb7c369fc0d57eb0f780 Mon Sep 17 00:00:00 2001
From: watson8544 <854410664@qq.com>
Date: Wed, 8 Aug 2018 00:06:12 +0800
Subject: [PATCH] add "api reference" (i2c rtc sd_card)

---
 en/api-reference/index.rst           |   1 +
 en/api-reference/peripherals/i2c.rst | 116 +++++++++++++++++++++++++++
 en/api-reference/peripherals/rtc.rst | 107 ++++++++++++++++++++++++
 en/api-reference/sd_card/sd_card.rst |  14 ++++
 4 files changed, 238 insertions(+)
 create mode 100644 en/api-reference/peripherals/i2c.rst
 create mode 100644 en/api-reference/peripherals/rtc.rst
 create mode 100644 en/api-reference/sd_card/sd_card.rst

diff --git a/en/api-reference/index.rst b/en/api-reference/index.rst
index ec10abb0..81efb7aa 100644
--- a/en/api-reference/index.rst
+++ b/en/api-reference/index.rst
@@ -9,6 +9,7 @@ API Reference
     Button <button/button>
     Peripherals <peripherals/index>
     Speaker <speaker/speaker>
+    SD Card <sd_card/sd_card>
 
 
 
diff --git a/en/api-reference/peripherals/i2c.rst b/en/api-reference/peripherals/i2c.rst
new file mode 100644
index 00000000..cd46fae0
--- /dev/null
+++ b/en/api-reference/peripherals/i2c.rst
@@ -0,0 +1,116 @@
+I2C API
+********
+
+-----------------------------
+
+Description
+------------
+
+Both master and slave modes are supported
+Master and slave modes can be used at the same time, on different I2C interfaces
+
+
+-----------------------------
+
+Function
+---------
+
+machine.I2C(id, mode, speed, sda, scl, slave_addr, slave_bufflen, slave_rolen, slave_busy)
+>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+
+| **Description:** 　　
+|   Create the I2C instance object
+
+| **Parament:**
+|   **id:** The hardware I2C peripheral ID; 0 or 1 can be used. Default: 0
+|   **mode:** I2C interface mode; master or slave. Use the constants **machine.I2C.MASTER** or **machine.I2C.SLAVE**  Default: master
+|   **speed:** I2C clock frequency in **Hz**. Default: 100000
+|   **sda:** I2C **sda** pin; can be given as integer gpio number or Pin object
+|   **scl:** I2C **scl** pin; can be given as integer gpio number or Pin object
+|   **slave_addr:** I2C slave address to be assigned to this i2c interface. Only used if SLAVE mode is selected
+|   **slave_bufflen:** Size of slave buffer used for master<->slave comunication in bytes
+|   **slave_rolen:** Size of **read-only** area at the end of the slave buffer in bytes
+|   **slave_busy:** Only used if **SLAVE** mode is selected
+|   *Note: Only sda and scl are required, all the others are optional and will be set to the default values if not given*
+
+
+init(args)
+>>>>>>>>>>>>>>>>>
+
+| **Description:** 　　
+|   Reinitialize an existing I2C object
+
+| **Parament:**
+|   **The arguments are the same as for creating a new i2c instance object** 
+
+
+scan()
+>>>>>>>>>>>>>>>>>
+
+| **Description:** 　　
+|   Scan for i2c devices on I2C bus. Does not scan reserved 7-bit addresses: **0x00-0x07** & **0x78-0x7F**
+|   *Note: can only be used in master mode*
+
+| **Parament:**
+|   **None** 
+
+| **Return:**
+|   Returns the list of detected addresses
+
+
+readfrom(addr, nbytes)
+>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+
+| **Description:** 　　
+|   Read **nbytes** bytes from i2c device with address **addr**
+|   *Note: can only be used in master mode*
+
+| **Parament:**
+|   **None:** 
+
+| **Return:**
+|   Return bytearray of read bytes
+
+writeto(addr, buf [,stop=True])
+>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+
+| **Description:** 　　
+|   Write the content of the buffer object **buf** to the i2c device with address **adr**
+|   *Note: can only be used in master mode*
+
+| **Parament:**
+|   *Note: If optional stop argument is set to False, the stop signal is not issued* 
+
+readfrom_into(addr, buf)
+>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+
+| **Description:** 　　
+|   Read from i2c device with address **addr** into buffer object **buf**
+|   *Note: can only be used in master mode*
+
+| **Parament:**
+|   *Note: Size of buf bytes are read* 
+
+---------------------
+
+Usage
+------
+
+.. code:: python
+
+    from machine import I2C
+
+    i2c = I2C(freq=400000, sda=21, scl=22)
+                                    # create I2C peripheral at frequency of 400kHz
+                                    # depending on the port, extra parameters may be required
+                                    # to select the peripheral and/or pins to use
+
+    i2c.scan()                      # scan for slaves, returning a list of 7-bit addresses
+
+    i2c.writeto(42, b'123')         # write 3 bytes to slave with 7-bit address 42
+    i2c.readfrom(42, 4)             # read 4 bytes from slave with 7-bit address 42
+
+    i2c.readfrom_mem(42, 8, 3)      # read 3 bytes from memory of slave 42,
+                                    #   starting at memory-address 8 in the slave
+    i2c.writeto_mem(42, 2, b'\x10') # write 1 byte to memory of slave 42
+                                    #   starting at address 2 in the slave
\ No newline at end of file
diff --git a/en/api-reference/peripherals/rtc.rst b/en/api-reference/peripherals/rtc.rst
new file mode 100644
index 00000000..f1cf6f06
--- /dev/null
+++ b/en/api-reference/peripherals/rtc.rst
@@ -0,0 +1,107 @@
+RTC API
+********
+
+-----------------------------
+
+Description
+------------
+
+The content of the RTC memory is preserved during the deep sleep.
+
+Up to 64 32-bit integers can be saved in RTC memory.
+
+One string of up to 2048 characters can be saved in RTC memory.
+The string can be, for example, json string containing the parameters which has to be restored after deep sleep wake-up.
+
+Integers and string saved in RTC memory are protected by 16-bit CRC
+
+
+-----------------------------
+
+Function
+---------
+
+machine.RTC()
+>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+
+| **Description:** 　　
+|   Create the RTC instance object
+
+init(date)
+>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+
+| **Description:** 　　
+|   Set the system time and date
+
+| **Parament:**
+|   **date:** it's a tuple containing the time and date information
+|             *Note: the tuple is equal to (year, month, day [,hour [,minute [, second ]]])*
+
+now()
+>>>>>>>>>>>>>>>>>
+
+| **Description:** 　　
+|   get the current time
+
+| **Parament:**
+|   **None** 
+
+| **Return:**
+|   Return the current time as tuple: `(year, month, day, hour, minute, second)`
+
+ntp_sync(server [,update_period] [,tz])
+>>>>>>>>>>>>>>>>>
+
+| **Description:** 　　
+|   Write bytes from buffer object buf to the RTC device
+
+| **Parament:**
+|   **server :**       the NTP server domain name or IP, for example "pool.ntp.org"
+|   **update_period:** optional, time update interval in seconds; default: 3600
+|   **tz:**            optional, time zone string; default: the one set in menuconfig
+
+
+| **Return:**
+|   Returns `True` on success, `False` ion error
+
+| **Example:**
+.. code:: python
+
+    import machine
+    import utime
+
+    rtc = machine.RTC()
+    rtc.ntp_sync(server="hr.pool.ntp.org", tz="CET-1CEST")
+
+
+synced()
+>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+
+| **Description:** 　　
+|   Sync the system time from NTP server
+
+| **Parament:**
+|   **None:** 
+
+| **Return:**
+|   Return `True` if the system time was synced from NTP server, `False` if not
+
+
+---------------------
+
+Usage
+------
+
+.. code:: python
+
+    import machine
+    import utime
+
+    rtc = machine.RTC()
+    rtc.ntp_sync(server="hr.pool.ntp.org", tz="CET-1CEST")
+    rtc.synced()
+    True
+    utime.gmtime()
+    (2018, 1, 29, 16, 3, 18, 2, 29)
+    utime.localtime()
+    (2018, 1, 29, 17, 3, 30, 2, 29)
\ No newline at end of file
diff --git a/en/api-reference/sd_card/sd_card.rst b/en/api-reference/sd_card/sd_card.rst
new file mode 100644
index 00000000..00e33272
--- /dev/null
+++ b/en/api-reference/sd_card/sd_card.rst
@@ -0,0 +1,14 @@
+SD Card API
+************
+
+-----------------------------
+
+Usage
+------
+
+.. code:: python
+
+    import uos
+
+    uos.mountsd()
+    uos.listdir('/sd')
\ No newline at end of file