====== Bones Milestone spezifische LUA Module ======

===== Milestone =====

Das Milestone Modul enthält grundsätzliche Funktionen zur Milestone Hardware oder Konfigurationseinstellungen. Augenblicklich sind dies Folgende Funktionen:

  * [[module#respath|respath]]

==== respath ====

'' respath(pfad) ''

''respath'' liefert den plattformunabhängigen Pfad zu Unterverzeichnissen zurück und wird als Hilfsmittel zur Entwicklung von Milestone LUA Programmen auf dem PC eingesetzt. Mit hilfe dieser Funktion ist es möglich unter der Entwicklungsumgebeung den selben Programmcode bezüglich Pfade zu verwenden wie auf dem Gerät selbst.

Beispiel:

Öffnen einer Textdatei aus dem Unterverzeichnis ''.\save\''
<code lua>
-- Get resource path
local respath = Milestone.respath('save')
local f = io.open(respath .. "highscore.txt", "w+")
</code>


===== Language =====

Da Bones Milestone Geräte mehrsprachig ausgeliefert werden, sollten Ihre Programme optimaler weise auch Mehrsprachigkeit unterstützen. Um den Aufwand möglichst gering zu halten gibt es das Modul ''Language''. durch die Funktionen dieses Moduls können Sie Tabellen mit Zeichenketten in verschiedenen Sprachen verwalten. Der Zugriff erfolgt dabei über [[https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes|ISO 639-1 Sprachkürzel]] oder über den Index innerhalb der Tabelle. Reihenfolge der Sprachen innerhalb einer Übersetzungstabelle ist: 

<code lua>
local ltable = {
  {"English", "EN"},
  {"German", "DE"},
  {"French", "FR"},
  {"Italian", "IT"},
  {"Spanish", "ES"},
  {"Swedish", "SV"},
  {"Dutch", "NL"},
  {"Norwegian", "NO"},
  {"Danish", "DA"},
  {"Polish", "PL"},
  {"Icelandic", "IS"},
  {"Japanese", "JA"},
  {"Portugese", "PT"},
  {"Turkish", "TR"},
  {"Arabic", "AR"},
  {"Catalan", "CA"},
  {"Czech", "CZ"},
  {"Finnish", "FI"},
  {"N/A", "NA"},
  {"Greek", "EL"},
  {"Russia", "RU"},
  {"Portugese Brazil", "PT-BR"},
  {"Chinese", "CH"},
}
</code>

Funktionen:

  * [[module#machid|machid]]
  * [[module#id|id]]
  * [[module#set|set]]
  * [[module#get|get]]
  * [[module#getlocal|getlocal]]
==== machid ====

''machid()''

''machid'' gibt die Spachkennnummer des entsprechenden Systems zurück. Diese Kennnummer entspricht dem Index der jeweiligen Sprache in folgender [[module#Language|Tabelle]].

==== id ==== 

''id(ISOlang)''

''id'' gibt die Sprachkennnummer zu einem [[https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes|ISO 639-1 Sprachkürzel]] zurück. Siehe auch folgende [[module#Language|Tabelle]].

==== set ==== 

''set(ISOlang, text, texttable)''

''set'' setzt in der Übersetzungstabelle ''texttable'' den angegeben Text als Sprache, welche durch das ISOlang Kürzel angegeben wurde. Rückgabewert ist die neue Tabelle.

Beispiel:

<code lua>
  local second
  second = language.set("EN","seconds")
  second = language.set("DE","Sekunden", introhigh)
</code>

Alternativ können die Texte auch beim erzeugen der Tabelle übergeben werden:

<code lua>
  local second = {"seconds", "Sekunden"}
</code>

Bezüglich der Reihenfolge beachten Sie bitte hierbei folgende [[module#Language|Tabelle]].

''set'' entspricht in etwa folgendem Aufruf:

<code lua>
  texttable[id(ISOlang)] = text
</code>

==== get ==== 

''get(ISOlang, texttable)''

''get'' gibt den Text der Übersetzungstabelle ''texttable'' zurück, welcher durch das ISOlang Kürzel angegeben wurde.

Beispiel:

<code lua>
  local second = {"seconds", "Sekunden"}
  print('50' .. language.get("DE", second))
</code>

''get'' entspricht in etwa folgendem Aufruf:

<code lua>
  texttable[id(ISOlang)]
</code>

==== getlocal ==== 

''getlocal(texttable)''

''getlocal'' gibt den Text aus ''texttable'' in der Sprache des aktuellen Systems zurück.

Beispiel:

<code lua>
  local second = {"seconds", "Sekunden"}
  print('50 .. language.getlocal(second))
</code>

um die Verwendung noch etwas kürzer zu machen kann man ein entsprechendes kürzeln (z.B. ''_T'') setzen:

<code lua>
  local _T = language.getlocal -- to get local text  
  local second = {"seconds", "Sekunden"}
  print('50 .. _T(second))
</code>

===== Audio =====

Das Audio Modul umfasst folgende Funktionen:

  * [[module#play|play]]
  * [[module#stop|stop]]
  * [[module#pause|pause]]
  * [[module#resume|resume]]
  * [[module#tts|tts]]
  * [[module#status|status]]
  * [[module#record|record]]

==== play ==== 

''play(dateiname)''

''play'' startet das Abspielen der Audio-Datei mit dem Pfad ''dateiname''. Rückgabewert ist nil wenn die Datei abgespielt werden kann oder eine Fehlermeldung, falls nicht.

Beispiel:

<code lua>
  res = audio.play("test.mp3")
  if res then
    print("play file error:" .. res .. fname)
  end
</code>

Bei erreichen des Endes der MP3 Datei endet das Abspielen automatisch und es wird das Event ''FILE_END'' in die Event-Queue gelegt. Siehe auch [[module#Event|Event]].
==== stop ==== 

''stop()''

''stop'' stoppt das laufende Abspielen/Aufnehmen. Rückgabewert ist nil, bzw. eine Fehlermeldung.

==== pause ==== 

''pause()''

''pause'' pausiert das laufende Abspielen/Aufnehmen. Rückgabewert ist ''nil'', bzw. eine Fehlermeldung.

==== resume ==== 

''resume()''

''resume'' Wiederaufnahme des laufende Abspielen/Aufnehmen nach ''pause''. Rückgabewert ist ''nil'', bzw. eine Fehlermeldung.

==== tts==== 

''tts()''

''tts'' Weist auf dem Milestone die 'Text To Speech' Synthese an den Text in gesprochene Sprache zu wandeln und auszugeben. Auf dem PC wird die Textzeile auf der Konsole ausgegeben. Entspricht der Anweisung ''print'' der jeweiligen Plattform.

==== status==== 

''status()''

''status'' Gibt den Status der Audio Engine als Table zurück:

^ Feld      ^ Typ    ^ Inhalt            ^
| status    | String | play/pause/stop   |
| elapsed   | Zahl   | Position in ms    |
| remaining | Zahl   | Verbleibend in ms |

==== record==== 

''record(filename, optionen)''

''record'' Startet eine Aufnahme. Die Datei wird entsprechend ''optionen'' in die Zieldatei ''dateiname'' geschrieben.

Optionen sind:

^ Feld       ^ Typ    ^ Inhalt     ^ Beschreibung                                                   ^
| source     | String | mic/tuner  | 'tuner' für radioaufnahmen, 'mic' für jegliche andere Aufnahme |
| headphones | Bool   | 1/0        | 1 für mithören der Aufnahme über Kopfhörer                     |
| sound      | String | signalton  | Name des Signaltons der vor der Aufnahme abgespielt werden soll|
| external   | Bool   | 1/0        | 1 für externes Mikrophon, 0 für internes                       |


===== Event =====

Benachrichtigungen wie das Ende des Abspielen einer MP3 Datei, oder das Drücken einer Taste finden auf dem Milestone über Nachrichten in einem eine Ereignispuffer statt. Der Puffer funktioniert nach dem FIFO Prinzip (zuerst herein - zuerst hinaus).

Folgende Ereignisse sind definiert:

^ Ereignis          ^ Beschreibung              ^
| KEY_PLAY          | Play-Taste                |
| KEY_MODE          | Mode-Taste                |
| KEY_REC           | Rekord-Taste              |
| KEY_FF            | Rechte Pfeiltaste         |
| KEY_REW           | Linke Pfeiltaste          |
| KEY_SEL           | Selektortaste             |
| FILE_END          | Ende einer Datei erreicht |


Mit folgenden Funktionen kann auf die Ereignisse zugegriffen werden.

  * [[module#count|count]]
  * [[module#clear|clear]]
  * [[module#push|push]]
  * [[module#pop|pop]]

==== count ====

''count()''

''count'' gibt die Anzahl der Nachrichten des Ereignispuffers zurück.

==== clear ====

''clear()''

''clear'' löscht alle Nachrichten des Ereignispuffers.

==== push ====

''push(evcode, param)''

''push'' plaziert den Event ''evcode'' mit den Parameter ''param'' im Ereignispuffer. Die Funktion gibt bei Erfolf 0 zurück und -1 bei einem zu vollen Puffer.

==== pop ====

''pop()'' 

''pop'' gibt eine Tabelle zurück welche den ältesten Event und den zugehörigen Parameter enthält.

Beispiel:

<code lua>
-- Auf eine Taste warten, alle anderen Events verwerfen
  function hit_key()
    local keys = {event.KEY_PLAY, event.KEY_MODE, event.KEY_REC, event.KEY_FF, event.KEY_REW, event.KEY_SEL }  
    local loop = true
    local ev
    event.clear()
    while loop do
      ev = event.pop()
      if ev ~= nil then
        for i, v in ipairs(keys) do
          if v == ev then
            loop = false
            break
          end    
        end    
      end
    end    
    return ev
  end
</code>

===== RTC =====

Funktionen der Echtzeituhr:

  * [[module#time|time]]
  * [[module#set|set]]

==== time ====

''time()''

''time'' gibt die Anzahl Sekunden seit dem 01.01.1970 zurück.

==== set ====

''set(year, mon, day, hour, min, sec)''

''set'' setzt die Echtzeituhr.

===== RTOS =====

  * [[module#wait|wait]]

==== wait ====

''wait(ms)''

''wait'' wartet die angegebene Zahl von Millisekunden und gibt dem System die Möglichkeit etwas inzwischen anderes zu tun.

===== Timer =====

  * [[module#read|read]]
  * [[module#delay|delay]]

==== read ====

''read()''

''read'' gibt die Mikrosekunden seit Systemstart zurück.

==== delay ====

''delay(μs)'' 

''delay'' wartet die spezifizierte Anzahl von Mikrosekunden ohne dem System die Möglichkeit zu geben etwas anderes zu tun.