In following you see the readme file contained in the directory /usr/local/bin in the images or in the tar ball.
This is the documentation to project bechele.de
Further infos under www.bechele.de
Author Rolf Jethon
bechele,de is a Raspberry Pi project, that enables you to create movement models
like hand puppets, dance puppets or animal robots with simultaneous output of
audio data and awake it to life, without the need of programming.
Instead of a Raspberry Pi a OrangePi PC can be used - therefore a separate SD
card image exists.
All required project scripts reside in folder /usr/local/bin.
Basics
To move a movement robot syncronized to music or speech, it is required to add
the movement in some way according to the tone. In this project this happens by
moving a joystick by hand synchronous to the sound. At the same time the
movements will be output to the servos to be able to check the results on the
fly. The number of recording channels is limited to a maximum of 16 according
to the project. In case of the puppet Mr. Bechele, the number of Servos in use
is only 4. This limitation is just coincidencial and not a limit for other
projects. One servo for the eye movement up-down, one for eye movement
left -right, one servo for the lid movement and one for the mouth movement.
My new puppet (almost finished) uses 8 channels for example. Because with a
joystick only two channels can be recorded, the recording of all channels need
to be done sequentially. In case of Mr. Bechele I recorded first the mouth
movement according to the speech audio mp3 file. Because mouth movements are
very quick they need full concentration to acieve a more or less accurate
result. Therefore I just recorded one channel only though I had two channels
available. Then I recoreded the eye lid movement with also only one channel.
Finally I recorded the eye movement with two channels at the same time. The
audio data was divided in single short sections, to allow the puppet player to
respond in the speech pauses. After finishing recording, audio data and movement
can be output step by step by pressing a button, so that the audience has the
impression the puppet talks really to the puppet player.
Working principle:
A movement set consists always of a mp3 sound file, and a .svo file that
contains the movement information for the servos. Optionally a text file with
the same name may exist, that contains text hints for the puppet player - in case
you don't want to learn all the dialogs by rote. This text will then be shown on
the terminal window, you started the program from.
In the first version of the project, the positions of the joy stick were passed
directly to the servos. There the value range of the joy stick needed to
coincide exactly with the servo position values. This had the following
disadvantages:
- The whole movement range of the servo needed to be possible for the servo.
- Different servo types could not be combined if the parameters differed.
- After changing mechanical parameters of a servo or joy stick, a mecanical
re-calibration was required.
- Mechanical changes required a re-recording of the concerned movement.
Therefore joy stick movements as well as servo movements will be parametrized
and normalized to a range of 0 to 4096 in file ConfigL.pm. If for example a
mouth movement of a puppy was realized, so that 2/3 of the possible angle range
of the servo was in use and after a mechanical change just the half of the
angle range is needed, existing movement file can be re-used without any change,
by adapting the servo parameters. The same applies if the joy stick changes.
The positions of 0 to 4096 in a movement file contains the complete possible
mechanical movement range of the servo in the model. In other words: The servo
-despite parametrized correctly- does never try to exceed its mechanical
limits in the model.
------------------------------------------------------------------------------
Installation:
The easiest way is to write a pre-defined SD card image to a SD card and you are
almost ready to go. For those who want to install themself, expect a time
consuming installation marathon:
Unpack the tar ball into / (root) of your distribution.
Depending on the linux distribution some software needs to be installed.
How to install that depends on the distribution.
you need:
cpanminus (required)
WiringPi (required for RaspBerry Pi)
git (required for OrangePi)
make (required for OrangePi)
gcc (required for OrangePi)
WiringOP (required for Orange Pi - install with:
git clone https://github.com/zhaolei/WiringOP.git -b h3
after that > cd WiringOP < und anschließend > ./build <)
now > echo '/usr/local/lib' >> /etc/ld.so.conf.d/randomLibs.conf <
and > ldconfig <
test with > gpio readall < all gpios should be displayed
)
alsa-utils (required)
mpg123 (required)
i2c-tools (required)
perl 5 (probably pre-installed - required)
perl-device-serialport (required)
Further you need to install some perl modules - easiest is to use:
cpanminus
Many modules depend on other modules, so that the installation may take a while.
PERL MODULES:
strict
Device::SerialPort
Curses::UI
WiringPi::API (Version 1.05 - for Orange Pi PC the latest version does not
work);
File::Find::Rule
Device::PWMGenerator::PCA9685
Audio::Play::MPG123
Time::HR
ConfigL (This comes along with the tar ball and does not need to be installed)
After the installation, some parameters need to be set - see section
configuration.
------------------------------------------------------------------------------
Programms and their function:
trackui.pl:
This program processes on demand all mp3 files from the directory that has
been passed as parameter during program start. To ease the use a quasi
graphical user interface is in use (curses), that also works over a terminal
program (for example putty).
Depending on complexity of a model or a puppet, movements will be generally
aquired sequentially. Probably nobody may control all servos simultaneously
so a correct movement results.
By using the user interface it's possible to combine movements. For example
several servos may execute the exactly the same movement. The movement
control of a servo group may be assigned to a joy stick axis. This is for
example necessary if a puppet has seperate servos for each eye lid. You don't
want to record each lid seperately but record them togehter because they
almost move together. If for an exception one lid shall be moved different
from the other, you may record one eye lid in a subsequent record cycle by
just defining a limited range, instead of the complete number of movement
steps within a single MP3 file. Depending on the number of servos and the
complexity of your movements, you may repeat recording as often as you like
with servos activated or de-activated as you need until the movement fits to
the sound as desired.
control elements of trackui.pl:
Section File:
Here you define the file (.svo) to process. Usually you will process the
files defined by selecting a folder as a program start parameter.
With << Prev Next >> you may move through the folder. The requirement is alway
a existing MP3 file. For this file a belonging .svo file will be created or
modified. If a .svo file already exists this may be output or modified.
With the double arrows you may move in steps of 10 files. This is helpful if
you want to navigate to a desired file quickly, because solution dependent,
processing single files may be impossible or pedestrian.
Save saves the .svo file finally.
Operation elements on the joy stick:
Key right: starts recording or viewing (trigger).
Key left: stops recording and returns to the menu.
Section Channel X:
Here you may activate the servos, that shall be recorded during the cycle by
moving the joy stick X-direction. This is almost only one servo, but several
may be selected. These will then be moved and recorded simultaneously.
Section Channel Y:
Like Channel X, but here the Y-direction of the joy stick will be used for
controlling.
Track Sets:
A track contains all movement steps that corrospond to a mp3's play duration.
In the default setting, movements will be recorded every 50 ms. A 20 second
MP3 results then in 400 movement way points.
Start at set: Is the start time of a record in steps of 50 ms.
Stop at set: Is the stop time in 50 ms steps.
The Check box Update activated controls that after the very first record in
a new MP3 the time points will be automatically determied and updated.
The Check box Full range allows independent of the fileld values to record or
view the complete movement duration.
Status:
Here useful program messages will be shown.
Process:
Record starts a recording according to the servo activation. Not activated
servos will be played only. All servos de-activated is the same like 'view'
View outputs a MP3 and movements only.
The program exits with Ctrl-Q
live.pl
This program outputs during the presentation the sound along with the
recorded movements. The sorting of the files follows the ASCII sequence.
The program will be only controlled using the four buttons of the control
button. The joy stick is not needed and normally disconnected.
Button 1 :
Start of the first sequence or switching to the next sequence.
Button 2 :
Start of the previous sequence
Button 3:
Repeats of the previous sequence with output of the repeat prefix sequence
from folder "repeat" of the output directory. If more than one sequence
resides there the following sequence (mp3 file) will be uses as a prefix.
The idea is to have a possibility to repeat a sequence if it was for example
too loud in the audience to understand.
Button 4 :
Outputs the next sequence in folder "extra" of the output directory.
If several sequences are stored there, with each repeat the following sequence
will be output. Folder extra may be just a laugh or a reaction sequence to the
audience.
servokalib.pl (2-channel) and servocalib-single (1-channel)
This program is used for a first test of new servos and to deteermine the
servo and joy stick parameters. It is more or less self explaining. Here you
need to have the joy stick connected.
Operation elements on the joy stick:
Key right: switches the joy stick to the next servo.
Key left: switches the joy stick to the previous servo.
X-pos(0-4096) |Y-Pos(0-4096) |Joystick X |Joystick Y |Servo 0 |Servo 1
-----------------------------------------------------------------------------
2714 | 1602 | 460 | 317 | 438 | 307
In file Modules/ConfigL you need to enter the limits - see the hints in the
file itself.
backup
Shell script that saves the actual configuration as a tar ball in:
/usr/local/backup
activate_autostart
running this once under Archlinux, the program live.pl will be started
automatically after booting. This is helpful if no terminal is connected to
the raspi.
runs only on distributions that support systemctl.
deactivate_atostart
De-activates the automatic boot into live.pl
cksum
helper file that checks the file integrity of .svo files.
Record tips:
Create your audio files with a longer silence at the end. So the puppie may
continue to move while the puppie player responds. When the button for the
next sequence will be pressed, the current will be stopped immediately and
the subsequent one starts. Better record the model movements a bit longer, so
the puppet does not look "static" in speech pauses.
------------------------------------------------------------------------------
Configuration:
After installation parameters perhaps need to be modified, before you may start
with playing or recording.
Setting up program parameters:
Serialport ($serialport) - According to the hardware in use.
i2c port ($i2cport) - According to the hardware in use.
i2c Adresse ($i2c_address) - According to the address in use. (tip: detect with
i2cdetect )
Setting up the number of servos in use:
Edit file: /usr/local/bin/Modules/ConfigL.pm
Change the entry:
$num_servos=4; # number of servos in use (max 16)
Of course you need these Servos attached.
Setting up the joy stick.
Assume a joy stick delivers at minimum position a value of 123 and 855 at
maximum. By entering these values into ConfigL.pm, these values will be
converted internally into 0 to 4096. If you move the stick to minimum a inner
value of 0 will be used and if the stick goes to maximum a inner value of 4096.
Adapt in ConfigL values:
$joystick_x_start $joystick_y_start $joystick_x_end $joystick_y_end
Setting up a servo:
With servos we have the following parameter sets:
1. The whole possibe movement range of a servo (not mounted in the model).
This is used to parametrize the servo type so when running servocalib.pl,
the servo is already preset and reacts accordingly.
(servolimit start + servolinit end)
2. The possible movement range within the model.
This is used to limit the servo movement inside the model in its mechanical
limits, so the servo does not try to overrun the mechanics.
(servostart + servoend)
3. The movement direction. (1 or 0).
O outputs the movement like the joy stick.
1 inverts the movement opposite to the joy stick
3. Servolabel: Here you may enter a text that later names the servo in trackui.pl
Tips for setting up:
- In any case prevent the servo from trying to exceeds its mechanical limits.
Especially cheap servos like SG90 don't appreciate that and burn trough.
- First set up the joy stick using servocalib (without connecting servos) and
then set up ConfigL.pm. Check in a second run, if you reach 0-4096.
- Only then connect !one! servo, put the stick to the middle, determine the
limits and enter them into ConfigL.pm.