CircuitPython Quick Start Unification

[kattni]

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

For CircuitPython Expectations, see issue #583

QUICK START PAGES:

• CircuitPython Built-Ins

• CircuitPython Digital In & Out

• CircuitPython Analog In

• CircuitPython Analog Out

• CircuitPython Internal Dotstar (NeoPixel)

• CircuitPython Cap Touch

• CircuitPython I2C Scan

• CircuitPython I2C Sensor

• CircuitPython UART Serial

• CircuitPython NeoPixel

• CircuitPython DotStar

• CircuitPython PWM

• CircuitPython HID Keyboard

• CircuitPython CPU Temp

• CircuitPython SPI & SD Card

• CircuitPython Storage

[ladyada]

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]

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]

ok go for it!

[kattni]

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]

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]

So a side2 list including every board?

[ladyada]

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

[kattni]

Yah that's what I meant :)

On it!

[kattni]

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

[ladyada]

D2 on itsybitsy is labeled '2' yeah

[kattni]

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

[ladyada]

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]

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]

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]

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]

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]

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]

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

[ladyada]

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]

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]

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]

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]

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]

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]

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]

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]

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

[kattni]

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]

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]

Added intro page.

[ladyada]

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]

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]

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]

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]

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]

OK pick one and go for it!

[kattni]

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]

I'll get started on Analog In.

[kattni]

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

[kattni]

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]

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]

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]

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]

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

Continuing on Internal RGB LED now.

[kattni]

Internal RGB LED is ready to be looked at!

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

[kattni]

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.

• NeoPixel/Dotstar will each have one diagram per, different board each.
• UART will use Flora v. of GPS for CPX/Gemma, breakout for the other boards, with wiring diagrams for every board.
• I2C Scan/Sensor will be combined, and both will use the TSL2561, with Flora v. for CPX/Gemma, breakout for the other boards, wiring diagrams for every board.
• HID Keyboard will have one wiring diagram.
• CPU Temp remains the same, REPL screenshot.
• Storage will be same, temperature logging to local flash. Possibly reference to SD card guide.

And that's where we're at!

[kattni]

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

[kattni]

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]

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