HSC2011/Software/Frontend/Application development: Unterschied zwischen den Versionen

aus Metalab, dem offenen Zentrum für meta-disziplinäre Magier und technisch-kreative Enthusiasten.
Wechseln zu: Navigation, Suche
(moved from Frontend documentation)
 
(updated to last upload)
 
Zeile 17: Zeile 17:
 
by simply overwriting the <tt>display</tt> function.
 
by simply overwriting the <tt>display</tt> function.
  
=== querying buzzers ===
+
If you set up interval callbacks, make sure you remove them when <tt>Edubuzzer.stop_application</tt> is called.
  
<tt>/ygor</tt> is the base URI for the middleware endpoint. Send <tt>GET</tt> requests to
+
=== general infrastructure ===
certain named queries, e.g. <tt>?name=ls_accepted_login.sql</tt>. For the full list,
+
see directory <tt>Ygor/sql/</tt> in the [https://github.com/Metalab/hsc2011/tree/master/software software repository]. It returns a JSON array of objects/hashes whose
+
keys are described in the SQL file, e.g. for above:
+
  
<code>   
+
Throughout the games, the [http://api.jquery.com/jQuery.getJSON/ jQuery] library is used. In order to display buzzers, fill the <tt>$("#buzzers")</tt> area, additional user interface can be shown in <tt>$("#post-buzzers")</tt>.
    [{"rowid":42,"src":"BUZZER-DEVICE-ID","dest":"MASTER-DEVICE-ID",
+
        "seqnum":23,"ibutton":"SOMETHING","since":"TIMESTAMP",
+
        "accepted":true,"ack":false}, … ]
+
</code>
+
  
Refer to the table schemas in <tt>Ygor/schema/</tt> for explicit key/row names. Rely
+
=== talking to buzzers ===
on <tt>src</tt> for uniquely identifying a buzzer.
+
  
The most important query is <tt>ls_events.sql</tt> because it deals with the device
+
The <tt>global.js</tt> library implements most of the buzzer communication you'll need. For example, in order to turn on all the four LEDs on a buzzer called <tt>dst</tt>, do this:
buttons. The first line in the file hints at the additional query parameters,
+
in this case <tt>loginid</tt>, i.e. the full query string is
+
<tt>?name=ls_events&loginid=ROWID</tt> where <tt>ROWID</tt> is a number received in earlier
+
different queries. Extract the button status from the <tt>eventmask</tt> field. See
+
<tt>docs/serialprotocol</tt> for the semantics.
+
  
For debugging purposes the middleware exposes an echo interface at base URI
+
Edubuzzer.send_package(dst, 'S', 's', 'n n yyyy 00 00', function() {});
<tt>/echo</tt>. The query string is ignored except for the parameter name
+
<tt>Response-Body</tt>. Its value is a percent encoded JSON string which
+
unsurprisingly is returned as response body.
+
  
For example, you want to mock:
+
<tt>'S'</tt> is the package type to send (as described in [[HSC2011/Communication/Serial protocol|the serial documentation]]), <tt>'s'</tt> the type of the acknowledgement that is expected, <tt>'n n …'</tt> the payload (as described there as well), and the function will get called once the command is acknowledged by the buzzer.
  
<code>
+
Be aware that while the [[HSC2011/Software/Ygor|underlying middleware]] handles all requests in sequence, you can't rely on the browser to deliver multiple <tt>send_package</tt> calls in sequence.
    $.getJSON(
+
        Edubuzzer.middleware_endpoint+'?name=…',
+
        function (foo) {
+
            …
+
        }
+
    )
+
</code>
+
  
Add a [http://api.jquery.com/jQuery.getJSON/ second parameter to the <tt>getJSON</tt> call], thus:
+
Events other than acknowledgements you can receive by implementing the hook <tt>Edubuzzer.new_event(event)</tt>. Event will be an object with members <tt>src</tt>, <tt>type</tt> and <tt>payload</tt>, with <tt>type</tt> typically being <tt>"E"</tt>. The payload is typically <tt>"b0001"</tt> for the first button going down etc. (again, see, the serial documentation).
  
<code>
 
    $.getJSON(
 
        Edubuzzer.middleware_mock_endpoint+'?name=…',
 
        'Response-Body'+encodeURIComponent('[{"rowid":123}]')
 
        function (foo) {
 
            …
 
        }
 
    )
 
</code>
 
  
 
=== instruction list ===
 
=== instruction list ===

Aktuelle Version vom 4. Mai 2011, 06:52 Uhr

HSC2011

architectural overview

Each Edubuzzer app, e.g. Raise Your Hands, is chiefly implemented in a single responsible JavaScript file, e.g. raise-your-hands.js, located in Ygor's www directory. Each one can define a single callback, Edubuzzer.run_application which is called when the application is started.

Inside Edubuzzer.run_application it may register other callbacks like Edubuzzer.updated_known_logins which is called whenever a client is added or removed, or Edubuzzer.display which is called in regular intervals.

global.js runs a poor man's event loop and schedules all pollings to the server which result in callbacks of the active app registered being called. An app is activated by changing the URI #hash. The skeleton switches to an app by simply overwriting the display function.

If you set up interval callbacks, make sure you remove them when Edubuzzer.stop_application is called.

general infrastructure

Throughout the games, the jQuery library is used. In order to display buzzers, fill the $("#buzzers") area, additional user interface can be shown in $("#post-buzzers").

talking to buzzers

The global.js library implements most of the buzzer communication you'll need. For example, in order to turn on all the four LEDs on a buzzer called dst, do this:

Edubuzzer.send_package(dst, 'S', 's', 'n n yyyy 00 00', function() {});

'S' is the package type to send (as described in the serial documentation), 's' the type of the acknowledgement that is expected, 'n n …' the payload (as described there as well), and the function will get called once the command is acknowledged by the buzzer.

Be aware that while the underlying middleware handles all requests in sequence, you can't rely on the browser to deliver multiple send_package calls in sequence.

Events other than acknowledgements you can receive by implementing the hook Edubuzzer.new_event(event). Event will be an object with members src, type and payload, with type typically being "E". The payload is typically "b0001" for the first button going down etc. (again, see, the serial documentation).


instruction list

  • decide on an app name (e.g. exampleapp)
  • create a new JavaScript file with the name
  • implement the run_application function and the hooks you need
    • present the app UI in element #buzzers
    • keep internal data under the Edubuzzer.exampleapp namespace
  • add the app name/link in index.xhtml
  • register the app in global.js
  • add styles in edubuzzer.css