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, I²C, 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

Thanks a lot afoken, I really value your feedback.

It'll be hard for me to gauge what is good/bad, needed/not-needed, desired/hated before I start writing, so I think that's where I'm going to start.

Put together a first draft of one of the single technical 'page' (on Github), then perhaps post it here to see if I can get it reviewed. Considering it is Perl, everyone here will have some relevancy to it, and those who want to review (just like this request for feedback) can do so.

Since I started the project, I have learned some monk names who are highly technical in several areas in electronics and communications etc, and some that are not. That's ok... I'm hoping to create a balance between everyone. I don't want it to be too advanced, but at the same time, not so basic that it means nothing. Essentially, I don't really know who my target audience is yet ;)

I'm looking forward to getting the first piece together for review, as that will lead into the design of the overall project. I like the differing opinions here, and very thankful for all of the feedback so far even before starting.

One thing that I've rarely seen in the Raspi or Arduino context is the 4-20 mA interface, a.k.a. current loop. In its pure analogue variant, it's a quite clever and simple interface suitable for both sensors and actuators. The idea is to use current, not voltage, to carry the signal. 4 mA represents 0%, 20 mA represents 100%. Everything in between is linear, e.g. 12 mA = 50 %.

Some advantages:

• The offset of 4 mA can be used to supply the sensor or actuator with energy. Many actuators actually have a separate supply voltage, because 4 mA at about 20 V is not that much energy, so it's a little bit hard to move things. Many sensors can work fine from 4 mA and don't need a separate supply.
• A broken sensor or actuator line can easily be detected: The current drops below 4 mA, typically to 0 mA.
• A short circuit in the sensor or actuator line can be detected: The current rises above 20 mA. The limiter (see disadvantages) will prevent excessive current, so nothing will start burning.
• A simple shunt resistor between GND and sensor is all you need to read the sensor value into the controller (ADC input). Most times, you add an op-amp and use a lower resistor value. Also, you need some clamping (a diode pair from signal input to Vcc and GND) to avoid magic smoke escaping from the controller or the op-amp. Trust me, I know from experience that modern microcontrollers don't like 24V at their input pins. Some op-amps can handle input signals larger than their supply voltage, so the clamping may be omitted for them, but most op-amps don't like that at all.
• Resistance of the sensor / actuator line is not an issue, because the sensor or the current source for the actuator will drive a constant current through the line. Voltage drop is irrelevant as long as the supply voltage is high enough. The industry standard supply voltage is 24 V, sufficient for insanely long lines. If line resistance becomes an issue, you can simply increase the supply voltage. (In other words: with short lines, you could get away with less supply voltage.) So usually, simple phone wire is used for current loops.
• Noise coupled into the line is not an issue. It will cancel out, because the line is essentially symmetrical. And if it doesn't, the sensor or current source will work against the noise.
• Electromagnetic compatibility is usually not an issue, because you rarely have high frequency signals on the line. All is purely analogue, so you usually don't have sharp edges on the signal. Unless something changes, the signal is DC.
• A simple multimeter capable of measuring voltages up to 100 V and current up to 100 mA is sufficient for debugging. Special devices are available to drive constant current into an actuator or to control the current into a controller (replacing the sensor). A scope may occassionally be helpful if you need to see the exact signal waveform.
• A simple potentiometer can be used during development to simulate a sensor. Add a mA meter in line and you can fake sensor data as required.

Some disadvantages:

• Sensors are typically not referenced to GND, because the current measuring shunt is connected between sensor and GND. If one end of the sensor is tied to GND, the current has to be measured at the high side, requiring more hardware between shunt and controller. The same is true for actuators.
• Supply voltage is typically 24 V, rarely found in the context of Raspi and Arduino.
• You want a current limiting circuit in series with the sensor / actuator to prevent damages due to short circuit of the terminals. Ohm's law is helpful here, a simple resistor at the high side can be sufficient, adjusted for a max. current of about 25 to 100 mA. An active solution may perform better, typically need two or three transistors and a few passives.
• You need an adjustable current source to drive an actuator. Typically, you use a special IC for the job, but you could also get away with an op-amp circuit. Both would be controlled by a voltage (DAC) output from the controller.
• You need one pair of wires per sensor, one pair of wires per actuator. No multiplexing.
• 4-20 mA sensors are not really cheap. They are clearly designed for industrial use, where reliability is more an issue than cost.

Update 2017-07-19: Hackaday has a nice posting about 4-20 mA current loops.

Alexander

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