Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Machine clean & docs update #99

Merged
merged 2 commits into from
Oct 17, 2023
Merged

Machine clean & docs update #99

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
43490be
ports/psoc6: Cleanup of previous machine_pin implementation.
jaenrig-ifx Oct 13, 2023
567a339
docs/psoc6: Modificatons in machine module.
jaenrig-ifx Oct 13, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
60 changes: 30 additions & 30 deletions docs/psoc6/feature_list.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,25 +10,25 @@ Enabled modules
* cmath
* gc
* math
* uarray
* uasyncio
* ubinascii
* ucollections
* uerrno
* uhashlib
* uheapq
* uio
* ujson
* uos
* urandom
* ure
* uselect
* usocket
* ussl
* ustruct
* usys
* utime
* uzlib
* array
* asyncio
* binascii
* collections
* errno
* hashlib
* heapq
* io
* json
* os
* random
* re
* select
* socket
* ssl
* struct
* sys
* time
* zlib


* Micropython specific modules and libraries
Expand All @@ -46,7 +46,7 @@ Enabled modules
* ADCBlock

* micropython
* ucryptolib
* cryptolib
* uctypes
* network

Expand All @@ -62,7 +62,7 @@ Not yet enabled

* Micropython specific modules and libraries
* btree
* ubluetooth
* bluetooth


Table :ref:`configuration details <table_mpy_configuration>` below lists specific settings deviating from the configuration as per config level as well as functionality not yet implemented:
Expand All @@ -74,29 +74,29 @@ Table :ref:`configuration details <table_mpy_configuration>` below lists specifi
+=================+======================================================================================================================+
| gc | Option ``MICROPY_ENABLE_GC`` enabled. |
+-----------------+----------------------------------------------------------------------------------------------------------------------+
| uhashlib | Options ``MICROPY_PY_UHASHLIB_MD5``, ``MICROPY_PY_UHASHLIB_SHA1``, ``MICROPY_PY_UHASHLIB_SHA256`` enabled. |
| hashlib | Options ``MICROPY_PY_UHASHLIB_MD5``, ``MICROPY_PY_UHASHLIB_SHA1``, ``MICROPY_PY_UHASHLIB_SHA256`` enabled. |
+-----------------+----------------------------------------------------------------------------------------------------------------------+
| uos | Support for LFS2 and FAT, LFS2 enabled by default. FS mounted on external flash at "/flash". |
| os | Support for LFS2 and FAT, LFS2 enabled by default. FS mounted on external flash at "/flash". |
| | |
| | Options ``MICROPY_PY_OS_DUPTERM``, ``MICROPY_PY_UOS_GETENV_PUTENV_UNSETENV``, ``MICROPY_PY_UOS_INCLUDEFILE``, |
| | ``MICROPY_PY_UOS_SYSTEM``, ``MICROPY_PY_UOS_UNAME``, ``MICROPY_VFS_LFS2`` enabled. |
| | |
| | Function *urandom()* not yet implemented. Requires implementing *mp_uos_urandom()* and setting option |
| | ``MICROPY_PY_UOS_URANDOM``. |
+-----------------+----------------------------------------------------------------------------------------------------------------------+
| urandom | Function *seed()* not yet implemented. |
| random | Function *seed()* not yet implemented. |
+-----------------+----------------------------------------------------------------------------------------------------------------------+
| ure | Options ``MICROPY_PY_URE_DEBUG``, ``MICROPY_PY_URE_MATCH_GROUPS``, ``MICROPY_PY_URE_MATCH_SPAN_START_END`` enabled. |
| re | Options ``MICROPY_PY_URE_DEBUG``, ``MICROPY_PY_URE_MATCH_GROUPS``, ``MICROPY_PY_URE_MATCH_SPAN_START_END`` enabled. |
+-----------------+----------------------------------------------------------------------------------------------------------------------+
| usocket | Options ``MICROPY_PY_USOCKET`` enabled. |
| socket | Options ``MICROPY_PY_USOCKET`` enabled. |
+-----------------+----------------------------------------------------------------------------------------------------------------------+
| ussl | Options ``MICROPY_PY_USSL`` enabled. Has 2 failing tests. |
| ssl | Options ``MICROPY_PY_USSL`` enabled. Has 2 failing tests. |
+-----------------+----------------------------------------------------------------------------------------------------------------------+
| usys | Options ``MICROPY_PY_SYS_EXC_INFO`` enabled. |
| sys | Options ``MICROPY_PY_SYS_EXC_INFO`` enabled. |
+-----------------+----------------------------------------------------------------------------------------------------------------------+
| utime | Enabled through HAL functions based on machine.RTC module. Option ``MICROPY_PY_UTIME_MP_HAL`` enabled. |
| time | Enabled through HAL functions based on machine.RTC module. Option ``MICROPY_PY_UTIME_MP_HAL`` enabled. |
+-----------------+----------------------------------------------------------------------------------------------------------------------+
| ucryptolib | Options ``MICROPY_PY_UCRYPTOLIB``, ``MICROPY_PY_UCRYPTOLIB_CTR``, ``MICROPY_PY_UCRYPTOLIB_CONSTS`` enabled. |
| cryptolib | Options ``MICROPY_PY_UCRYPTOLIB``, ``MICROPY_PY_UCRYPTOLIB_CTR``, ``MICROPY_PY_UCRYPTOLIB_CONSTS`` enabled. |
+-----------------+----------------------------------------------------------------------------------------------------------------------+
| machine | Functions not yet implemented: *lightsleep()*, *deepsleep()*, *wake_reason()*, *time_pulse_us()*, *rng()*. |
| | |
Expand Down
82 changes: 50 additions & 32 deletions docs/psoc6/quickref.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -87,9 +87,9 @@ An instance of the :mod:`machine.Pin` class can be created by invoking the const

from machine import Pin

p0 = Pin('P13_7', Pin.OUT, Pin.PULL_DOWN, value=Pin.STATE_LOW) # create output pin on pin P13_7,
# with pull-down resistor enabled,
# with initial value 0 (STATE_LOW)
p0 = Pin('P13_7', Pin.OUT, Pin.PULL_DOWN, value=0) # create output pin on pin P13_7,
# with pull-down resistor enabled,
# with initial value 0 (low)


Additionally, with any combination of parameters (except the Pin number or ``id`` which should be passed mandatorily), a :mod:`machine.Pin` object with various configuration levels can be instantiated. In these cases, the :meth:`Pin.init` function has to be called proactively to set the other necessary configurations, as needed.
Expand All @@ -115,19 +115,22 @@ Similar to CPython, the parameters can be passed in any order if keywords are us

from machine import Pin

p0 = Pin(id='P13_7', value=Pin.STATE_LOW, pull=Pin.PULL_DOWN, mode=Pin.OUT) # create output pin on pin P13_7,
# with pull-down resistor enabled,
# with initial value 0 (STATE_LOW)
p0 = Pin(id='P13_7', value=0, pull=Pin.PULL_DOWN, mode=Pin.OUT) # create output pin on pin P13_7,
# with pull-down resistor enabled,
# with initial value 0 (low)


p1 = Pin('P0_0', Pin.OUT, None, value=Pin.STATE_HIGH) # create output pin on pin P0_0,
# with pull as NONE,
# with initial value 1 (STATE_HIGH)
p1 = Pin('P0_0', Pin.OUT, None, value=1) # create output pin on pin P0_0,
# with pull as NONE,
# with initial value 1 (high)

Note that the parameters such as ``value`` can only be passed as keyword arguments.

..
TODO: add ``drive`` and ``alt`` when implemented
.. note::

The following constructor arguments are NOT supported in this port:
* ``drive``. This configuration is automatically handled by the constructor and abstracted to the user.
* ``alt``. Alternative functionality is directly handled by the respective machine peripherals classes.

Methods
^^^^^^^
Expand All @@ -137,16 +140,6 @@ Methods
Set pin value to its complement.


Constants
^^^^^^^^^
The following constants are used to configure the pin objects in addition to the ones mentioned in the :mod:`machine.Pin` class.

.. data:: Pin.STATE_LOW
Pin.STATE_HIGH

Selects the pin value.


There's a higher-level abstraction :ref:`machine.Signal <machine.Signal>`
which can be used to invert a pin. Useful for illuminating active-low LEDs
using ``on()`` or ``value(1)``.
Expand Down Expand Up @@ -180,6 +173,14 @@ scl P6_0 P9_0
sda P6_1 P9_1
===== =========== ============

..

TODO: This is only applicable to the CY8CPROTO-062-4343W. This does not belong here.
TODO: Define approach on how the user gets to know the pinout diagram, alternate function of each board
- From board manual?
- From datasheet?
- To create a pinout diagram?


The driver is accessed via :ref:`machine.I2C <machine.I2C>`

Expand All @@ -192,19 +193,19 @@ initialized and configured to work in master mode. The maximum supported frequen
::

from machine import I2C
i2c = I2C(0,scl='P6_0',sda='P6_1',freq=400000)
i2c = I2C(0, scl='P6_0', sda='P6_1',freq=400000)

Here, ``id=0`` should be passed mandatorily which selects the ``master`` mode operation.
Here, ``id=0`` should be passed mandatorily which selects the ``master`` mode operation. The ``scl`` and ``sda`` pins are also required.

::

from machine import I2C
i2c = I2C(0) #I2C is initialized & configured with default scl, sda pin & frequency
i2c = I2C(0, scl='P6_0', sda='P6_1') #I2C is initialized & configured with default frequency

::

from machine import I2C
i2c = I2C(0,scl='P9_0',sda='P9_1',freq=400000) #I2C is initialised & configured with given scl,sda pins & frequency
i2c = I2C(0, scl='P9_0', sda='P9_1', freq=400000) #I2C is initialised & configured with given scl,sda pins & frequency

Methods
^^^^^^^
Expand Down Expand Up @@ -411,8 +412,17 @@ MISO P9_1 P6_1 P10_1
SCK P9_2 P6_2 P10_2
===== =========== ============ ============

..

TODO: This is only applicable to the CY8CPROTO-062-4343W. This does not belong here.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree this is specific to only proto board. But also, in mpy official docs other ports which support multiple boards still have I guess the most common board reference (pinouts etc.) in quickref. But we will have to move around our docs a bit. Maybe have common port docs and point out to getting started with different boards or something.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agree, other ports show only one board. We have to discuss this in the strategy, and find our compromise for maintainability - user friendliness.

TODO: Define approach on how the user gets to know the pinout diagram, alternate function of each board
- From board manual?
- From datasheet?
- To create a pinout diagram?

Refer `PSoC 6 MCU: CY8C62x8, CY8C62xA Datasheet <https://www.infineon.com/dgdl/Infineon-PSOC_6_MCU_CY8C62X8_CY8C62XA-DataSheet-v18_00-EN.pdf?fileId=8ac78c8c7d0d8da4017d0ee7d03a70b1>`_
for additional details regarding all the SPI capable pins.
for additional details regarding all the SPI capable pins. The pins ``sck``, ``mosi`` and ``miso`` *must* be specified when
initialising Software SPI.

The driver is accessed via :ref:`machine.SPI <machine.SPI>`

Expand All @@ -425,7 +435,7 @@ SPI object is created with default settings or settings of previous initializati
::

from machine import SPI
spi = SPI(0) # Default assignment: id=0, sck=P9_2 ,MOSI=P9_0, MISO=P9_1, baudrate=1000000, Polarity=0, Phase=0, bits=8, firstbit=SPI.MSB
spi = SPI(0, sck='P11_2', mosi='P11_0', miso='P11_1') # Default assignment: id=0, SCK=P11_2 ,MOSI=P11_0, MISO=P11_1
spi.init()

Management of a CS signal should happen in user code (via machine.Pin class).
Expand All @@ -441,7 +451,7 @@ If the constructor is called with any additional parameters then SPI object is c

::

spi = SPI(0, baudrate=2000000) #object is created & initialised with baudrate=2000000 & default parameters
spi = SPI(0, sck='P11_2', mosi='P11_0', miso='P11_1', baudrate=2000000) #object is created & initialised with baudrate=2000000 & default parameters
spi = SPI(0, baudrate=1500000, polarity=1, phase=1, bits=8, firstbit=SPI.LSB, sck='P11_2', mosi='P11_0', miso='P11_1')

Methods
Expand Down Expand Up @@ -473,9 +483,9 @@ following pins : "P10_0" - "P10_5".

Use the :ref:`machine.ADC <machine.ADC>` class::

from machine import ADC, Pin
from machine import ADC

adc = ADC(Pin("P10_0")) # create an ADC object on ADC pin
adc = ADC("P10_0") # create an ADC object on ADC pin
val = adc.read_u16() # read a raw analog value in the range 0-65535
val = adc.read_uv() # read an analog value in micro volts

Expand All @@ -499,16 +509,24 @@ PSoC6 supports only 1 12-bit SAR ADC with the following channel to pin mapping a
| 5 | P10_5 |
+---------+-------+

..

TODO: This is only applicable to the CY8CPROTO-062-4343W. This does not belong here.
TODO: Define approach on how the user gets to know the pinout diagram, alternate function of each board
- From board manual?
- From datasheet?
- To create a pinout diagram?

.. note::
Arbitrary connection of ADC channels to GPIO is not supported. Specifying a pin that is not connected to this block,
or specifying a mismatched channel and pin, will raise an exception.

To use the APIs:
::

from machine import ADCBlock, Pin
from machine import ADCBlock

adcBlock = ADCBlock(0, bits=12) # create an ADCBlock 0 object
adc = adcBlock.connect(0, Pin("P10_0")) # connect channel 0 to pin P10_0
adc = adcBlock.connect(0, "P10_0") # connect channel 0 to pin P10_0
val = adc.read_uv() # read an analog value in micro volts

1 change: 1 addition & 0 deletions ports/psoc6/modules/machine/machine_adc.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@
#define MICROPY_INCLUDED_MACHINE_ADC_H

#include "machine_adcblock.h"
#include "machine_pin_phy.h"

typedef struct _machine_adc_obj_t {
mp_obj_base_t base;
Expand Down
2 changes: 0 additions & 2 deletions ports/psoc6/modules/machine/machine_adcblock.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,8 +11,6 @@
#define MAX_BLOCKS (1)
#define MAX_CHANNELS (6)

#include "machine_pin.h"

typedef struct _machine_adc_obj_t machine_adc_obj_t; /* Forward declaration of adc_obj */

typedef struct _machine_adcblock_obj_t {
Expand Down
8 changes: 4 additions & 4 deletions ports/psoc6/modules/machine/machine_pin.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@

// port-specific includes
#include "modmachine.h"
#include "machine_pin.h"
#include "machine_pin_phy.h"
#include "extmod/virtpin.h"
#include "mplogger.h"
#include "cyhal.h"
Expand Down Expand Up @@ -178,7 +178,7 @@ static bool machine_pin_is_inited(machine_pin_io_obj_t *self) {
STATIC mp_obj_t machine_pin_obj_init_helper(machine_pin_io_obj_t *self, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) {
mplogger_print("init helper function called\n");

enum {ARG_mode, ARG_pull, ARG_value, ARG_drive}; // , ARG_alt};
enum {ARG_mode, ARG_pull, ARG_value};
static const mp_arg_t allowed_args[] = {
{MP_QSTR_mode, MP_ARG_OBJ, {.u_rom_obj = MP_ROM_NONE}},
{MP_QSTR_pull, MP_ARG_OBJ, {.u_rom_obj = MP_ROM_NONE}},
Expand Down Expand Up @@ -223,7 +223,7 @@ STATIC mp_obj_t machine_pin_obj_init_helper(machine_pin_io_obj_t *self, size_t n
}

// Machine Pin methods - port-specific definitions
// Pin constructor(id,mode,pull,value=value,drive=drive,alt=alt)
// Pin constructor(id,mode,pull,value=value)
mp_obj_t mp_pin_make_new(const mp_obj_type_t *type, size_t n_args, size_t n_kw, const mp_obj_t *args) {
mplogger_print("%q constructor invoked\n", MP_QSTR_Pin);

Expand Down Expand Up @@ -272,7 +272,7 @@ STATIC mp_obj_t machine_pin_value(size_t n_args, const mp_obj_t *args) {
STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(machine_pin_value_obj, 1, 2, machine_pin_value);

// instantiates obj of Pin class
// Pin.init(mode,pull,value=value,drive=drive,alt=alt)
// Pin.init(mode,pull,value=value)
STATIC mp_obj_t machine_pin_obj_init(size_t n_args, const mp_obj_t *args, mp_map_t *kw_args) {
return machine_pin_obj_init_helper(args[0], n_args - 1, args + 1, kw_args);
}
Expand Down
9 changes: 0 additions & 9 deletions ports/psoc6/modules/machine/machine_pin.h
View file
Open in desktop

This file was deleted.

2 changes: 1 addition & 1 deletion ports/psoc6/mphalport.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@


// port-specific includes
#include "modules/machine/machine_pin.h"
#include "modules/machine/machine_pin_phy.h"

extern cyhal_rtc_t psoc6_rtc;
extern cyhal_timer_t psoc6_timer;
Expand Down
1 change: 1 addition & 0 deletions ports/psoc6/mphalport.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,7 @@
// port-specific includes



#define MP_HAL_PIN_FMT "%u"
#define mp_hal_pin_obj_t uint

Expand Down
Loading