Beefy Boxes and Bandwidth Generously Provided by pair Networks
No such thing as a small change
 
PerlMonks  

Contemplating a documentation series for my Raspberry Pi work

by stevieb (Canon)
on Jul 03, 2017 at 17:53 UTC ( #1194097=perlmeditation: print w/replies, xml ) Need Help??

So, after over a year of learning, development, implementation and testing, I am very near the point where my Raspberry Pi Perl software is ready for prime-time use by the masses. After a few more tweaks, test additions, documentation updates and one last once-over, I plan on writing a "Howto Pi with Perl" type tutorial, across several articles in a series.

Trying to put together some sort of sane format, I'm looking to those who have publishing experience or technical writers to give my initial thoughts a once-over and provide me any feedback. Most, if not all portions will include breadboard diagrams of each task, code (of course), pictures if reasonable and in some cases potentially even video clips.

Initial, broad-view structure:

  • very brief intro to the Pi, its capabilities, and overview of the features/limitations of the software
  • a synopsis of what will be being taught, formats/conventions that will be used
  • basic intro on creating and using a Pi object
  • intro to the most basic part of the Pi, the GPIO
  • examples of creating and using a GPIO pin at the most basic level (INPUT, OUTPUT, HIGH and LOW etc)
  • intro and examples using advanced pin features (interrupts, PWM, pull up/down etc)
  • workshop: using simple pin-based sensors and devices (LEDs, hygrometers, thermo-resistors, distance sensors etc)
  • detailed overview of the communication mechanisms included (I2C, Serial, SPI etc)
  • workshop: detailed overview of using the comms, starting very basic, leading into writing your own device/sensor modules using the software
  • workshop: using an LCD and/or OLED screen to display things on it
  • workshop: intro to and using Analog to Digital converters
  • workshop: intro to and using Digital to Analog converters
  • workshop: intro to and using Digital Potentiometers
  • workshop: intro to and using shift registers (basic through to advanced usage)
  • workshop: using a GPS module
  • workshop: advanced uses: utilizing several ICs and sensors in much larger and more involved projects (probably put together a few of these)
  • workshop: connecting to and using features of an Arduino with the Pi (over varying communication methods, including example Arduino sketches)
  • how this software came about, and some basic information on the underlying parts that allow it to work
  • extensive article on how I ensure the code is fully tested after each commit on a custom hardware test platform
  • possibly some details/photos on some of my real life projects I use at home (my indoor grow room automation system for example)
  • possibly a demo example of writing a web UI with jQuery to automate and provide a GUI of a basic project

update: I think I'm going to use this as my initial template, so I may periodically update it with feedback and new ideas.../update

For each element that contains a specific topic, include, where feasible/available a section at the bottom of the doc for advanced users perhaps in <small> or equivalent tags (these are just thoughts, nothing firm):

  • link to datasheet
  • list of issues or possible enhancements
  • link to relevant section in the Pi datasheet
  • link to the specific module that houses the code
  • link to a C/C++ example
  • link to Python equivalent

Any thoughts on this general first thoughts layout? Anything that I should include that's not already? Anything I should remove? How about any thoughts on the individual elements and the manner in which to present them?

I think I will create the actual demonstration parts first, then weave in the commentary thereafter. At first thought, this seems like the simplest approach that'll allow me to review all of the actual working parts as I go back through and edit in commentary.

Thanks,

-stevieb

Replies are listed 'Best First'.
Re: Contemplating a documentation series for my Raspberry Pi work
by zentara (Archbishop) on Jul 03, 2017 at 18:20 UTC
    Sounds great! You have been a big help in getting my Pi running with perl. It is so disappointing to see all Pi examples written in python. :-)


    I'm not really a human, but I play one on earth. ..... an animated JAPH

      Thanks zentara.

      The very first thing I did with my Pi was attempt to figure out how I'd use it with Perl. I have ever only done one piece of Python on any of my Pi's, and that was only about a week ago.

      I do a lot of prototyping in C/C++, then make that code available with Perl.

      Currently, I ship a Tutorial/FAQ with the base distribution (the dist that encompasses all other individual dists). It's not fully complete, and there is information missing where it directs you to the sub-module documentation. It's a start though.

      The new series I am going to write will encompass things from beginning to end.

        I do a lot of prototyping in C/C++, then make that code available with Perl.

        ...which, of course, is the real, true, and righteous way sage prorammers should develop.

        Thanks, stevieb; you're doing great things.


        If you didn't program your executable by toggling in binary, it wasn't really programming!

Re: Contemplating a documentation series for my Raspberry Pi work
by afoken (Canon) on Jul 03, 2017 at 18:24 UTC

    I would avoid most of the electronics part. There are tons of tutorials, blog entries and so on out there; find a good one and link to it. Then explain how perl can do a better job than that snake stuff.

    Alexander

    --
    Today I will gladly share my knowledge and experience, for there are no sweeter words than "I told you so". ;-)

      Do you mean descriptions of the electronics?

      Take a shift reg for example... I think a very brief "this is what a shiftreg does" and then perhaps linking to a wikipedia article for more info perhaps? I'm hoping to make each element self-contained with a desc, the code, breadboard layouts so that a user can literally copy/paste code and make exact connections, interspersed with brief info-type statements where needed.

      That's kind of what I had in mind at least.

        This makes perfect sense, in my experience this is what people are actually looking for.

        Do you mean descriptions of the electronics?

        Yes. Don't explain LEDs, why LEDs need current limiting resistors, how poteniometers and sensors work, how DACs, ADCs, shift registers, RS232, IC, SPI, ... work, what pull-up and pull-downs do. That has been explained often enough and could be done by simply linking to good resources. Wikipedia might be good a candidate. I hoped to find that basic stuff at https://www.raspberrypi.org/documentation/, but unfortunately, they seem to have omitted that part.

        I'm hoping to make each element self-contained

        Of course, that's quite the opposite of omitting old content. But a really self-contained element would perhaps have to start with basic electronics, explaining voltage, current, resistors, and so on. You need to set a lower limit at what you want to explain. You don't want to start at quantum physics to explain electrons interacting with each other and other matter.

        My idea was to raise that minumum level of knowledge from "minimal electronics" (lamp, switch, battery) to "familiar with microcontroller related hardware and protocols". That avoids a lot of work for you by not having to explain the basic stuff over and over again. And it would avoid a lot of work for the experienced reader by not having to skip over the basic stuff over and over again. Adding a few explaining links to each element for the basics would still allow readers at the "minimal electronics" level to understand what happens.

        self-contained with a desc, the code, breadboard layouts so that a user can literally copy/paste

        Obviously missing here is a circuit diagram. That's much more important than a breadboard layout. Yes, it could be reverse engineered from the breadboard layout. But a (good) circuit diagram is much clearer than a layout.

        And if you raise the knowledge level to "familiar with microcontroller related hardware", you can omit the breadboard layout. It's obvious from the circuit diagram how to connect the hardware. And it allows to see some magic happen, teaching some good lessons. Just copying breadboards does not help to understand electronics. It can be a first step, like training wheels. But at some point, you remove the training wheels.

        What's your intention? You want to explain how to use perl (your modules) on a Raspi. So that should be the primary content, not electronics. Using a nice breadboard example for connecting a LED and a potentiometer is ok. Adding one more example to the existing two million does not hurt. But shortly after that, stop detailing everything.

        There is a limit for the number of components on a breadboard. Yes, you can build an entire 8-bit combuter on breadboards, but that does not mean that you should do that. I would avoid putting more than about 50 pins on a breadboard. Breadboards tend to have loose connections, especially when you move them, and when the contact springs wear out. They add a lot of parasitic capacitance due to the way they are constructed. And of course, you can't use SMD parts without adapters. Perfboards don't have these problems, but of course, reusing them is harder. They tend to loose some pads when unsoldering parts.

        Alexander

        --
        Today I will gladly share my knowledge and experience, for there are no sweeter words than "I told you so". ;-)
Re: Contemplating a documentation series for my Raspberry Pi work
by zentara (Archbishop) on Jul 04, 2017 at 12:33 UTC
    Hi again stevieb. It sounds like you have the start of an O'Reilly book on the PerlPi. :-)

    One thing I noticed was the number of dependencies for installing all the prerequisite modules for installing the RPi-WiringPi module.

    Warning: prerequisite GPSD::Parse 1.01 not found. Warning: prerequisite RPi::ADC::ADS 1.01 not found. Warning: prerequisite RPi::ADC::MCP3008 2.3604 not found. Warning: prerequisite RPi::BMP180 2.3604 not found. Warning: prerequisite RPi::DAC::MCP4922 2.3605 not found. Warning: prerequisite RPi::DHT11 1.03 not found. Warning: prerequisite RPi::DigiPot::MCP4XXXX 2.3604 not found. Warning: prerequisite RPi::I2C 2.3604 not found. Warning: prerequisite RPi::LCD 2.3603 not found. Warning: prerequisite RPi::Pin 2.3603 not found. Warning: prerequisite RPi::SPI 2.3607 not found. Warning: prerequisite RPi::Serial 2.3602 not found. Warning: prerequisite RPi::WiringPi::Constant 1 not found. Warning: prerequisite WiringPi::API 2.3613 not found. Generating a Unix-style Makefile

    Additionally cpan didn't want to install automatically. When I try "cpan install RPi-WiringPi" it returns without finding the module. You need to use "cpan install RPi::WiringPi", and even then a bunch of errors are generated in the cpan tests regarding an unknown error in installing WiringPi::API . It would be nice if you made a Bundle:RPi or something similar.

    I finally read that you need to install WiringPi C lib first, before installing WiringPi::API. Then I also needed to manually install RPi-Pin-2.3603. Other than those glitches, it all installed fine.

    My next project is driving a 64x32 led display. :-)

    I think you ought to look for a publisher.


    I'm not really a human, but I play one on earth. ..... an animated JAPH

      "Additionally cpan didn't want to install automatically. When I try "cpan install RPi-WiringPi" it returns without finding the module.

      Neither cpan nor cpanm will allow you to install modules like this:

      marto@shemp:~$ cpan install RPi-WiringPi Reading '/home/marto/.cpan/Metadata' Database was generated on Tue, 04 Jul 2017 12:53:45 GMT Warning: Cannot install RPi-WiringPi, don't know what it is. Try the command i /RPi-WiringPi/ to find objects with matching identifiers. marto@shemp:~$ cpan install HTML-Template Reading '/home/marto/.cpan/Metadata' Database was generated on Tue, 04 Jul 2017 12:53:45 GMT Warning: Cannot install HTML-Template, don't know what it is. Try the command i /HTML-Template/ to find objects with matching identifiers. marto@shemp:~$ cpanm RPi-WiringPi ! Finding RPi-WiringPi on cpanmetadb failed. ! Finding RPi-WiringPi () on mirror http://www.cpan.org failed. ! Couldn't find module or a distribution RPi-WiringPi marto@shemp:~$ cpanm HTML-Template ! Finding HTML-Template on cpanmetadb failed. ! Finding HTML-Template () on mirror http://www.cpan.org failed. ! Couldn't find module or a distribution HTML-Template

      On a related note, you could vastly reduce the time to install modules by using cpanm over cpan, it's paninful to watch cpan install modules on a Raspberry Pi. Once the dependancy wiringpi is installed cpanm RPi::WiringPi installs everything in a reasonable time for a Modeal A v1 Pi running a bunch of other stuff (apache, openvpn etc).

      Update: parent updated since posting reply: adding "I finally read that you need to install WiringPi C lib first, before installing WiringPi::API. Then I also needed to manually install RPi-Pin-2.3603. Other than those glitches, it all installed fine."

      Hey zentara,

      I'm just finalizing a significant upgrade/enhancements to the "pin registration" system. This is a protection mechanism that 100% ensures that if there's a crash or interrupt of any sort, we roll back the configuration of all pins we know about, and restore their state and functionality back to how we had it before exiting. It also protects someone from registering the same pin twice for different purposes by accident. Yesterday, I added this pin registration functionality to all of the various objects you can create through the $pi object (ie. if you create a shift register or ADC, we'll automatically register those pins). You really don't want to accidentally send a shift reg into bizarre behaviour just because you forgot that you're flipping a pin that's say for example the communication pin for the other device :)

      I think that system will be important especially for users who are new to the platform.

      Once I've got all of the quirks worked out (today), I will focus my attention on the entire installation of everything and smooth out any wrinkles. Thanks for letting me know!

      Also, please do share the code you come up with for the LED matrix display. I honestly have never used one. The farthest I ever got was chaining four shift registers together with eight LEDs per register for when I was testing shiftreg functionality originally. Here's an image with two of them. I never documented it with all four due to it not being necessary, but I had them in a grid and that was fun to work with.

        "I will focus my attention on the entire installation of everything and smooth out any wrinkles. Thanks for letting me know!"

        I'd hang on until you had an actual reproducable problem reported, cpanm RPi::WiringPi works without issue on the lowest spec (oldest model) Pi, running many other things.

      It sounds like you have the start of an O'Reilly book on the PerlPi

      After a couple of days since you posted this, I actually looked quite deeply into this.

      I have a couple of concerns right off the bat. First, I'm moving out onto a self-sustainable property in the imminent couple of months that is going to take up a lot of my time. This is why I have put in such time and effort getting the code close to what I'm happy with. I am not certain until I've been there at least for several months if I could keep deadlines. Second, I don't know if there'd be the audience for it to be financially viable for O'Reilly, or myself. Perl usage is dwindling if one looks at reality seriously, so that, combined with the fact there's going to be far fewer people using a Pi *and* Perl, the potential audience drops significantly.

      The thought alone is an exciting one, but I've always been a practical person, and reality is what I live by. I'd do it if, you know, the document I'm now going to start makes headway and gets positive reviews, and if it would make fiscal sense to myself (to at least cover costs (ie. time)) and some publisher.

      People for years have told me I need to write a book (my poetry/lyrics, a book about my photographic adventures), but it's an interesting concept writing a book based on my own software and technical achievements.

Re: Contemplating a documentation series for my Raspberry Pi work
by morgon (Priest) on Jul 04, 2017 at 20:51 UTC
    Have you thought about writing an article about it e.g. for the MagPi-Magazine?

      I have not. What I'm proposing that I'm going to do is far beyond a single article, but realistically, after I get a 'part' or two done and grasp how the rest of the document will flow and get a first full draft done that is 'publish' worthy, I may reach out to such mags just to say "you know, Python isn't the only Pi game in town" with a basic writeup or something.

      Thanks for the idea though, it didn't cross my mind.

      morgon ++, I think this is an excellent idea.
Re: Contemplating a documentation series for my Raspberry Pi work
by Laurent_R (Canon) on Jul 04, 2017 at 20:10 UTC
    This sounds awsome.

    I have translated into French a few tutorials on the Pi, and of course it was all over Python and Python APIs. I don't necessarily dislike Python, but I clearly prefer Perl and I would be really glad to test the Pi with Perl and also, if permitted, to be able to translate and post such tutorials for Perl on Pi.

    Great work, stevieb.

      Wow, thanks Laurent_R!

      I'll keep posted here on my progress :)

      I use Python at work so I don't have any real issues with it, I just like Perl better, and I've been using it for a heck of a lot longer.

Log In?
Username:
Password:

What's my password?
Create A New User
Domain Nodelet?
Node Status?
node history
Node Type: perlmeditation [id://1194097]
Front-paged by Corion
help
Chatterbox?
and the web crawler heard nothing...

How do I use this? | Other CB clients
Other Users?
Others contemplating the Monastery: (3)
As of 2021-12-07 23:48 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?
    R or B?



    Results (34 votes). Check out past polls.

    Notices?