search

adafruit / circuitpython

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

CircuitPython Quick Start Unification #635

Closed kattni closed 6 years ago

kattni commented 6 years ago

Unify the CircuitPython quick starts for mirroring across all the board guides!

For CircuitPython Expectations, see issue #583

QUICK START PAGES:

ladyada commented 6 years ago

ok lets look at https://learn.adafruit.com/adafruit-trinket-m0-circuitpython-arduino/circuitpython-built-ins first do we want to move the bottom section "Things to watch out for!" to 'Expectations'? maybe just point people to the Expectations page. otherwise this is kinda generic already?

kattni commented 6 years ago

I was thinking on this one. It is generic already, yes. I put it on the page because there's a couple of changes I think we need to make. I agree the "Things to watch out for" needs to be moved to The Expectations Expansion (I'll add to that issue when I'm done with this comment). I also think the "Handy Tips" page needs to be split between Built-Ins and Expectations (already updated that issue to reflect this).

Otherwise, it may be worth cleaning it up a little if we're going to be mirroring it everywhere.

ladyada commented 6 years ago

ok go for it!

kattni commented 6 years ago

Ok I split Handy Tips up, unmirrored and deleted that page. I quick updated Built-Ins. I think if we decide to add much more to it, we'll want to do some clearer delineation, but it looks great for now! The Expectations page and issue have been updated with the info removed from Built-Ins. I think Built-Ins is done for now!

ladyada commented 6 years ago

okidoke lets move to digital IO https://learn.adafruit.com/adafruit-trinket-m0-circuitpython-arduino/circuitpython-digital-in-out i think i picked the pin #'s because they exist on all devices (other than cpx) so what we need to do is add a side2 element with a photo or fritzing showing where the digital #13 LED and pin #2 are)

kattni commented 6 years ago

So a side2 list including every board?

ladyada commented 6 years ago

i think better to have one side2 per board (but on top of each other, one by one)

kattni commented 6 years ago

Yah that's what I meant :)

On it!

kattni commented 6 years ago

Is D2 on the ItsyBitsy the 2 in the corner or is it the alternate of A2?

ladyada commented 6 years ago

D2 on itsybitsy is labeled '2' yeah

kattni commented 6 years ago

Ok, done! Let me know if you want anything changed, and if not, what's next!

ladyada commented 6 years ago

ok looked! A2 != D2 (gemma m0 is a weird one) - so for Feather & CPX we'll need to do something else - maybe add another example or commented out line for D7 on CPX and D5 on Feather?

kattni commented 6 years ago

Hmm I looked through pinouts to verify those. Oops. I like the commented out line option. Or do D7 on both? Is there an issue with D7 on the Feather?

ladyada commented 6 years ago

hmm not sure what pinout that is, you can see equivalent pins here https://github.com/adafruit/circuitpython/blob/master/ports/atmel-samd/boards/feather_m0_express/pins.c e.g. no "D2" appears

D7 is great on the CPX because its the switch, so very easy to test. D7 isnt exposed on feather m0

kattni commented 6 years ago

I used the pinouts on the guides. So it's my mistake I'm sure.

Ok keen. I'll do up images for those and submit a PR for the code.

kattni commented 6 years ago

Ok, I've posted the 5 boards that are in Fritizing, and I left the image with the boxes around the correct pins for ItsyBitsy for now, until we have Fritizing for it. Let me know if they look alright to you!

I reworded the info at the top to be more general, however I still need to finish updating the code. I think we should create a new folder in the Learn repo called "CircuitPython_Quick_Starts" and have the code live there, since it's not specific to Gemma (or whichever) anymore. Next, I'll get that taken care of, get the DigitalIO code moved there, get it merged, and get it updated in the guide.

kattni commented 6 years ago

Ok, repo folder is created, all relevant code has been copied over and renamed to CircuitPython_** where ** is the concept we're covering - this can obviously be something different if you want. I have updated code for DigitalIO. I'm waiting until we've discussed things and finalised the images, etc, before I try to update the explanation content in the guide.

I had an idea, regarding the code for the DigitalIO example specific to CPX. If we use D7, we either call it button and we add, commented out, the pin line and the setup line to do a Pull.UP, or we call it switch and add, commented out, three setup lines separately for the switch and a different if statement.

D5 is button B on the CPX - if we use it, we can include 1 commented out line for both Feather M0 Express and CPX, and require no other changes to the code. It's as easy to test as the switch for the purposes of the code.

Let me know what you think.

kattni commented 6 years ago

Phil B did up the ItsyBitsy fritzing for me so that's done and added to the guide. Thanks Phil!

ladyada commented 6 years ago

I think we should create a new folder in the Learn repo called "CircuitPython_Quick_Starts" and have the code live there, since it's not specific to Gemma (or whichever) anymore. Next, I'll get that taken care of, get the DigitalIO code moved there, get it merged, and get it updated in the guide.

ok please do that!

I had an idea, regarding the code for the DigitalIO example specific to CPX. If we use D7, we either call it button and we add, commented out, the pin line and the setup line to do a Pull.UP, or we call it switch and add, commented out, three setup lines separately for the switch and a different if statement.

i think know what you mean but i'd prefer commented/uncommented lines rather than having 'cleverness' with the naming/logic. lets call the pin object 'switch' since a pushbutton is a kind of switch, and have a different line for D2, D5 and D7 :) id rather not use the push button on the CPX since its opposite polarity

please let me know when to take another look!

kattni commented 6 years ago

I noticed that with the button.

Ok I updated the code, updated the text to explain the code. Let me know if it's all accurate. It tests successfully, but there's the two extra lines for CPX because, as far as I could tell, the switch is a Pull.UP so I added the extra line for that. The text below the code explains how to use the commented out lines, but they're commented solidly in the code as well.

Also I added all the new products to it, including a few related products :). Let me know if I missed anything there.

ladyada commented 6 years ago

hi here's feedback!

1) there should be pull UPs on all the switches, they all connect to ground when pressed. please update the code and check

2) don't refer to line numbers in the text, refer to the actual text, because line numbers may vary if we change a pylint note

3) where did you add 'all the new products'? please provide the link you're referring to :)

kattni commented 6 years ago
  1. Ok. Code is updated. Tested successfully on ItsyBitsy!
  2. Updated to refer to text, and cover the potential for someone to start with CPX and work backwards to Feather, etc.
  3. I added them to the right side but it only shows the first 5 - I hadn't backed out of the "Manage Featured Products" page when I posted earlier - maybe it doesn't update until you back out of that page? Aaaaand I'm realising that it added them to the entire Gemma guide, which wasn't intentional. I was thinking specific to the page. Let me know if I should return it to its previous state.
ladyada commented 6 years ago

ok 1 & 2 are now good 3) yeah you can only add products per guide not per page. so each guide should just have that board it references

time to mirror into the rest of the guides (itsy doesnt exist rn) - so please do that so each board mentioned has this page :)

kattni commented 6 years ago

I removed the products from the Gemma guide, it's back to where it started.

What's the plan for CPX? Nearly that entire section was written specific to CPX which makes sense, it's a special case. Am I removing what's there and replacing it with mirrors? Or does CPX remain as-is?

ladyada commented 6 years ago

lets keep CPX with the custom one for now, do you want to add these to the intro-to-circuitpy guide or make another guide where these pages can have a home?

kattni commented 6 years ago

I opened this one up to discussion because I could see the merit of both options. The conclusion is separate guide, and we can link to it from the Welcome guide. The Welcome guide is already pretty big and should focus on getting started and troubleshooting. This would be the next-step guide. :)

So I'll create a new one and get the initial stuff moved over, and get it mirrored to all the boards from the new guide!

ladyada commented 6 years ago

ok make a backup before moving the page. i lost a page when i tried moving it once :/

kattni commented 6 years ago

I didn't know you could literally move a page. I copy and paste all the elements individually. It works out because it gives me a chance to proof everything anyway.

kattni commented 6 years ago

Ok first page published and guide is in moderation. I don't have an intro page for it yet. I'll add the other pages as we go. I figured get it up so I can mirror the pages into the other guides as we go. Unless you want to have this guide completely finished before publishing it?

kattni commented 6 years ago

Added intro page.

ladyada commented 6 years ago

diggin' it! can you mirror from an unpublished guide? if so, lets keep this hidden until we get at least the first 5 elements done

kattni commented 6 years ago

I can! Are you happy with the intro "The Next Step" page? If so I can use that as the main page for the section inside the guides, and nest the rest of the pages under that instead of "CircuitPython Playground".

kattni commented 6 years ago

Also for Trinket, it's obvious to delete the mirrored page, but for Gemma, do you want me to delete the original once we have it in place? I reverted it to draft for now so there's not a duplicate publicly for now.

ladyada commented 6 years ago

yep first page of the guide is good! mirror awayyyyy gemma, delete original, have only this guide's pages mirrored. for the next pages, you can just work in the playground guide, then mirror out - easier that way :)

kattni commented 6 years ago

Ok, I mirrored The Next Step in, and for Gemma and Trinket, I put all the current pages under that one, so as we go, all we need to do is delete the current ones and mirror in the new ones.

I'm having someone check to verify that the mirrors worked. (It's weird how it worked, so even though it did the first time, I'm still having someone check.)

Excellent, that was the plan! And since we're working off of live guides, I'll leave everything in place until we're mirroring the replacement in.

I think we're ready for the next one!

ladyada commented 6 years ago

OK pick one and go for it!

kattni commented 6 years ago

Do you want a single "Internal RGB LED" page with code commented out for both or do you want two separate pages for the internal LEDs, DotStar and NeoPixel, and then mirror into only the applicable guides? (Still planning on separate DotStar and NeoPixel pages as it is right now for external.)

Which capacitive touch breakout should I use for the Cap Touch page? https://www.adafruit.com/product/1374, https://www.adafruit.com/product/1982 or other?

I'll have more questions, but those are what I can think of now!

kattni commented 6 years ago

I'll get started on Analog In.

kattni commented 6 years ago

Re: AnalogIn. Still having some issues with the code. I'll get back to it tomorrow.

kattni commented 6 years ago

AnalogIn should be ready to go.

I'm doing AnalogOut next. I did up code for an LED at different brightness levels with a dac_value(volts) helper. Does this work for you? And if so, do fritizing diagrams for all the boards?

kattni commented 6 years ago

AnalogIn is set! I'll get it into the other guides.

We sorted all the questions above: yes to "Internal RGB LED", everything has cap touch built in, and analogout will use the REPL and a scope or Saleae if someone has those options.

We also sorted basic details for: PWM, servo, UART, I2C, NeoPixel/Dotstar, CPU temp, DHT, HIDKeyboard, Audio Out.

AnalogOut is next!

kattni commented 6 years ago

AnalogOut is all set and mirrored across the rest of the guides!

As discussed, I'll be doing PWM next with a simple example using D13, and include the two piezo examples. I have code working for the D13 LED. I'll write up that section first. Then I'll look at the piezo code and add to it to get it working across all the boards.

kattni commented 6 years ago

PWM content is written and code is uploaded and embedded. Verified that you want hw diagrams of the piezo example. Diagrams created - need to make images big enough for 4x3 cropping and then do up the side2 elements.

Started on cap touch. A0 works on five out of six boards, but it's disabled on CPX. I plan to do up the code to use A0 since it works on the rest of the boards, and include a warning that it doesn't work on the CPX. I'll do up one of the boards attached to a banana. Then at the bottom of the page I can do a side2 with the same images with arrows pointing out A0 (except CPX) and include the list of cap touch pins on each board, and explain CPX.

kattni commented 6 years ago

PWM and Cap Touch are both ready to be looked at!

Continuing on Internal RGB LED now.

kattni commented 6 years ago

Internal RGB LED is ready to be looked at!

Next up in some order is Servo, NeoPixel, DotStar, CPU Temp. And the rest :)

kattni commented 6 years ago

PWM, Servo, Cap Touch and RGB LED are all finalised and mirrored into the board guides!

Currently working on NeoPixel and DotStar, and starting UART and I2C. Left are HID Keyboard, CPU Temp and Storage.

And that's where we're at!

kattni commented 6 years ago

NeoPixel/Dotstar are finished and mirrored. UART and CPU temp are waiting final approval.

kattni commented 6 years ago

UART, I2C, CPU temp are all mirrored in.

Storage is finished, waiting on final approval.

HID Mouse and Keyboard are finished and waiting on first revision.

That's it!

kattni commented 6 years ago

Everything is set and the guide is live! https://learn.adafruit.com/circuitpython-essentials