The README file of the project - included in the package
12 Sep 2017 17:43
The project

Verwandte Themen:
Related topics:

Bechele 2 Software
FAQ - questions
Hardware of Bechele 2
The project - how it works

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.

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
- 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.

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:
Many modules depend on other modules, so that the installation may take a while.

   WiringPi::API (Version 1.05 - for Orange Pi PC the latest version does not 
   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 

Programms and their function:

  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 

  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.

  Here useful program messages will be shown.

  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

  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 

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.

  Shell script that saves the actual configuration as a tar ball in: 

  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.

  De-activates the automatic boot into live.pl 
  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. 

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.