Tjoho Applikationsutvecklarens handledning Maj 2003 Uppdragsgivare: Ylva Dalén, KI Starthus Projektmedlemmar: Sophia Demnert, Elina Eriksson, Kamilla Johansson Per-Jonny Käck, Ingela Linered, Åsa Moum, Michael Stockman, Stefan Trolle
Innehåll Inledning... 2 Bakgrund... 2 Beskrivning av systemet... 2 Applikationsvision... 3 Applikationen... 4 Funktioner i systemet... 4 Översiktlig beskrivning av applikationen... 4 Hur applikationen kommunicerar med servern... 4 Signaler... 5 Insignaler... 5 Utsignaler... 6 Hintar... 7 1
Inledning Nedan följer en beskrivning av vad man ska tänka på och hur man ska gå till väga när man utvecklar en applikation. Dokumentet är skrivet i första hand för den som utvecklar en applikation i programspråket JAVA och som använder sig av det klientbibliotek som finns tillgängligt för detta programspråk. Det är möjligt att utveckla applikationer i andra programspråk, men då får utvecklaren antingen skriva ett nytt klientbibliotek för detta programspråk eller i sin applikation kommunicera direkt med servern med hjälp av tjohoxml, se bilaga TjohoXML. Bakgrund Bakgrunden till projektet är att tillhandahålla roliga och stimulerande applikationer som handikappade barn kan använda. Tanken är också att applikationerna ska ge barnet möjlighet att själv generera rörelser på plattformen. Förhoppningen är att rörelserna på plattformen ska stärka barnets benstomme samtidigt som barnet har roligt. Eftersom vi inte har haft någon möjlighet att testa vårt system på barnen så har vi lagt ned mest arbete på kommunikationen mellan plattform och applikationer samt att förenkla utarbetandet av nya applikationer i framtiden. Beskrivning av systemet Systemet består i stort av tre olika delar. En server, en plattform, (själva maskinen), och ett klientbibliotek. Plattformen är själva maskinen som barnet står i, det är där knapparna finns som styr alla händelser och rörelser. Servern är den del som sköter kommunikationen mellan applikationen och plattformen. För att underlätta kommunikationen mellan applikationen och servern finns ett klientbiblioteket utvecklat i Java. Om man utvecklar en applikation i Java innebär det att man inte behöver tänka på i vilken form servern vill ha informationen utan endast använda sig av befintliga metoder i klientbiblioteket. Kommunikationen mellan applikationen och servern går via klientbiblioteket och sker med hjälp av signaler som skapas av applikationen och registreras hos servern. För fullständig beskrivning av systemet, se bilaga TjohoUML. I en applikation definieras hur de olika knapparna på plattformen ska styra händelser och rörelser. Det sker med hjälp av tips, (hintar), som skrivs i applikationen och som under körning skickas till servern. Om man ansluter flera applikationer på en gång så är det den applikation som sist registrerade sina hintar som får högst prioritet. Plattformen kan också ersättas av en simulator som med fördel kan användas för att testa applikationerna. Den agerar då istället för plattformen. För mer 2
information om hur simulatorn fungerar, se bilaga Simulator. Man kan inte ansluta både plattformen och simulatorn samtidigt. Om man vill utveckla applikationer i ett annat programspråk än java så går det bra eftersom all kommunikation med servern sker via XML, se bilaga TjohoXML, se bilaga TjohoXML. Om man ska utveckla flera applikationer i samma språk bör man skriva ett nytt klientbibliotek för det språket. Applikationsvision Tanken om hur en applikation skulle kunna utnyttja de funktioner som systemet tillhandahåller. En av tankarna är att det är lättare att skriva en applikation som använder sig av servern för att styra plattformen Tjoho än att kommunicera direkt med plattformen. Ytterligare en tanke är att det är lättare att kommunicera med klientbiblioteket än med servern, även om den möjligheten fortfarande finns kvar. En applikation som är till mest glädje och nytta för barnen utnyttjar en så stor del som möjligt av de funktioner som finns tillgängliga på plattformen. På så sätt blir det så omväxlande som möjligt för barnen som använder plattformen. Det är därför lämpligt att det finns flera svårighetsgrader på en applikation så att man kan ändra funktionerna lite efter barnens utveckling, men också så att flera barn kan ha glädje av samma applikation trots att de kan olika mycket. En applikation ska fungera på så sätt att när den startas av en användare så försöker den att ansluta sig till servern via klientbiblioteket. När detta har lyckats får användaren välja svårighetsgrad mm i ett grafiskt gränssnitt för login som finns i klientbiblioteket. Nästa steg för applikationen är att registrera de signaler, funktioner och tips, (hintar), som den behöver för att kunna fungera som tänkt. Därefter kan applikationen utföra sitt huvudsyfte, att roa barnet. När barnet har använt applikationen klart ska applikationen, innan den stängs av, avregistrera de signaler och hintar som den tidigare registrerat. På så sätt kan plattformen fortsätta att köras utan just denna applikation. 3
Applikationen Funktioner i systemet De funktioner som finns tillgängliga i systemet: - Knapptryckningar - Vridning - Höjning/Sänkning - Vibration - Lutning - Hopp Det finns dock inte stöd för alla dessa funktioner på den nuvarande plattformen Hoppolek men det kommer att finnas på nästa version, Tjoho. Översiktlig beskrivning av applikationen Det första man måste göra när man ska utveckla en applikation är att tänka ut vad som ska hända om man trycker på de olika knapparna på plattformen och vilka signaler som behövs för att styra detta. Alla signaler från applikationen måste registreras hos servern. För att koppla ihop en signal med en knapp använder man sig av hintar. Om man vill att flera knappar ska styra samma funktion finns det hint-kommandon även för detta. Hintar består av signaler och kanter mellan dem samt noll eller flera olika operationer. Operationerna kan till exempel koppla ihop flera knapptryckningar så att de gemensamt styr en signal. När applikationen har körts klart är det viktigt att komma ihåg att avregistrera de signaler och hintar som tidigare blev registrerade. Hur applikationen kommunicerar med servern För att applikationen ska kunna kommunicera med servern måste den hämta en tillgänglig instans av klientbiblioteket genom att anropa metoden CRMClient.getInstance(). Det är sedan denna instans som används nedan i metodanropen. För att applikationen ska kunna startas måste servern först vara startad. Detta behöver man inte ta hänsyn till vid utvecklandet av applikationen men kan vara bra att känna till om det inte fungerar som väntat när man startar applikationen. Man måste också ansluta sin instans av klientbiblioteket till servern. Det sker genom metoden connect(). Ex CRMClient.getInstance().connect(). Applikationen måste också registreras för att kunna fungera. Det sker genom att skriva CRMClient.getInstance().registerApplication(applikationsNam n). Om applikationen av någon anledning skulle bli nedkopplad från servern finns en metod reconnect() tillgänglig, som har sparat all information om 4
applikationens namn samt vilka signaler och hintar som har registrerats så att man slipper tänka på att göra om detta om man blir nedkopplad. Man kan stänga anslutningen till servern genom metoden close(). All sparad information i klientbiblioteket, som till exempel applikationens namn, behålls dock så att ett anrop till reconnect() är möjligt. Det finns möjlighet att få information varje gång en registrerad insignal ändrar värde genom att ärva ett interface SignalListener, och sedan registrera sig som lyssnare till insignalen. Så fort en signal ändrar värde anropas då metoden valuechanged(). Det är i denna metod man får kontrollera vilken signal som hade ändrat värde. Man måste dock inte använda sig av SignalListener utan man kan också själv kontrollera vilket värde de olika signalerna har genom att anropa getvalue() i signalen. Signaler Det finns två olika sorters signaler, insignaler och utsignaler. Insignalerna kommer in till applikationen och innehåller information om vad som har hänt på plattformen, t ex att en knapp har tryckts ned. Utsignalerna är signaler från applikationen till plattformen med information om hur plattformen ska röra sig. Både insignaler och utsignaler kan vara av två olika typer, frekvens eller binär. Frekvenssignalerna kan endast anta värdet 0 eller något positivt heltal. Binärsignalerna kan anta värdet 0, eller 1. Följande metoder finns tillgängliga i Signal: gettype(), anger vilket typ signalen är av. getname(), anger vilket namn signalen har. getvalue(), anger vilket värde signalen har. Insignaler Insignaler är de signaler som kommer från plattformen till applikationen, dvs de talar om att någonting har hänt på plattformen. Ett exempel kan vara att en knapp har blivit nedtryckt eller uppsläppt. Om man har implementerat SignalListener och lagt till sig som lyssnare till insignalerna, så anropas metoden valuechanged(signal sig, int val) så fort en insignal ändrar värde. Vad som ska hända i den metoden är fritt för applikationen att välja. sig anger vilken signal det är som har ändrat värde, och ett bra sätt att få inormation om denna signal är att anropa metoden getname().val anger signalens nya värde. Ett annat sätt att få information om att en signal ändrat värde är att kontinuerligt avläsa (polla) signalens värde genom att anropa metoden getvalue(). 5
För att skapa en insignal skriver man till exempel new InSignal( signalnamn, SignalType.BINARY) eller new InSignal( signalnamn, SignalType.FREQUENCY);. För att insignalen ska fungera som tänkt måste man registrera signalen. Det görs genom ett anrop till metoden CRMClient.getInstance().registerSignal(signalnamn). För att man ska få information om att signalen har ändrat värde måste man också lägga till en signallyssnare. Det görs genom ett anrop till metoden addsignallistener(signallistener listener), exempelvis signalnamn.addsignallistener(applikationsnamn). Efter detta ska värdeändringar i någon signal medföra att metoden valuechanged() exekveras. Om man inte behöver en signal mer kan man avregistrera den hos servern genom att anropa metoden CRMClient.getInstance().unregisterSignal(Signal signal). Utsignaler Utsignaler är de signaler som applikationen skickar till plattformen för att tala om hur den ska röra sig. Det krävs en signal för varje rörelse, det vill säga en utsignal för att plattformen ska röra sig upp och en annan för att den ska röra sig ned. Man måste skapa en utsignal för varje rörelse man vill att plattformen ska kunna utföra i applikationen. Utsignaler skapas på ett sätt som liknar insignalernas, genom att skriva new OutSignal( signalnamn, SignalType.BINARY) eller new OutSignal( signalnamn, SignalType.FREQUENCY). För att sedan ändra värdet på en utsignal anropar man metoden setvalue(int value), där value anger det nya värdet. Exempelvis signalnamn.setvalue(1). De utsignaler som finns tillgängliga för att styra plattformen Tjoho är följande. up signal för att röra plattformen uppåt, binär down signal för att röra plattformen nedåt, binär jump signal för att plattformen ska hoppa, binär left signal för att plattformen ska svänga vänster, binär right signal för att plattformen ska svänga höger, binär lean_left signal för att plattformen ska luta åt vänster, binär lean_right signal för att plattformen ska luta åt höger, binär vibrate signal för att plattformen ska vibrera, frekvens Om man inte behöver en signal mer kan man avregistrera den hos servern genom att anropa metoden CRMClient.getInstance(). unregistersignal(signal signal). 6
Hintar En hint beskriver en bra koppling för en given signal för att en applikation ska fungera på det sätt som applikationsprogrammeraren vill. En hint innehåller information om ett generellt bra sätt att koppla ihop signaler i ett logiskt nät med hjälp av logiska operatorer. En hint definieras av den minsta och högsta svårighetsgraden, som gäller för den hinten, samt hintens namn. Hinten kan bestå av en eller flera objekt (object) och kanter (edge). Alla objekt till alla kanter måste deklareras innan kanterna kan deklareras. En hint skapas när man skriver hint = new Hint(Hint.DIFFICULTY_EASY, HINT.DIFFICULTY_HARD, app). Första och andra parametern representerar den lägsta respektive den högsta svårighetsgrad som hinten ska vara giltig för. De svårighetsgrader som är definierade är: DIFFICULTY_EASY, DIFFICULTY_MEDIUM och DIFFICULTY_HARD. Sista parametern app är en String med applikationens namn, samma namn som applikationen registrerat hos klientbiblioteket. För att lägga till en plattformssignal i hinten skriver man t ex Object o1 = hint.addsyssignal( button1 ). Plattformen Tjoho har 9 knappar och en del andra signaler som finns specificerade i samma dokument som tjohoxml, se bilaga TjohoXML. Knapparna heter button1 till button9. En beskrivning av den nuvarande applikationens signal skapas när man skriver Object o2 = hint.addappsignal(app, sign.getname(). Första parametern app är en String med applikationens namn. Andra parametern är namnet på en instans av antingen klassen InSignal eller OutSignal. För att lägga till en beskrivning av en funktion till en hint skriver man Object o3 = hint.addfunction( or1, Or )eller Object o4 = hint.addfunction( pulse1, PulseControl,20000 ). Den första parametern i metoden addfunction är det namnet som operationen får av applikationsutvecklaren och den andra är den logiska operatorn. Namnet på operationen ska vara unikt inom samma hint. Det vill säga att två operationer inom samma hint inte kan heta pulse1. De logiska operatorerna, med dess parametrar är; (se även bilaga TjohoXML) - And kräver att alla insignaler till operationen ska vara ickenoll för att utsignalen ska bli ett. Parametrar: inga - CountMemory (typ 1) kräver precis två insignaler och ger som utdata en frekvens ur en frekvenstabell. I minnet finns ett index till frekvenslistan som bestämmer utsignalen. Den ena insignalen ökar index med ett och den andra insignalen minskar index med ett. CountMemory startar på den första frekvensen i frekvenslistan. 7
Parametrar: typnamnet stable, uppapplikationsnamn, uppsignalnamn, nerapplikationsnamn, nersignalnamn, lista med frekvenser. - CountMemory (typ 2) kräver precis två insignaler och ger som utdata en av tre frekvenser. Den första frekvensen i frekvenslistan är defaultfrekvens som används när båda insignalerna är 0. Kopplad till respektive insignal finns dessutom en frekvens som används när den insignalen är ickenoll. Om båda insignalerna är ickenoll så används frekvensen till den insignal som först blev ickenoll. Parametrar: typnamnet unstable, applikationsnamn1, signalnamn1, applikationsnamn2, signalnamn2, defaultfrekvens, frekvens1, frekvens2. - Not negerar insignalen, ickenoll ger noll som utsignal och noll ger ett som utsignal. Parametrar: inga - OnOffSwitch växlar mellan ett och noll. Växlingen sker när insignalen går från noll till ickenoll. Parametrar: inga - Or kräver att någon av insignalerna till operationen ska vara ickenoll för att utsignalen ska bli ett. Parametrar: inga - PulseControl ger ett som utsignal så länge som insignalen är ickenoll men inte längre än en specificerad tid. Parametrar: tid i millisekunder. En hint består också av flera kanter (edge). En kant innehåller information om hur de tidigare beskrivna signalerna och operationerna ska kopplas samman, till exempel att en signal ska kopplas till en logisk operator eller direkt till en annan signal. En kant läggs till hinten genom att skriva hint.addedge(o3, o4). Varje kant måste gå mellan två objekt. Hinten registreras hos servern genom att använda sig av metoden CRMClient.getInstance().addHint(hint). 8