Skip to content
Permalink
master
Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

mr_keyboard/USAGE_GENERAL.md

Go to file
 
 
Cannot retrieve contributors at this time
General usage of the program First time setup / Installation Download and folder name Python modules Required Midi (optional) Usergroup Configure the local NTP server Settings Usage Setup (Part 1: Hardware) Setup (Part 2: Software) Execution (as standalone) Troubleshooting Midi devices
104 lines (83 sloc) 8.82 KB
Raw Blame
Open in GitHub Desktop

General usage of the program

If you just want to use the program: this document. If you also want to write code for the program or change the code of the program itself: read USAGE_AS_A_LIBRARY.md.

This describes the general usage of the program as a standalone although most of it will still be relevant if you're using starting a program that uses this program as a library.

First time setup / Installation

All of the steps in this section may be skipped if they have been done earlier.

You need a computer running some kind of linux. Tested on Ubuntu and an Arch based distro (Manjaro to be precise).

You also need to have at least python 3.6 and pip (the python package manager) installed. If you're using a newer version of python than 3.6: substitute every 'python3.6' with the version you're using.

If you're using a notebook from the institute: you may have to switch to the 'willi' account (with su willi) and use sudo for some operations.

Download and folder name

  • Download the newest version and unpack it if it was packed
  • make sure the folder containing all of the programs files is named exactly "mr_keyboard"

Python modules

Make sure the following packages are installed (list installed packages: python3.6 -m pip list, install a package: python3.6 -m pip install <package>, append --user if you don't have sufficient rights). The versions listed here are the last ones that are known to work well with the program but any higher version should work just just fine (but you should be careful when using another main version). You only need to install the modules you will use. If, for example, you won't use midi then there is no need to install mido and python-rtmidi (but then midi has to be disabled either in the settings file or with the CLI flag).

Required
  • pyserial (v3.4)
  • ntplib (v0.3.3)
  • pyroute2 (v0.4.21)
Midi (optional)
  • mido (v1.2.8)
  • python-rtmidi (v1.1.0) or
  • install portmidi with the package manager of your system (on ubuntu: apt-get install libportmidi-dev). this is not a python module!

Usergroup

If you want to run the program without using the root account then you have to add your user to the group with access to tty devices (dialout in ubuntu, uucp in arch) if this hasn't been done already (it will run as it should if that has already been done). On Ubuntu: sudo usermod -a -G dialout user

Configure the local NTP server

To allow for the local NTP installation to act as a server: Edit /etc/ntp.conf (reboot to restart the NTP server when you're done):

  • remove any restrict <localhost> (localhost could also be '127.*.*.* or ::1)
  • add the following two lines:
    • server 127.127.1.1
    • fudge 127.127.1.1 stratum 12
  • make sure there is no noserve after a restrict

Settings

Every setting that may be changed is in 'settings.ini'. There are explanations for every setting included in the file. The file has to have this exact name (if you didn't provide another with a CLI flag).

Usage

Setup (Part 1: Hardware)

  • make sure the keyboard is not connected to a computer
  • switch the power on for everything (keyboard, notebook(s), midi device(s) and the network switch) you want to use
  • wait a minute (but don't wait too long, i.e. more than 15-30 minutes)
  • ensure the notebook(s) is/are connected to the power
  • connect everything you need (the keyboard and whatever midi devices you want to use) via USB to the computer running the program
  • connect everything you need (the keyboard and the notebook(s) you're using) with the network switch

Setup (Part 2: Software)

  • there is no need to configure the network manually as the program does this as well (if you're running it as a user with sufficient privileges, e.g. as root) but it may take a couple of tries until it is set
  • you do not need to manually connect to the boards to check if they work, the program checks it for you (and is a lot faster at it)
  • set midi->secondary_enable in settings.ini to True if you want to use any secondary midi devices with the program
  • read the section on midi devices below to learn more on how to use them
  • If you want to run it for a longer time: check your power settings (so it does not go to sleep). The program will stop if the computer goes to sleep!
  • You may want to set the name of your network interface (short description on Wikipedia) as default in the settings file (under local_machine->ifname, hints on how to do it are there). This is only necessary if you didn't do so before or want to set a different network interface as default

Execution (as standalone)

  • go in the folder containing the folder with the program files (e.g. __main__.py, settings.ini)
  • check the which version of python is installed/used with python3 and exit(). If the installed version is below 3.6: substitute every python3 below with python3.6 (or whatever version you have installed as long as it is >=3.6)
  • calibrate the inputs using the -c flag if the light conditions around the keyboard changed (this may, for example, be because of a change in location or incoming sunlight). This overwrites any older calibration data
  • There is a console interface including some options selectable by setting some flags. The available flags as well as some hints on how to use them can be found if you run python3 -m mr_keyboard --help
  • test the keys before you start an experiment just to be safe
  • You can start the program the program without a connection to the keyboard if you just want to set up the network or test the NTP server
  • run it with python3 -m mr_keyboard
  • use Ctrl + C to stop the program

Troubleshooting

  • missing network config: start the program as root until it the configuration is set by the program or configure the network as you've set it in the settings file (see point "Settings" above)
  • NTP server not reachable: wait about 5 - 30s and try again or call ntpd as root. If this doesn't work: call ntpd -q and ntpd as root
  • SerialTimeoutException: try again for a couple of times, if this doesn't help: restart the keyboard (disconnect USB, disconnect power to the keyboard and reconnect after ~15s, wait 1min, reconnect USB, try running the program again)
  • socket.timeout: restart the keyboard (see above)

Midi devices

  • you can use an arbitrary amount of midi inputs with the program
  • every midi (used) input will have its messages (only note_on + velocity and note_off) logged
  • each of the inputs can have up to one output (this means you can also have an input without an output if you just want to log the data but don't want the midi output)
  • you can use the same output for multiple inputs. This works but is not recommended if you have an alternative
  • you can find the midi configuration and some hints on the options (and their usage) in the settings file under [midi]
  • if you don't have a midi->audio converter (or need all of your USB ports): use a software synthesiser, below are some you could use
    • to imitate real instruments: fluidsynth (with Qsynth if you want a GUI), some usable free soundfonts can be found here: http://freepats.zenvoid.org/
    • else: something simple like amsynth or synthv1. There are loads of usable free ones
  • the Blüthner midi box is called "Bluethner Digital Piano"
  • the Yamaha digital piano (owners manual)
    • is called "CLP-150" but (as an output) you need to use the unique (full) name in the settings file (or just select it at runtime) as it has two channels and the name would be ambiguous otherwise
    • those two channels do not seem to be able to receive midi data independently from each other (and it looks like it's even worse than the merging we do in the program) -> use only one of the channels/outputs, use the same channel multiple times instead if you have to (and let the program merge the outputs)
    • you can however use the keyboard as its own output (use it as an input without an output in the program and let it generate its own sound, see below) and feed it midi signals from another source at the same time without problems (if "another source" is only one, if not the data from the other inputs will be merged again with the drawbacks this brings)
    • there seems to be a small but noticeable lag if you use it as its own midi output (doesn't generate its own sound but is used in the program as midi input with itself as the corresponding output). You may want to use another midi output for it in this case.
    • the manual recommends to turn of the power when connecting it to a computer via USB and when changing the midi output mode (on the bottom next to the USB port)
    • to enable/disable the generation of sound on its own when using it as a midi keyboard: go in the midi settings of the digital piano (button to the far right ont the control panel) and turn "LocalControl" on/off