search

adafruit / circuitpython

CircuitPython - a Python implementation for teaching coding with microcontrollers
https://circuitpython.org
Other
4.06k stars 1.2k forks source link

document port, chip, and board limitations #6930

Closed tlyu closed 1 year ago

tlyu commented 2 years ago

The documentation pages for _bleio don't clearly indicate that there is only partial BLE support for the espressif port. (Implementation is in progress and tracked by #5926.) This should be documented clearly in more places to avoid disappointing users who might purchase these devices hoping to have full BLE support in CircuitPython. I don't know offhand whether it will be easier to add a note to the support status of each board in the _bleio module or whether it makes more sense to add a warning near the top of the text of the _bleio documentation.

The relevant product pages should also be updated, but that probably gets done elsewhere.

dhalbert commented 2 years ago

I think this is a more general problem of finding a consistent way of noting what is not implemented and what works.

In general we have noted these kinds of limitations in the Learn Guides for each board. Many pages are shared or "mirrored" so this does not make guide maintenance onerous as it sounds. Sometimes we forget to note such things.

We could make these notes in readthedocs, which comes from shared-bindings. But many beginners do not know about readthedocs. Or we could perhaps make it in some notes that are per port, and possibly per board in some cases. Perhaps there would be "limitations" file. Then that info has to get published somewhere. I think this is worth discussing maybe in a Monday meeting, and I will also bring it up among staff.

mlg556 commented 1 year ago

just wanted to add that I was bitten by this recently. I bought a ESP32-S3-DevKitC-1-N8 to build a BLE HID keypad, thinking it would work since I saw "_bleio" in the available modules, but I'm getting a NotImplementedError when trying to initialize a Service.

of course I'm sure it will be supported eventually, and I can always try micropython, but it was a bit of a let-down 😅

dhalbert commented 1 year ago

I have generalized the title of this bug.

@jepler @kattni @tlyu @caternuson I wrote a draft page for the "Welcome to CircuitPython" guide (it does not have to stay there) that documents port and board-specific limitations, mostly of built-in modules. I found all these by looking for placeswhere NotImplementedError was called, and then added a few more things. The page is not published, but you can view it at this temporary link: https://learn.adafruit.com/welcome-to-circuitpython/board-and-port-specific-limitations?preview_token=WsdVgHQVBTr9iHLerIfyWA.

Does a Guide page make sense for this kind of info? These limitations could also be documented in RTD, but a lot of people don't dig into that initially. As we add new features, this page will need to be revised, but that's true of anything.

I originally thought this might be some .md or .rst files in the source tree, in each port, that got collected somewhere into RTD, but it was easier to do as a guide page, and the information doesn't necessarily all divide neatly into ports.

We can discuss this in our internal meeting, in "In the Weeds" in the weekly meeting, and/or in #circuitpython-dev.

anecdata commented 1 year ago

This page is really good. A couple of questions on Pico W:

DHCP client not yet available.

Something beyond this?

>>> wifi.radio.ipv4_address
192.168.6.201
>>> wifi.radio.ipv4_gateway
192.168.4.1
>>> wifi.radio.ipv4_subnet
255.255.252.0

IPV4 DNS not yet available.

DNS lookups are available, but not setting custom DNS server(s).

>>> ipaddress.ip_address(pool.getaddrinfo("adafruit.com", 443)[0][4][0])
104.20.38.240
dhalbert commented 1 year ago

I can also refactor the notes on that page into the appropriate //| documentation in the source code. I think it may be good to have it in two places, sorted by port in one place and by built-in module in another.

kairos0ne commented 1 year ago

Why do you restrict the import of the module adafruit_ble if the board is not supported. It seems strange to do such a thing given the market offering of the airlift coprocessor ? 

Traceback (most recent call last):
  File "main.py", line 16, in <module>
  File "adafruit_ble/__init__.py", line 25, in <module>
ImportError: no module named '_bleio'
dhalbert commented 1 year ago

The page is not published, but you can view it at this temporary link: https://learn.adafruit.com/welcome-to-circuitpython/board-and-port-specific-limitations?preview_token=WsdVgHQVBTr9iHLerIfyWA.

We ended up not doing this. Instead, there are some limitations listed in https://learn.adafruit.com/welcome-to-circuitpython/frequently-asked-questions. In the ReadTheDocs pages, there are now Limitations: sections describing various port-specific limitations.

dhalbert commented 1 year ago

Why do you restrict the import of the module adafruit_ble if the board is not supported. It seems strange to do such a thing given the market offering of the airlift coprocessor

adafruit_ble depends on _bleio. There are several implementations of _bleio:

  1. nRF native implementation.
  2. Espressif native implementation. This implementation is incomplete: see https://learn.adafruit.com/welcome-to-circuitpython/frequently-asked-questions#faq-3129409
  3. BLE HCI implementation done by a co-processor, e.g. the AirLift co-processor.

"3." _bleio is omitted from boards that don't have space for it. Which board are you using?

kairos0ne commented 1 year ago

I have tried with the featherS2 and featherS3 by unexpected maker and I’ve also tried the adafruit Rp2040 feather I’ve had no such luck with any of them but the strangest thing is I had it working on 6.x circuit python with the rp2040 but not amnymore on the later versions.

kairos0ne commented 1 year ago

Obviously I meant along side the Airlift Featherwing, plz excuse my tone I’m a little frustrated that I bought three boards and two airlifts – my project requires BLE only to find that its not supported for these boards. The Airlift coprocessor is advertised as a BLE solution for any feather based board and if there are three that it in fact doesn’t work with then people should know that before they spend money…

From: kairos0ne @.> Date: Sunday, 14 May 2023 at 17:36 To: adafruit/circuitpython @.> Cc: kairos0ne @.>, Your activity @.> Subject: Re: [adafruit/circuitpython] document port, chip, and board limitations (Issue #6930) I have tried with the featherS2 and featherS3 by unexpected maker and I’ve also tried the adafruit Rp2040 feather I’ve had no such luck with any of them but the strangest thing is I had it working on 6.x circuit python with the rp2040 but not amnymore on the later versions.

dhalbert commented 1 year ago

Obviously I meant along side the Airlift Featherwing, plz excuse my tone I’m a little frustrated that I bought three boards and two airlifts – my project requires BLE only to find that its not supported for these boards. The Airlift coprocessor is advertised as a BLE solution for any feather based board and if there are three that it in fact doesn’t work with then people should know that before they spend money…

  1. It's true that _bleio supporting AirLift is not turned on for ESP32-S2 boards. I'm not sure if this is an oversight or we did it for space-saving reasons. I have opened a new issue about this: #7977.
  2. _bleio supporting AirLift is turned on for RP2040 boards.

However, note that AirLift BLE support is limited to acting as a BLE peripheral right now. It cannot act as a central, talking to other BLE peripherals. See the details as noted https://learn.adafruit.com/adafruit-airlift-featherwing-esp32-wifi-co-processor-featherwing/circuitpython-ble and https://learn.adafruit.com/welcome-to-circuitpython/frequently-asked-questions#faq-3129409

Currently the AirLift support for CircuitPython only provides BLE peripheral support. BLE central is under development. So you cannot connect to BLE devices like Heart Rate monitors, etc., but you can act as a BLE peripheral yourself.

dhalbert commented 1 year ago

@kairos0ne I am going to close this issue because the original issue was a general one about documentation that has been addressed. Let's continue AirLift BLE support in #7977.

dhalbert commented 1 year ago

Try the RP2040 again -- it should be on (I verified on such a board), and I don't understand why you are not seeing it.

kairos0ne commented 1 year ago

Yeah RP2040 seems to give me a different error, however I think I'm getting the gist of what you wrote and whats been written:

Circuit Python Serial Monitor

Traceback (most recent call last):
  File "main.py", line 55, in <module>
  File "adafruit_airlift/esp32.py", line 199, in start_bluetooth
_bleio.BluetoothError: Timeout waiting to write HCI request
dhalbert commented 1 year ago

For the RP2040, this sounds like a support problem. Could you open a thread in https://forums.adafruit.com/viewforum.php?f=60 and ping me here with the link when you've done so? Include the simplest program that causes the error -- it sounds like either the firmware on the AirLift is out of date or there is a wiring problem or a pin setup problem.

Also in the support thread we can discuss the Espressif issue: it turns out getting AirLift _bleio working on Espressif is not so easy. The reasons are not due to the fundamental code but instead are due to some build infrastructure issues.

karavelioglu commented 5 months ago

Hey folks,. I am getting a _bleio problem on HUZZA32 Feather board. Is there a workaround?

https://forums.adafruit.com/viewtopic.php?p=1011498#p1011498