updated "API Reference"

en/api-reference/button/button.rst

@@ -0,0 +1,70 @@
+Button API
+***********
+
+-----------------------------
+
+Function
+---------
+
+isPressed()
+
+isReleased()
+
+pressedFor(timeout)
+
+wasPressed(callback=None) 
+wasReleased(callback=None)
+releasedFor(timeout, callback=None)
+
+
+
+---------------------
+
+Usage
+------
+
+.. code:: python
+
+    from m5stack import *
+    from machine import SPI, Pin
+    from display import LCD
+    import utime
+
+    spi = SPI(1, baudrate=32000000, mosi=Pin(23), miso=Pin(19), sck=Pin(18))
+
+    lcd = LCD(spi = spi) #lcd init
+    
+    while True:
+      if buttonA.wasPressed():
+        lcd.print('Button A was Pressed\n')
+
+      if buttonA.wasReleased():
+        lcd.print('Button A was Released\n')
+
+      if buttonA.pressedFor(1.5):
+        lcd.print('Button A pressed for 1.5s\n')
+
+      if buttonA.releasedFor(2):
+        lcd.print('Button A released for 2s press hold\n')
+
+      utime.sleep(0.1)
+
+
+.. code:: python
+
+    #Button Callback
+
+    from m5stack import * 
+
+    def on_wasPressed():
+      lcd.print('Button B was Pressed\n')
+
+    def on_wasReleased():
+      lcd.print('Button B was Released\n')
+
+    def on_releasedFor():
+      lcd.print('Button B released for 1.2s press hold\n')
+
+    buttonB.wasPressed(on_wasPressed)
+    buttonB.wasReleased(on_wasReleased)
+    buttonB.releasedFor(1.2, on_releasedFor)

en/api-reference/index.rst

@@ -6,6 +6,11 @@ API Reference
     :maxdepth: 1
   
     LCD <lcd/lcd>
+    Button <button/button>
+    Peripherals <peripherals/index>
+    Speaker <speaker/speaker>
+
+
 
 
 

en/api-reference/peripherals/adc.rst

@@ -0,0 +1,65 @@
+ADC API
+********
+
+-----------------------------
+
+Description
+------------
+
+ESP32 integrates two 12-bit SAR (Successive Approximation Register) ADCs (Analog to Digital Converters) and supports measurements on 18 channels (analog enabled pins)
+
+ESP32 DAC output voltage range is 0-Vdd (3.3 V), the resolution is 8-bits
+
+
+-----------------------------
+
+Function
+---------
+
+machine.ADC(pin [,unit=1])
+>>>>>>>>>>>>>>>>>>>>>>>>>>
+
+| **Description:** 　　
+|   Create the adc instance object
+
+| **Parament:**
+|   **pin:** pin argument defines the gpio which will will be used as adc input
+|   **unit:** Optional unit argument select ESP32 ADC unit for this instance. Values 1 (ADC1, default) or 2 (ADC2) can be selected
+
+| **Example:**
+.. code:: python
+
+    import machine
+
+    adc = machine.ADC(35)
+
+read()
+>>>>>>>>>>>>>>>>>
+
+| **Description:** 　　
+|   Read the ADC value as voltage (in mV)
+|   
+
+| **Parament:**
+|   None Parament
+
+| **Example:**
+.. code:: python
+
+    import machine
+
+    adc = machine.ADC(35)
+    adc.read()
+
+
+---------------------
+
+Usage
+------
+
+.. code:: python
+
+    import machine
+
+    adc = machine.ADC(35)
+    adc.read()

en/api-reference/peripherals/dac.rst

@@ -0,0 +1,69 @@
+DAC API
+********
+
+-----------------------------
+
+Description
+------------
+
+ESP32 has two 8-bit DAC (digital to analog converter) channels, connected to GPIO25 (Channel 1) and GPIO26 (Channel 2).
+The DAC driver allows these channels to be set to arbitrary voltages.<br The DAC channels can also be driven with DMA-style written sample data, via the I2S driver when using the “built-in DAC mode”.
+
+ESP32 DAC output voltage range is 0-Vdd (3.3 V), the resolution is 8-bits
+
+
+-----------------------------
+
+Function
+---------
+
+machine.DAC(pin)
+>>>>>>>>>>>>>>>>>
+
+| **Description:** 　　
+|   Pin argument defines the gpio which will will be used as dac output
+|   *Note: Only GPIOs 25 and 26 can be used as DAC outputs*
+|   
+
+| **Parament:**
+|   **pin:** The pin argument can be given as pin number (integer) or the machine.Pin object
+
+| **Example:**
+.. code:: python
+
+    import machine
+
+    dac = machine.DAC(machine.Pin(26))
+    dac.write(128)
+
+write(value)
+>>>>>>>>>>>>>>>>>
+
+| **Description:** 　　
+|   Set the DAC value
+|   *Note: The value of 255 sets the voltage on dac pin to 3.3 V
+|   
+
+| **Parament:**
+|   **value:** DAC vaule.Valid range is: 0 - 255
+
+| **Example:**
+.. code:: python
+
+    import machine
+
+    dac = machine.DAC(machine.Pin(26))
+    dac.write(128)
+
+
+---------------------
+
+Usage
+------
+
+.. code:: python
+
+    import machine
+
+    dac = machine.DAC(machine.Pin(26))
+    dac.write(128)

en/api-reference/peripherals/gpio.rst

@@ -0,0 +1,27 @@
+GPIO API
+********
+
+-----------------------------
+
+Function
+---------
+
+value()
+
+
+
+
+---------------------
+
+Usage
+------
+
+.. code:: python
+
+    import machine
+    
+    pinout = machine.Pin(0, machine.Pin.OUT)
+    pinout.value(1)
+    
+    pinin = machine.Pin(2, machine.Pin.IN)
+    val = pinin.value()

en/api-reference/peripherals/index.rst

@@ -0,0 +1,13 @@
+Peripherals API
+***************
+
+.. toctree::
+   :maxdepth: 1
+
+   ADC <adc>
+   DAC <dac>
+   SPI <spi>
+   Neopixel <neopixel>
+   Timer <timer>
+   UART <uart>
+

en/api-reference/peripherals/neopixel.rst

@@ -0,0 +1,116 @@
+Neopixel API
+*************
+
+-----------------------------
+
+Description
+------------
+
+This class includes full support for various types of Neopixel, individually-addressable RGB(W) LEDs.
+ESP32 RMT peripheral is used for very precise timing ( +/- 50 ns ).
+Up to 8 Neopixel strips can be used, 1~1024 pixels each.
+
+-----------------------------
+
+Function
+---------
+
+machine.Neopixel(pin, pixels, type)
+>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+
+| **Description:** 　　
+|   Create the Neopixel instance object
+
+| **Parament:**
+|   **pin:** the data gpio which connects to rgb
+|   **pixels:** The number of rgb
+|   **type:** Neopixel type: 0 (machine.Neopixel.RGB) for RGB LEDs, or 1 (machine.Neopixel.RGBQ) for RGBW LEDs
+
+| **Example:**
+
+.. code:: python
+
+    import machine
+    np = machine.Neopixel(22, 115, 0)
+    npw = machine.Neopixel(machine.Pin(25), 24, machine.Neopixel.RGBW)
+
+setHSB(pos, hue, saturation, brightness [, white, num, update] ))
+>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+
+| **Description:** 　　
+|   Write bytes from buffer object buf to the Neopixel device
+
+| **Parament:**
+|   **pos:**        required, pixel position; 1 ~ pix_num
+|   **hue:**        float: any number, the floor of this number is subtracted from it 
+|                   to create a fraction between 0 and 1.
+|                   This fractional number is then multiplied by 360 to produce the hue angle in the HSB color model
+|   **saturation:** float; 0 ~ 1.0
+|   **brightness:** float; 0 ~ 1.0
+|   **num:**        optional; default: 1; number of pixels to set to the same color, starting from pos
+|   **update:**     optional, default: True; update the Neopixel strip. 
+|                   *Note: If False np.show() has to be used to update the strip*
+
+| **Return:**
+|   None
+
+| **Example:**
+.. code:: python
+
+    import machine, time
+
+    np = machine.Neopixel(machine.Pin(22), 24)
+
+    def rainbow(loops=120, delay=1, sat=1.0, bri=0.2):
+        for pos in range(0, loops):
+            for i in range(0, 24):
+                dHue = 360.0/24*(pos+i);
+                hue = dHue % 360;
+                np.setHSB(i, hue, sat, bri, 1, False)
+            np.show()
+            if delay > 0:
+                time.sleep_ms(delay)
+
+    def blinkRainbow(loops=10, delay=250):
+        for pos in range(0, loops):
+            for i in range(0, 24):
+                dHue = 360.0/24*(pos+i);
+                hue = dHue % 360;
+                np.setHSB(i, hue, 1.0, 0.1, 1, False)
+            np.show()
+            time.sleep_ms(delay)
+            np.clear()
+            time.sleep_ms(delay)
+
+
+---------------------
+
+Usage
+------
+
+.. code:: python
+
+    import machine, time
+
+    np = machine.Neopixel(machine.Pin(22), 24)
+
+    def rainbow(loops=120, delay=1, sat=1.0, bri=0.2):
+        for pos in range(0, loops):
+            for i in range(0, 24):
+                dHue = 360.0/24*(pos+i);
+                hue = dHue % 360;
+                np.setHSB(i, hue, sat, bri, 1, False)
+            np.show()
+            if delay > 0:
+                time.sleep_ms(delay)
+
+    def blinkRainbow(loops=10, delay=250):
+        for pos in range(0, loops):
+            for i in range(0, 24):
+                dHue = 360.0/24*(pos+i);
+                hue = dHue % 360;
+                np.setHSB(i, hue, 1.0, 0.1, 1, False)
+            np.show()
+            time.sleep_ms(delay)
+            np.clear()
+            time.sleep_ms(delay)

en/api-reference/peripherals/spi.rst

@@ -0,0 +1,120 @@
+SPI API
+********
+
+-----------------------------
+
+Description
+------------
+
+This class includes full support for using ESP32 SPI peripheral in master mode
+
+Only SPI master mode is supported for now.
+
+Python exception wil be raised if the requested spihost is used by SD Card driver (sdcard in spi mode).
+If the requested spihost is VSPI and the psRAM is used at 80 MHz, the exception will be raised.
+The exception will be raised if SPI cannot be configured for given configurations.
+
+
+-----------------------------
+
+Function
+---------
+
+machine.spi(spihost, baudrate, polarity, phase, firstbit, sck, mosi, miso, cs, duplex, bits)
+>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+
+| **Description:** 　　
+|   Create the spi instance object
+
+| **Parament:**
+|   **spihost:** The hardware SPI host. machine-SPI.HSPI (1) or machine.SPI.VSPI (2) can be used. Default: 1
+|   **baudrate:** SPI clock speed in Hz; Default: 1000000
+
+| **Example:**
+.. code:: python
+
+    from machine import SPI, Pin
+
+    spi = SPI(
+        spihost=SPI.HSPI, 
+        baudrate=2600000
+        sck=Pin(18), 
+        mosi=Pin(23), 
+        miso=Pin(19), 
+        cs=Pin(4)
+    )
+
+write(buf)
+>>>>>>>>>>>>>>>>>
+
+| **Description:** 　　
+|   Write bytes from buffer object buf to the SPI device
+
+| **Parament:**
+|   **buf:** data buffer to be write
+
+| **Return:**
+|   Returns `True` on success, `False` ion error
+
+| **Example:**
+.. code:: python
+
+    from machine import SPI, Pin
+
+    spi = SPI(
+        spihost=SPI.HSPI, 
+        baudrate=2600000
+        sck=Pin(18), 
+        mosi=Pin(23), 
+        miso=Pin(19), 
+        cs=Pin(4)
+    )
+
+    spi.write(buf) #NOHEAP
+
+
+write_readinto(wr_buf, rd_buf)
+>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+
+| **Description:** 　　
+|   Write bytes from buffer object wr_buf to the SPI device and reads from SPI device into buffer object rd_buf
+
+| **Parament:**
+|   **wr_buf:** data buffer to be write
+|   **rd_buf:** data buffer to be read
+|   *Note: * In fullduplex mode write and read are simultaneous. In halfduplex mode the data are first written to the device, then read from it
+
+| **Return:**
+|   Returns `True` on success, `False` ion error
+
+| **Example:**
+.. code:: python
+
+    import machine
+
+    adc = machine.ADC(35)
+    adc.read()
+
+
+---------------------
+
+Usage
+------
+
+.. code:: python
+
+    from machine import SPI, Pin
+
+    spi = SPI(
+        spihost=SPI.HSPI, 
+        baudrate=2600000
+        sck=Pin(18), 
+        mosi=Pin(23), 
+        miso=Pin(19), 
+        cs=Pin(4)
+    )
+
+    spi.write(buf) #NOHEAP
+    spi.read(nbytes, *, write=0x00) #write is the byte to ?output on MOSI for each byte read in
+    spi.readinto(buf, *, write=0x00) #NOHEAP
+    spi.write_readinto(write_buf, read_buf) #NOHEAP; write_buf and read_buf can be the same

en/api-reference/speaker/speaker.rst

@@ -0,0 +1,60 @@
+Speaker API
+************
+
+-----------------------------
+
+Function
+---------
+
+volume(volume)
+>>>>>>>>>>>>>>>>
+
+| **Description:** 　　
+|   Set the volume of sound
+
+| **Parament:**
+|   **volume:** sound volume 
+
+| **Example:**
+.. code:: python
+
+    from m5stack import *
+
+    speaker.volume(2)
+    speaker.tone(freq=1800)
+
+tone(freq [, duration])
+>>>>>>>>>>>>>>>>>>>>>>>>
+
+| **Description:** 　　
+|   Speak a sound with `frequency` and `duration`
+
+| **Parament:**
+|   **frequency:** the frequency of sound 
+|   **duration:** the duration of sound continued
+
+
+| **Return:**
+|   None
+
+| **Example:**
+.. code:: python
+
+    from m5stack import *
+
+    speaker.volume(2)
+    speaker.tone(freq=1800)
+    speaker.tone(freq=1800, duration=200) # Non-blocking
+
+---------------------
+
+Usage
+------
+
+.. code:: python
+
+    from m5stack import *
+
+    speaker.volume(2)
+    speaker.tone(freq=1800)
+    speaker.tone(freq=1800, duration=200) # Non-blocking

en/index.rst

@@ -24,9 +24,9 @@ If you have any questions, you can contact us by `email <tech@m5stack.com>`_ or
 ----------------------  ----------------------  ----------------------
 `Product Documents`_     `Get Started`_           `API Reference`_
 ----------------------  ----------------------  ----------------------
-|Basic Cases|_           |M5Stack Awesome|_           |FAQ|_    
+|M5Stack Cases|_           |M5Stack Awesome|_           |FAQ|_    
 ----------------------  ----------------------  ----------------------
-`Basic Cases`_           `M5Stack Awesome`_           `FAQ`_  
+`M5Stack Cases`_           `M5Stack Awesome`_           `FAQ`_  
 ======================  ======================  ======================
 
 
@@ -39,8 +39,8 @@ If you have any questions, you can contact us by `email <tech@m5stack.com>`_ or
 .. |API Reference| image:: ../_static/pics/m5-api-reference.jpg
 .. _API Reference: api-reference/index.html
 
-.. |Basic Cases| image:: ../_static/pics/m5stack-forum.jpg
-.. _Basic Cases: basic-cases/index.html
+.. |M5Stack Cases| image:: ../_static/pics/m5stack-forum.jpg
+.. _M5Stack Cases: basic-cases/index.html
 
 .. |M5Stack Awesome| image:: ../_static/pics/m5-awesome.jpg
 .. _M5Stack Awesome: m5stack-awesome/index.html
@@ -57,7 +57,7 @@ If you have any questions, you can contact us by `email <tech@m5stack.com>`_ or
    Product Documents <product-documents/index>
    Get Started <get-started/index>
    API Reference <api-reference/index>
-   Basic Cases <basic-cases/index>
+   M5Stack Cases <basic-cases/index>
    M5Stack Awesome <m5stack-awesome/index>
    FAQ <m5stack-faq/index>
 

en/product-documents/index.rst

@@ -38,6 +38,10 @@ Modules
    M5Stack LORA Module <modules/m5stack_lora_module>
    M5Stack SIM800 Module <modules/m5stack_sim800_module>
    M5Stack BATTERY Module <modules/m5stack_battery_module>
+   M5Stack BTC Module <modules/m5stack_btc_module>
+   M5Stack PROTO Module <modules/m5stack_proto_module>
+   M5Stack PROTO Kit <modules/m5stack_proto_kit>
+
 
 Tools
 ~~~~~~~~~~~~~~~~~~~  

en/product-documents/modules/m5stack_btc_module.rst

@@ -0,0 +1,29 @@
+M5Stack BTC Module
+==================
+
+DESCRIPTION
+-----------
+
+The M5Stack BTC Module is a base including DHT12 module which can detect
+temperature and humidity. Your M5Stack Core board can stay as a small
+displayer(like a small TV or a small IOT central contronller) after
+adding this BTC Module. Absolutely, it is more easier to charge M5Stack
+Core via Type-C Cable after adding this BTC Module.
+
+FEATURES
+--------
+
+-  DHT12 inside
+
+INCLUDES
+--------
+
+-  Type-C USB Cable
+-  M3 x 16
+-  Tools
+
+DOCUMENTS
+---------
+
+-  `WebSite <https://m5stack.com>`__
+

en/product-documents/modules/m5stack_proto_kit.rst

@@ -0,0 +1,66 @@
+M5Stack PROTO Module
+====================
+
+DESCRIPTION
+-----------
+
+The M5Stack PROTO Module is a flexible blank circle with 30 pins which
+could connect with all series of M5Stack Core. You can create any circle
+that could controlled by any M5Stack Core on M5Stack PROTO Module as you
+like.
+
+FEATURES
+--------
+
+-  Flexible extended blank circle
+-  Compatible with all series of M5Stack Core
+
+Interface
+---------
+
++-------------------+------------------+
+| LINE0             | LINE1            |
++===================+==================+
+| GND               | IO35(ADC1)       |
++-------------------+------------------+
+| GND               | IO36(ADC2)       |
++-------------------+------------------+
+| GND               | EN               |
++-------------------+------------------+
+| IO23(MOSI)        | IO25(DAC0)       |
++-------------------+------------------+
+| IO19(MISO)        | IO26(DAC1)       |
++-------------------+------------------+
+| IO18(EXT\_SCK)    | 3V3              |
++-------------------+------------------+
+| IO3(U1\_RX)       | IO1(U1\_TX)      |
++-------------------+------------------+
+| IO16(U2\_RX)      | IO17(U2\_TX)     |
++-------------------+------------------+
+| IO21(I2C\_SDA)    | IO22(I2C\_SCL)   |
++-------------------+------------------+
+| IO2               | IO5              |
++-------------------+------------------+
+| IO12(I2S\_SCLK)   | IO13             |
++-------------------+------------------+
+| IO15(I2S\_OUT)    | IO0              |
++-------------------+------------------+
+| HPOWR             | IO34             |
++-------------------+------------------+
+| HPOWR             | 5V               |
++-------------------+------------------+
+| HPOWR             | BAT              |
++-------------------+------------------+
+
+INCLUDES
+--------
+
+-  1x M5Stack PROTO Module
+-  User Manual
+
+DOCUMENTS
+---------
+
+-  `WebSite <https://m5stack.com>`__
+-  `GitHub <https://github.com/m5stack/M5Stack>`__
+

en/product-documents/modules/m5stack_proto_module.rst

@@ -0,0 +1,72 @@
+M5Stack PROTO Kit
+=================
+
+DESCRIPTION
+-----------
+
+The M5Stack PROTO Module is a flexible blank circle with 30 pins which
+could connect with all series of M5Stack Core. You can create any circle
+that could controlled by any M5Stack Core on M5Stack PROTO Module as you
+like.
+
+FEATURES
+--------
+
+-  Flexible extended blank circle
+-  Compatible with all series of M5Stack Core
+-  A environment detector - DHT12 Module
+
+Interface
+---------
+
++-------------------+------------------+
+| LINE0             | LINE1            |
++===================+==================+
+| GND               | IO35(ADC1)       |
++-------------------+------------------+
+| GND               | IO36(ADC2)       |
++-------------------+------------------+
+| GND               | EN               |
++-------------------+------------------+
+| IO23(MOSI)        | IO25(DAC0)       |
++-------------------+------------------+
+| IO19(MISO)        | IO26(DAC1)       |
++-------------------+------------------+
+| IO18(EXT\_SCK)    | 3V3              |
++-------------------+------------------+
+| IO3(U1\_RX)       | IO1(U1\_TX)      |
++-------------------+------------------+
+| IO16(U1\_RX)      | IO17(U2\_TX)     |
++-------------------+------------------+
+| IO21(I2C\_SDA)    | IO22(I2C\_SCL)   |
++-------------------+------------------+
+| IO2               | IO5              |
++-------------------+------------------+
+| IO12(I2S\_SCLK)   | IO13             |
++-------------------+------------------+
+| IO15(I2S\_OUT)    | IO0              |
++-------------------+------------------+
+| HPOWR             | IO34             |
++-------------------+------------------+
+| HPOWR             | 5V               |
++-------------------+------------------+
+| HPOWR             | BAT              |
++-------------------+------------------+
+
+INCLUDES
+--------
+
+-  1x M5Stack PROTO Module
+-  1x DHT12 Temperature & Humidity Sensor
+-  1x Bus Socket
+-  1x GROVE Cable
+-  1x Packing Box
+-  User Manual
+
+DOCUMENTS
+---------
+
+-  `WebSite <https://m5stack.com>`__
+-  `Example <https://github.com/m5stack/M5Stack/tree/master/examples/Advanced/Blynk/Post-DHT12>`__
+-  `GitHub <https://github.com/m5stack/M5Stack>`__
+

en/product-documents/tools/m5stack_usb_downloader.rst

@@ -0,0 +1,46 @@
+M5Stack USB Downloader
+======================
+
+DESCRIPTION
+-----------
+
+1. USB to URAT Chip. CP2104 supports automatic firmware download of
+   ESP32/ESP8266
+2. TXD light, RXD light, Power light and 6pin @ 2.54mm bus sockets.
+
+PARAMETER
+---------
+
++-------------+-----------+
+| PinNumber   | PinName   |
++=============+===========+
+| 1           | GND       |
++-------------+-----------+
+| 2           | GPIO0     |
++-------------+-----------+
+| 3           | EN        |
++-------------+-----------+
+| 4           | TXD       |
++-------------+-----------+
+| 5           | RXD       |
++-------------+-----------+
+| 6           | 3.3V      |
++-------------+-----------+
+
+NOTE
+~~~~
+
+There are two reserved pins(RTS, DTR) on M5Stack USB Downloader for
+other applications.
+
+INCLUDES
+--------
+
+-  1x M5Stack USB Downloader
+
+DOCUMENTS
+---------
+
+-  `Schematic <https://github.com/watson8544/M5Stack-UserGuide/blob/master/TOOLS_DOCS/USBtool.pdf>`__
+-  `UserGuide <https://github.com/watson8544/M5Stack-UserGuide/blob/master/TOOLS_DOCS/M5Stack-USB-Downloader-UserGuide.md>`__
+