Many embedded projects require streams of accurate, short-duration
pulses. I'm not talking about PWM here, but about various
communications protocols, such as X10, TV IR remote-control, and G35
RGB LED lights. In particular, the G35 protocol uses a series of
10 usec pulses to send light-control information through the power
cord; you can find an excellent explanation of this protocol here
But interpreters, such as eLua, are often too slow to generate the
needed pulse stream for such protocols. These tools can support
SPI and PWM, where the precise pulse generation is off-loaded to
on-chip subsystems, but non-supported protocols, such as G35, are
usually out of reach without mods to the code underlying the
Mod that code
So, I modified the pio.c code in the eLua source tree to add a new GPIO
functionality. Just for grins, here is a screen-shot from my
oscilloscope showing part of a G35 pulse stream:
Using eLua to generate arbitrary 10-microsecond pulse streams.
If you need a reference, you can find a description of the current (as
in eLua version 0.9) GPIO functionality here
My modification adds a new class of GPIO functions, of the form pio.pulse.xxx()
. This consists
of the following four functions:
or clears, a pulse stream so you can add new pulse information.
pio.pulse.add(chnl, value, nbits)
takes the number of bits specfied by nbits from the given value and
adds them to the selected channel.
pio.pulse.start(chnl, pinid, nusecs)
starts sending the pulse stream in the selected channel to the GPIO pin
defined by pinid; each pulse in the stream will be nusecs microseconds
the state of the pulse stream and returns true if that stream has been
completely sent, else it returns false.
These functions use an array of bits, called a channel, to hold the
pulse information. A 1-bit in the array means that the associated
output pin will go high, while a 0-bit means the pin will go low.
The amount of time the pin stays in that state is defined by the nusecs
value in the call to pio.pulse.start()
call to pio.pulse.start()
also defines the GPIO pin used for the pulse stream.
As implemented, my version of eLua supports up to four pulse channels,
with each channel carrying up to 160 bits in the pulse stream.
There is nothing magical about these values. They are set with
#defines in the pio.c source file and can be adjusted to provide
Using the new features
The first step for using the new pulse functions is to choose a GPIO
pin for the output and configure that pin. For example, you could
use pin PD11 on an STM32F4 Discovery board (S4D), and you would set up
that pin with:
1 -- channel for
G35_PIN = pio.PD_11
You define a pulse stream by first selecting a channel and reseting
it. For example, to start a pulse stream on channel 1 (since this
is eLua, channels are numbered from 1 to 4), you would use:
Now you can begin adding pulse information to the stream. For
example, you would add the G35 start bit with this call:
1) -- always begin with start bit
This uses a value of 1 (2nd argument) and adds the low one bit (3rd
argument) to channel G35 (1st argument). Note that bits are
always added at the low end of the channel; any existing bits in the
channel are always moved toward the high end to make room for the
addition. Perhaps an example will clarify this.
Assume an existing pulse stream of 0011010
want to add the bits 110
to the stream, you would
use a function call of:
pio.pulse.add(G35, 6, 3)
which adds the low three bits of the value 6 to the stream. Your
stream would then contain 0011010 110
(space added for formatting). Note that your pulse stream has
gone from seven bits to ten bits in length.
You can continue using the pio.pulse.add()
function to push new information into the pulse stream. Note that
calling this function only adds information to the stream; it does not
actually trigger the sending of the pulse stream.
After you have loaded all of the information you want into the pulse
stream, you use a call to pio.pulse.start()
to begin the actual transfer of the pulse stream to the output
pin. This function lets you select the channel to send, the GPIO
pin to use for output, and the duration of each pulse, in microseconds.
Note that generating the pulse stream (pio.pulse.add()
completely separate from sending the pulse stream (pio.pulse.start()
comes in very handy in debugging. For example, you can route your
pulse stream to an LED, and even lengthen the pulse duration into
seconds, so you can visually check your data. This concept also
allows you to route a pulse stream to any of several different I/O
pins, should your design require it.
The function pio.pulse.isdone()
can be used to test if the pulse stream has finished
transmission. I included this function for future use, when the
pulse code uses an ISR for pulse generation. Right now, the code
that sends the pulse stream blocks until the entire stream has been
sent, so there is no need for this check function. I hope that
future versions of this code will be updated to use a timer ISR.
Enough discussion, already
Here is an eLua program that sets up a string of G35 LED lights and
changes the color of all lights every three seconds:
-- G35 controller
1 -- pulse channel for G35 comms
G35_PIN = pio.PD_11
function g35_AddBits(val, num)
for n = 1, num do
(bit.isclear(val, num-n)) then
pio.pulse.add(G35, 3, 3) -- add 011
pio.pulse.add(G35, 1, 3) -- add 001
1) -- always begin with start bit
pio.pulse.start(G35, G35_PIN, 8)
function g35_Update(addr, bright, red, green, blue)
for n = 1, bulbs do
g35_Update(n, 10, 10, 10, 10)
red = 15
green = 15
blue = 15
while (term.getchar(term.NOWAIT) == -1) do
for n = 1, 50 do
g35_Update(n, 255, red, green, blue)
red = (red + 2) % 16
green = (green + 3) % 16
blue = (blue + 4) % 16
You need to make a few simple connections to use this code for
controlling a string of G35 LED lights. You first need a 5 VDC
wall-wart rated at 2 amps or more, for powering your LED light
string. DO NOT
power your light string from the S4D board!
Connect together the negative wire from the power supply, a wire to a
GND terminal on your S4D board, and the negative lead on the G35 light
string. You can find info on the G35 cable in the link at the top
of this page.
Connect together the positive wire from the power supply and the
positive lead on the G35 light string. You can optionally wire an
on-off switch in this connection, should you want to switch the lights
on and off independently of the S4D board.
Finally, connect the pin labeled PD11 on the S4D board to the data wire
(center wire) on the G35 light string.
Details on use
When you first power-up the light string, it will remain
dark. You will need to run the above program so the code can
enumerate all of the bulbs in the string. At that point, the code
can begin altering each of the bulbs by sending data down the G35
cable. You can find more details on how the bulbs behave on
power-up through the link at the top of this page.
I developed and ran the above program on an STMicro S4D running at 168
MHz. Note that eLua does not officially support this board yet
(as of eLua 0.9). I was working from a "master" branch where the
eLua developers are building up what (I hope) will become the official
Note, however, that my mods are done to the pio.c source file, which is
universal to all of the eLua targets. This essentially means that
all eLua targets, from the mbed to the supported Atmel devices, could
now use my pulse functions.
If you check the call to pio.pulse.start()
above, you will notice that I'm using a time value (3rd argument) of
eight, rather than the nominal 10 usecs. This is because there is
a two-usecs overhead in the S4D timer functions used to generate the
pulses. This means that the shortest pulse I can generate with
this code is three usecs. It also means that anytime you start a
pulse stream, you must subtract two from the desired pulse width to
allow for this overhead.
Note that this timer overhead is target-dependent. For example,
the mbed timer functions generate three usecs of overhead delay, so the
above function call on an mbed would use a timer value of seven, not
eight. If you rebuild my code for a different target, you will
need to use an oscilloscope or similar device to measure the actual
delay versus the requested delay and adjust your function calls
There are two ways to gain access to these pulse functions. The
first is to add my modified pio.c source file below to an existing 0.9
eLua source tree and rebuild for your target. The second is to
use a binary image already created with my pulse functions added.
If you want to play with these pulse functions and you have an S4D
board handy, you can install this binary image
If you want to rebuild eLua and include my pulse functions, replace the
existing pio.c file with this file
and rebuild for
I really hope that these pulse functions make their way into the next
official eLua release. Being able to generate high-precision,
arbitray streams of pulses from an interpreter, such as eLua,
dramatically simplifies code generation. And did I mention it's a
total hoot? :-)