diff --git a/docs/index.rst b/docs/index.rst index a97bff1c84..3bc78e9023 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -12,6 +12,7 @@ MicroPython documentation and references esp8266/quickref.rst esp32/quickref.rst rp2/quickref.rst + mimxrt/quickref.rst wipy/quickref.rst unix/quickref.rst zephyr/quickref.rst diff --git a/docs/library/machine.PWM.rst b/docs/library/machine.PWM.rst index 793c074a36..4b74355775 100644 --- a/docs/library/machine.PWM.rst +++ b/docs/library/machine.PWM.rst @@ -78,6 +78,13 @@ Methods With a single *value* argument the pulse width is set to that value. +Specific PWM class implementations +---------------------------------- + +The following concrete class(es) implement enhancements to the PWM class. + + | :ref:`pyb.Timer for PyBoard ` + Limitations of PWM ------------------ @@ -90,6 +97,11 @@ Limitations of PWM 80000000 / 267 = 299625.5 Hz, not 300kHz. If the divider is set to 266 then the PWM frequency will be 80000000 / 266 = 300751.9 Hz, but again not 300kHz. + Some ports like the RP2040 one use a fractional divider, which allow a finer + granularity of the frequency at higher frequencies by switching the PWM + pulse duration between two adjacent values, such that the resulting average + frequency is more close to the intended one, at the cost of spectral purity. + * The duty cycle has the same discrete nature and its absolute accuracy is not achievable. On most hardware platforms the duty will be applied at the next frequency period. Therefore, you should wait more than "1/frequency" before diff --git a/docs/library/machine.SDCard.rst b/docs/library/machine.SDCard.rst index b07ad37d39..cde0bd1d14 100644 --- a/docs/library/machine.SDCard.rst +++ b/docs/library/machine.SDCard.rst @@ -122,3 +122,46 @@ You can set the pins used for SPI access by passing a tuple as the *Note:* The current cc3200 SD card implementation names the this class :class:`machine.SD` rather than :class:`machine.SDCard` . + +mimxrt +`````` + +The SDCard module for the mimxrt port only supports access via dedicated SD/MMC +peripheral (USDHC) in 4-bit mode with 50MHz clock frequency exclusively. +Unfortunately the MIMXRT1011 controller does not support the USDHC peripheral. +Hence this controller does not feature the ``machine.SDCard`` module. + +Due to the decision to only support 4-bit mode with 50MHz clock frequency the +interface has been simplified, and the constructor signature is: + +.. class:: SDCard(slot=1) + :noindex: + +The pins used for the USDHC peripheral have to be configured in ``mpconfigboard.h``. +Most of the controllers supported by the mimxrt port provide up to two USDHC +peripherals. Therefore the pin configuration is performed using the macro +``MICROPY_USDHCx`` with x being 1 or 2 respectively. + +The following shows an example configuration for USDHC1:: + + #define MICROPY_USDHC1 \ + { \ + .cmd = { GPIO_SD_B0_02_USDHC1_CMD}, \ + .clk = { GPIO_SD_B0_03_USDHC1_CLK }, \ + .cd_b = { GPIO_SD_B0_06_USDHC1_CD_B },\ + .data0 = { GPIO_SD_B0_04_USDHC1_DATA0 },\ + .data1 = { GPIO_SD_B0_05_USDHC1_DATA1 },\ + .data2 = { GPIO_SD_B0_00_USDHC1_DATA2 },\ + .data3 = { GPIO_SD_B0_01_USDHC1_DATA3 },\ + } + +If the card detect pin is not used (cb_b pin) then the respective entry has to be +filled with the following dummy value:: + + #define USDHC_DUMMY_PIN NULL , 0 + +Based on the definition of macro ``MICROPY_USDHC1`` and/or ``MICROPY_USDHC2`` +the ``machine.SDCard`` module either supports one or two slots. If only one of +the defines is provided, calling ``machine.SDCard()`` or ``machine.SDCard(1)`` +will return an instance using the respective USDHC peripheral. When both macros +are defined, calling ``machine.SDCard(2)`` returns an instance using USDHC2. diff --git a/docs/library/network.LAN.rst b/docs/library/network.LAN.rst new file mode 100644 index 0000000000..58bd61ebbd --- /dev/null +++ b/docs/library/network.LAN.rst @@ -0,0 +1,93 @@ +.. currentmodule:: network +.. _network.LAN: + +class LAN -- control an Ethernet module +======================================= + +This class allows you to control the Ethernet interface. The PHY hardware type is board-specific. + +Example usage:: + + import network + nic = network.LAN(0) + print(nic.ifconfig()) + + # now use socket as usual + ... + + +Constructors +------------ + +.. class:: LAN(id, *, phy_type=, phy_addr=, phy_clock=) + + Create a LAN driver object, initialise the LAN module using the given + PHY driver name, and return the LAN object. + + Arguments are: + + - *id* is the number of the Ethernet port, either 0 or 1. + - *phy_type* is the name of the PHY driver. For most board the on-board PHY has to be used and + is the default. Suitable values are port specific. + - *phy_addr* specifies the address of the PHY interface. As with *phy_type*, the hardwired value has + to be used for most boards and that value is the default. + - *phy_clock* specifies, whether the data clock is provided by the Ethernet controller or the PYH interface. + The default value is the one that matches the board. If set to ``True``, the clock is driven by the + Ethernet controller, otherwise by the PHY interface. + + For example, with the Seeed Arch Mix board you can use:: + + nic = LAN(0, phy_type=LAN.PHY_LAN8720, phy_addr=2, phy_clock=False) + +Methods +------- + +.. method:: LAN.active([state]) + + With a parameter, it sets the interface active if *state* is true, otherwise it + sets it inactive. + Without a parameter, it returns the state. + +.. method:: LAN.isconnected() + + Returns ``True`` if the physical Ethernet link is connected and up. + Returns ``False`` otherwise. + +.. method:: LAN.status() + + Returns the LAN status. + +.. method:: LAN.ifconfig([(ip, subnet, gateway, dns)]) + + Get/set IP address, subnet mask, gateway and DNS. + + When called with no arguments, this method returns a 4-tuple with the above information. + + To set the above values, pass a 4-tuple with the required information. For example:: + + nic.ifconfig(('192.168.0.4', '255.255.255.0', '192.168.0.1', '8.8.8.8')) + +.. method:: LAN.config(config_parameters) + + Sets or gets parameters of the LAN interface. The only parameter that can be + retrieved is the MAC address, using:: + + mac = LAN.config("mac") + + The parameters that can be set are: + + - ``trace=n`` sets trace levels; suitable values are: + + - 2: trace TX + - 4: trace RX + - 8: full trace + + - ``low_power=bool`` sets or clears low power mode, valid values being ``False`` + or ``True``. + + +Specific LAN class implementations +---------------------------------- + +On the mimxrt port, suitable values for the *phy_type* constructor argument are: +``PHY_KSZ8081``, ``PHY_DP83825``, ``PHY_DP83848``, ``PHY_LAN8720``, ``PHY_RTL8211F``. diff --git a/docs/library/network.rst b/docs/library/network.rst index 1bd7e303bb..361e664b54 100644 --- a/docs/library/network.rst +++ b/docs/library/network.rst @@ -152,6 +152,7 @@ provide a way to control networking interfaces of various kinds. network.WLANWiPy.rst network.CC3K.rst network.WIZNET5K.rst + network.LAN.rst Network functions ================= diff --git a/docs/mimxrt/general.rst b/docs/mimxrt/general.rst new file mode 100644 index 0000000000..d08e180e7f --- /dev/null +++ b/docs/mimxrt/general.rst @@ -0,0 +1,92 @@ +.. _mimxrt_general: + +General information about the MIMXRT port +========================================= + +The i.MXRT MCU family is a high performance family of devices made by NXP. +Based on an ARM7 core, they provide many on-chip I/O units for building +small to medium sized devices. + +Multitude of boards +------------------- + +There is a multitude of modules and boards from different sources which carry +an i.MXRT chip. MicroPython aims to provide a generic port which runs on +as many boards/modules as possible, but there may be limitations. The +NXP IMXRT1020-EVK and the Teensy 4.0 and Teensy 4.1 development boards are taken +as reference for the port (for example, testing is performed on them). +For any board you are using please make sure you have a data sheet, schematics +and other reference materials so you can look up any board-specific functions. + +The following boards are supported by the port: + +- MIMXRT1010-EVK +- MIMXRT1020-EVK +- MIMXRT1050-EVK +- MIMXRT1060-EVK +- MIMXRT1064-EVK +- Teensy 4.0 +- Teensy 4.1 + +Supported MCUs +-------------- + ++-------------+--------------------+-------------------------+ +| Product | CPU | Memory | ++=============+====================+=========================+ +| i.MX RT1064 | Cortex-M7 @600 MHz | 1 MB SRAM, 4 MB Flash | ++-------------+--------------------+-------------------------+ +| i.MX RT1061 | Cortex-M7 @600 MHz | 1 MB SRAM | ++-------------+--------------------+-------------------------+ +| i.MX RT1062 | Cortex-M7 @600 MHz | 1 MB SRAM | ++-------------+--------------------+-------------------------+ +| i.MX RT1050 | Cortex-M7 @600 MHz | 512 kB SRAM | ++-------------+--------------------+-------------------------+ +| i.MX RT1020 | Cortex-M7 @500 MHz | 256 kB SRAM | ++-------------+--------------------+-------------------------+ +| i.MX RT1010 | Cortex-M7 @500 MHz | 128 kB SRAM | ++-------------+--------------------+-------------------------+ + +Note: Most of the controllers do not have internal flash memory. Therefore +their flash capacity is dependent on an external flash chip. + +To make a generic MIMXRT port and support as many boards as possible the +following design and implementation decision were made: + +* GPIO pin numbering is based on the board numbering as well as on the + MCU numbering. Please have the manual/pin diagram of your board at hand + to find correspondence between your board pins and actual i.MXRT pins. +* All MCU pins are supported by MicroPython but not all are usable on any given board. + +Technical specifications and SoC datasheets +------------------------------------------- + +The data sheets and other reference material for i.MXRT chip are available +from the vendor site: https://www.nxp.com/products/processors-and-microcontrollers/arm-microcontrollers/i-mx-rt-crossover-mcus:IMX-RT-SERIES . +They are the primary reference for the chip technical specifications, capabilities, +operating modes, internal functioning, etc. + +For your convenience, a few technical specifications are provided below: + +* Architecture: ARM Cortex M7 +* CPU frequency: up to 600MHz +* Total RAM available: up to 1 MByte (see table) +* BootROM: 96KB +* External FlashROM: code and data, via SPI Flash; usual size 2 - 8 MB + Some boards provide additional external RAM and SPI flash. +* GPIO: up to 124 (GPIOs are multiplexed with other functions, including + external FlashROM, UART, etc.) +* UART: 4 or 8 RX/TX UART. Hardware handshaking is supported by the MCU, + but the boards used for testing do not expose the signals. +* SPI: 2 or 4 low power SPI interfaces (software implementation available on every pin) +* I2C: 2 or 4 low power I2C interfaces (software implementation available on every pin) +* I2S: 3 I2S interfaces +* ADC: one or two 12-bit SAR ADC converters +* Ethernet controller +* Programming: using BootROM bootloader from USB - due to external FlashROM + and always-available BootROM bootloader, the MIMXRT is not brickable + +The lower numbers for UART, SPI and I2C apply to the i.MXRT 101x MCU. + +For more information see the i.MXRT data sheets or reference manuals. +NXP provides software support through it's SDK packages. diff --git a/docs/mimxrt/img/teensy_4.1.jpg b/docs/mimxrt/img/teensy_4.1.jpg new file mode 100644 index 0000000000..0a09f68ea4 Binary files /dev/null and b/docs/mimxrt/img/teensy_4.1.jpg differ diff --git a/docs/mimxrt/quickref.rst b/docs/mimxrt/quickref.rst new file mode 100644 index 0000000000..b87a343bd8 --- /dev/null +++ b/docs/mimxrt/quickref.rst @@ -0,0 +1,864 @@ +.. _mimxrt_quickref: + +Quick reference for the i.MXRT family +===================================== + +.. image:: img/teensy_4.1.jpg + :alt: Teensy 4.1 board + :width: 640px + +The Teensy 4.1 board. + +Below is a quick reference for i.MXRT-based boards. If it is your first time +working with this board it may be useful to get an overview of the microcontroller: + +.. toctree:: + :maxdepth: 1 + + general.rst + tutorial/intro.rst + + +Installing MicroPython +---------------------- + +See the corresponding section of tutorial: :ref:`mimxrt_intro`. It also includes +a troubleshooting subsection. + +General board control +--------------------- + +The MicroPython REPL is on the USB port, configured in VCP mode. +Tab-completion is useful to find out what methods an object has. +Paste mode (ctrl-E) is useful to paste a large slab of Python code into +the REPL. + +The :mod:`machine` module:: + + import machine + + machine.freq() # get the current frequency of the CPU + +Delay and timing +---------------- + +Use the :mod:`time