High-Level Design Specification for the Callimuse System

Transcription

1 High-Level Design Specification for the Callimuse System CSC354 Introduction to Software Engineering, Dr. Dale Parson, Fall This assignment is due by end of October 24, Introduction by the Instructor (Customer) There will be an in-class review within teams on Tuesday October 22 like before. Attendance is mandatory and counts for 15% of the project grade. Bring your draft document for peer review that day. Here are instructions for turning it in. cd $HOME cp ~parson/softeng/design13fall.zip SoftEng cd./softeng unzip design13fall.zip cd design13fall The Word file DesignSpec354Fall2013.doc is in there (this file). Copy that file onto your local machine and edit it. I MUST be able to open it with MS Word and view all text and illustrations for evaluation. I plan to integrate the high-level design specs into one Word document. If you edit it in Open Office or some other program, open it in Word on a KU computer before turning it in, to make sure I can read it. I will deduct 15% from any document turned in that I cannot open with Word. When you are done editing that file, copy it back into that same directory, cd into that directory and type gmake turnitin. That will send it to my account on acad. I have written a minimal system that actually runs and displays one test stroke. It mostly illustrates the skeletal structure of the Graphics Server. The MIDI Generator is very similar in overall multithreaded-server structure to the Graphics Server. The OSC/UDP application protocol includes lossless compression to cut down on the number of UDP datagrams per stroke, but it is missing fields and requires segmentation -> reassembly enhancements in order to work with normal, full-size strokes. There is generated Javadoc documentation for my working skeletal example here. The com.illposed.osc pages give the JavaOsc documentation, and the kucmuse and kutil pages give the Callimuse and related utility documentation. A requirement on your implementation code is the creation of Javadoc comments for all public and protected methods and fields that generates Javadoc HTML without warnings.

2 You can inspect my code on acad/bill at ~parson/softeng/parsonswe/trunk in the kucmuse and kutil subdirectories. You will be building atop that code base after approval of your design specifications. I have requested that KU IT add access for you to the Subversion code repository management database that we will use to manage code, and to the Bugzilla bug reporting system. We should have that access in time for the implementation process. We have gone over UML modeling tools and approaches in class. Use the textbook author s sketch approach, that I call a map of the design, in this assignment. Every student must capture at least one UML design diagram and turn it in with the descriptive text in this assignment. Turn in your assignments individually and I will integrate them as I grade them. Make sure that your subsections complement each other, and that they do not duplicate each other. There are more detailed instructions for each section below. Follow my writing guidelines. We already have a top-level deployment diagram on page 1 of the Functional Specification. Do not re-capture that diagram. The current, high-level design spec should show the insides of those boxes in the Functional Spec. See for the requirements specification. The present, functional specification is not comprehensive. It builds on, constrains, and resolves issues left open by the requirements spec. Partition each of the sections below into subsections, one per team member. 2. Vendor System Demo Design (COTS Team) By the end of the semester I would like a demonstration of the Nightshade system for scripting planetarium shows. Nightshade is available here. I am specifically interested in Nightshade NG PR2 Released including scripting. You will not be designing the Nightshade system. You will be designing a demo. Learn as much as possible about the Nightshade system and specify what you plan to demonstrate for this assignment. Include design illustrations for your plan. 3. Mobile User Interface Design (Mobile Client Team) My only small prototype code for this team is a demonstration of how to send an OSC/UDP broadcast message via our initial (to-be-extended) Callimuse protocol. See the main method test driver in the bottom of file kucmuse/callimuseframe.java. My Functional Spec gives the

3 anticipated fields for the protocol, which is outline in // implementation comments in method OSCInterpreter.run in file CallimuseFrame.java. See additional comments in the next section. 209 // HERE IS THE OSC/UDP DATAGRAM PROTOCOL THAT I AM USING. 210 // STUDENTS MUST FULLY DEFINED AND EXTEND IT: 211 // [0] String Sender's IP address for identification 212 // [1] Integer Sender's port identifier 213 // [2] Integer sequence number for fully assembled message 214 // [3] Integer subsequence number to steer reassembly 215 // [4] Integer total number of subsequences 216 // [5] Object [] of radii Float objects 217 // [6] Object [] of theta Float objects Use whatever UML diagramming techniques are useful. Use class diagrams. Use at least one of sequence diagrams, activity diagrams or state diagrams to show the flow of control or the changes of states or both. Class diagrams show structure. These other diagram types show highlevel behavior. Model the essential aspects of our app s interaction with Android libraries. You can show whatever Android classes are appropriate as simple class boxes; you do not need to show internal structure of Android libraries. 4. OSC/UDP Application Protocol and support (Networking Team) Your jobs are to design the full application protocol, to document some existing classes from my initial prototype, to show how you will extend that prototype to include segmentation and reassembly in order to accommodate the 1500-byte limit on a UDP datagram. Your classes from my Javadoc and code base include kutil.runnableosclistener, kutil.compressintegerfloatarrays and kucuse.callimuseoscserver. Write class diagrams that show their relationships. You can model any class or interface in JavaOsc (com.illposed.osc) as a simple box with no internal structure. For your classes, however, show all helper classes including private nested classes for the existing software. The previous section of this spec shows the draft, 7-field OSC application protocol of the initial code. You will need to extend it to support at least the fields in the Functional Spec, including array fields radius[] between 0.0 (center) and 1.0 (edge of dome), angle theta[] in the range [0.0, 2pi) radians, and virtual pressure[] for each centroid pixel. The scalar fields of the Functional Spec include color, brush stroke, momentum and spin. You do not need to use UML to illustrate the application protocols. Use Word tables like this.

4 Table I: Unsegmented OSC/UDP format that uses address pattern "/callimuse/stroke" 1 Sender IP [0] String Sender port [1] Integer 4000 Sender sequence [2] Integer 0 Sender subsequence Number of subsequences [3] Integer 0 [4] Integer 6 Radii [5] Object [] of Float Theta [6] Object [] of Float Here is another for the actual, compressed format that my initial code uses. It does not yet do segmentation and reassembly. Table II: Compressed OSC/UDP format that uses address pattern "/callimuse/stroke/reassemble" Sender IP [0] String Sender port [1] Integer 4000 Sender sequence [2] Integer 0 Sender subsequence Number of subsequences [3] Integer 0 [4] Integer 6 Radii [5] Integer [] of compressed Float Theta [6] Integer [] of compressed Float 1 See the initial stroke pattarns in the Javadoc for the strokepattern constants in class CallimuseFrame.

5 You need to extend these protocols in collaboration with the Mobile-client-UI, Graphics Server and MIDI Translator teams. You need to synchronize with the latter team and the MIDI Generator team to define their protocols. Your main implementation job is to design and later to implement segmentation and reassembly methods. Segmentation turns one OSC/UDP unsegmented message into a series of segmented messages that divide compressed arrays evenly across some number of OSC/UDP messages with no more than 1500 bytes. Allow no more than 250 total Integer [] elements per segmented message. Reassembly of unsegmented messages is probably the hardest part. We will go over a draft design that should be feasible in class. For now you need to document the design of the planned segmentation and reassembly methods in a class in package kutil. Use class diagrams. Use at least one of sequence diagrams, activity diagrams or state diagrams to show the flow of control or the changes of states or both. Class diagrams show structure. These other diagram types show high-level behavior. 4. Graphics Server Design Your interfaces and classes from my Javadoc and code base include kutil.dependentframe, kutil.startframe, kutil.polarcartesiandevice, kucmuse.callimuseframe and kucmuse.ideogram. You can model any class or interface outside of your assignment as a simple box with no internal structure. For your classes, however, show all helper classes including private nested classes for the existing software. Your main jobs are to add color, stroke styles, motion, generation of outbound OSC/UDP broadcast messages to be used by the MIDI generator, and ideogram recognition. I will help with ideogram recognition as needed. Do not delay graphical display waiting for ideogram recognition. We can run that in another thread. We have a 16-threaded Linux server with a high-powered GPU card called dumbledore in the Old Main lab. We can use that for testing, in addition to laptop(s) that members of the graphics team provide. I may have a laptop for you to use. The outgoing OSC/UDP protocol outline in the Functional Spec mentions OSC fields location, momentum, spin, disappearing / evaporating, color, brush stroke styling, and ideograms data coming from the graphics engine. Work with the MIDI team and the networking team You will probably need to incorporate a javax.swing.timer into your design to drive evolution of the graphics on the state of the dome in between arrival of OSC/UDP messages from the mobile UIs. Use class diagrams. Use at least one of sequence diagrams, activity diagrams or state diagrams to show the flow of control or the changes of states or both, for example the advance in state as driven by the timer, and the generation of outgoing OSC/UDP. Class diagrams show structure. These other diagram types show high-level behavior.

6 5. MIDI Generator Design I do not have starting code for the MIDI generator. My advice is to copy class kucmuse.callimuseframe into a new class kucmuse.midigenerator and use that as an example of how to set up your OSC listener thread. The OSC processing part of your class should map directly. You should implement a minimal GUI that has at least one graphical control, which is a combo box to select the MIDI device for output. Here are the top two graphical controls from the Scrabble-to-MIDI control GUI. Your code should run only in Synthesizer mode. Sequencer mode that creates and records and runs static MIDI sequences is not appropriate for this application, so you don t need that first combo box. If you use a foot controller to control some aspects of MIDI translation, then you will need a second combo box to select the input MIDI device. In directory parson/javalang/gamestomidi2013rev1/scrabble are the following files. ScrabbleToMultiMidiConfigUI.java is the MIDI generator UI class. It is too complicated to use as an example of the overall design, but it may supply some useful example code snippets. File ScrabbleToMultiMidi.java is the MIDI Translator for Scrabble. Again it is too complicated, but it may provide useful code snippets. The Javadoc for Scrabble-to-MIDI at the following URL is too big for use as a design example, but if you go inspecting the above two classes, some of that Javadoc may be useful. Some of the scheduling logic in helper class SynthRunnable inside that file may be useful; I will summarize state machine issues below. Basically, the MIDI Translator is a collection of state machines. A. There is one state machine that takes incoming OSC/UDP messages, maps them to musical phrases, and puts them into some kind of phrase queue. B. Another state machine takes the MIDI phrases out of the queue, according to time, and delivers them to a MIDI port. Note that you write notes to a javax.sound.midi. javax.sound.midi.receiver. This state machine should also write copies of repeating phrases (if any) back into the phrase queue. C. If you decide to support effects modulation from a foot controller or other MIDI controller device, javax.sound.midi.transmitter actually receives the incoming messages,

7 which you read via a custom application subclass derived from interface Receiver. The Transmitter sends MIDI messages to your Receiver. I recommend skipping (C) until you get (A) and (B) working. You can run (A) on the OSC/UDP acceptmessage thread (unless the mapping is so time consuming that your code starts dropping datagrams, in which case I will help you set up another thread to run the OSC-to-MIDI mapper), and you can run (B) in the GUI thread under the control of a javax.swing.timer object. I have never timed the output this way, but it seems like a simple enough approach. You could use a java.util.concurrent.priorityblockingqueue with note time as the priority function. Notes or phrases with earlier times come out first. Any thread enqueuing or dequeuing a note or phrase could peek() for the next time and then set a Swing Timer to go off at the time of the next note or phrase, and then write MIDI output. Probably the simplest way to integrate (C) into this design is to write a MIDI-to-OSC message translator that runs on its own thread and sends OSCMessages to the acceptmessage method already running in (A). That way all incoming rata arrives as OSC messages. I can help to write this MIDI-control-to-OSC translator. Do not worry about implementing sound spatialization too much just yet. However, we are only writing a spec at this time, not code, so you should address spatial sound at a very high level in this spec. In addition to a class diagram, each of the above state machines needs a simple, state machine diagram. A simple dataflow diagram can show the flow of data though your nodes in the deployment diagram and within Ableton Live. An outline of how you plan to route MIDI channels through Ableton Live would also be useful. That would be a dataflow diagram. Feel free to show an illustration of the Live work surface if useful.