Expand "CircuitPython Expectations"

[kattni]

Expand the CircuitPython Expectations page to include more FAQs. If there are other things you are finding people constantly asking, please comment on this issue! Thanks!

Potentially combine with CircuitPython Built-Ins page.

Needed additions:

• Lack of interrupts (IRQs)

• WINC1500 and Feather M0 support

• Heap memory usage

• MemoryError and how to avoid it

• AVR CP support

• Difference between Express and non-Express boards

• Limits on ints and floats on M0 boards

• ESP32 support

• Switching between Arduino and CircuitPython

• Things to watch out for! (From CircuitPython Built-Ins)

[ladyada]

people ask about WINC1500 + Feather M0 support - it wont fit into M0 flash :/

[ladyada]

• can AVRs such as ATmega328 or ATmega2560 run CP?
• differences between "Express" and "Not Express" boards

@kattni - check discord and hackchat logs for other common Qs :)

[ladyada]

for M0, at least, we store numbers in 30 bits. that means there's a limit/range on both ints (0 to 0x7FFFFFF ) and floats #572
(check me @dhalbert )

[dhalbert]

Integers are 31 bits signed. Floats are 30 bits (the bottom two mantissa bits are dropped). It's a variable encoding: the lowest bit == 1 means integer; when == 0, the second lowest bit helps specify the kind of object. When two encoding bits are used, the 32-bit value is a 30-bit float or a 4-byte-aligned object pointer or a "qstr" (a static string pointer). See comment below from py/obj.h. There are multiple alternative encodings provided by MicroPython. For atmel-samd and esp8266, we use MICROPY_OBJ_REPR_C. A few ports use other representations.

// A MicroPython object is a machine word having the following form (called R):
//  - iiiiiiii iiiiiiii iiiiiiii iiiiiii1 small int with 31-bit signed value
//  - 01111111 1qqqqqqq qqqqqqqq qqqqq110 str with 20-bit qstr value
//  - s1111111 10000000 00000000 00000010 +/- inf
//  - s1111111 1xxxxxxx xxxxxxxx xxxxx010 nan, x != 0
//  - seeeeeee efffffff ffffffff ffffff10 30-bit fp, e != 0xff
//  - pppppppp pppppppp pppppppp pppppp00 ptr (4 byte alignment)
// Str and float stored as O = R + 0x80800000, retrieved as R = O - 0x80800000.
// This makes strs easier to encode/decode as they have zeros in the top 9 bits.
// This scheme only works with 32-bit word size and float enabled.
#define MICROPY_OBJ_REPR_C (2)

[sommersoft]

Totally flaked on adding this after the meeting this week...

ESP32: When is it coming to CircuitPython?

The summarized standard answer I've seen, and given, is that we're not currently developing for it and will pull from MicroPython once their dev is complete. Also, we have no ETA.

[ladyada]

Memory Error, and how to avoid it:
#569 (comment)

[jallwine]

Not sure if this qualifies as something that is asked constantly, but this page has a couple issues that I ran into when trying to read serial data with the CircuitPython on the Circuit Playground Express (CPX): https://github.com/AllwineDesigns/CircuitPythonSerialGlitchiness

Things that I think are worth noting on an FAQ or troubleshooting page are:

• The USB serial connection is only accessible using stdin/stdout.
• Reading from stdin requires blocking your script.
• CircuitPython uses the serial connection for controlling the running script
  • When Ctrl+C (3) and Ctrl+D (4) characters are sent, they trigger specific behaviors.
  • This means if a program sends raw binary data 3 or 4, your CircuitPython script won't necessarily read that data (sending 3 kills your script and enters the REPL, sending 4 restarts the script).
• Carriage return characters (\r or 13) are replaced with Newline characters (\n or 10).
• One way to avoid these issues is to use a separate USB to serial cable and hook them up to the RX and TX pins of the CPX.
  • You can then use busio.UART to read the serial data without worrying about CircuitPython interfering with the data.
  • busio.UART also has timeout capabilities, so you can avoid blocking while waiting for data to come in.

[kattni]

Include the following from CircuitPython Built-Ins (some of this is already included):
Things to watch out for!

• The wide body of python libraries have not been ported over, so while we wish you could import numpy, numpy isn't available. So you may have to port some code over yourself!
• For the ATSAMD21 based boards (Feather M0, Metro M0, Trinket M0, Gemma M0, Circuit PlayGround Express) there's a limited amount of RAM, we've found you can have about 250-ish lines of python (that's with various libraries) before you hit MemoryErrors. The upcoming SAMD51 chipset will help with that a ton but its not yet available)
• Non-Express boards like Trinket M0 and Gemma M0 and non-Express Feathers do not include all of the hardware support. For example, audioio and bitbangio are not included.
• Integers can only be up to 31 bits. Integers of unlimited size are not supported.
• We keep up with MicroPython stable releases, so check out the core 'differences' they document here.

[caternuson]

How about an acronym decoder ring, with links.
CP = CircuitPython (link to welcome to guide)
CPC = Circuit Playground Classic (link to PID 3000)
CPX = Circuit Playground Express (link to PID 3333)

[tannewt]

@kattni Mind doing this soon so we can close this issue?

[kattni]

@tannewt Yep I'll get it on my list.

[kattni]

I've begun working on this. I will be pinging various people for help with their suggestions if needed.

[kattni]

This is ready to go! We can always add more as more common questions or important information come up.

[ladyada]

reviewed and this is gooood!