A09-05 OSGi IRC Bot For Coffee Maker (4op) AS-0.3200 Automaatio- ja systeemitekniikan projektityöt Loppuraportti Syksy 2009 Ryhmä Henri Nieminen Juha Sironen Ohjaaja: Heikki Nikula Aloitettu: 08.09.2009 Päätetty: 08.12.2009 Nieminen, Sironen
Sisällysluettelo 1 JOHDANTO... 3 2 TEORIAA... 4 2.1 IRC... 4 2.2 OSGI... 5 2.3 BUNDLE... 5 2.4 PIRCBOT... 5 3 PROJEKTIN AIKATAULUN SEURANTA... 6 4 KUSTANNUSTEN SEURANTA... 7 5 PROJEKTIN TULOKSET... 8 6 BUNDLEN KÄYTTÖ... 9 7 COFFEEBOTIN KÄYTTÖ...12 8 PROJEKTIN ANALYSOINTI...13 9 YHTEENVETO...14 LÄHTEET...15 LIITTEET LIITE 1 BotActivator class LIITE 2 CoffeeBot class LIITE 3 BotListener class LIITE 4 UsersList class LIITE 5 BotActivator Javadoc LIITE 6 CoffeeBot Javadoc LIITE 7 BotListener Javadoc LIITE 8 UsersList Javadoc LIITE 9 Projekti päiväkirja Nieminen, Sironen
1 Johdanto Tämä työ on toteutettu kurssilla Automaatio- ja systeemitekniikan projektityöt (AS- 0.3200) syksyllä 2009 Automaation ja systeemitekniikan laitoksella. Työssä on toteutettu Automaatiotekniikan laitoksella sijaitsevan kahvinkeittimen ohjaus IRC:n kautta, hyväksi käyttäen IRC-bottia. Työ on toteutettu Java ympäristössä ja ohjelmointi alustana on käytetty Java Eclipse SDK:ta. IRC-botin runkona on käytetty Jibble:n PircBottia. Java koodista on muodostettu bundle, jota ajetaan Knopflerfish:n OSGi alustalla. Itse kahvinkeitin (esitettynä kuvassa 1) oli jo ennen projektia aloitusta fyysisesti liitetty verkkoon ja sillä oli oma bundle (Coffee Maker) valmiina. Tässä raportissa esitellään työn tuloksia ja analysoidaan niitä. Projekti on toteutettu parityönä. Kuva 1 Ohjattava kahvinkeitin Projektin tavoitteena oli saada ohjattua kahvinkeitintä IRC:n (Internet Relay Chat) kautta. Tavoitteena oli luoda IRC-botti, joka vastaa IRC-kanavalle annettuihin käskyihin. IRCbotin tulee ottaa yhteys automaattisesti IRC-kanavaan ja pysyä kanavalla. Jos yhteys katkeaa, tulee Botin ottaa automaattisesti yhteys uudestaan. Botti välittää käskyt Coffeemaker sovellukselle ja palauttaa sieltä saadut tiedot IRC-kanavan käyttäjälle. Lisäksi Botin tulee osata hallita käyttäjiä, jottei kuka tahansa voi liittyä IRC-kanavalle ja Nieminen, Sironen 3
keittää kahvia. Käyttäjien hallinta toteutetaan ensin alkuun käyttäjä rekisterillä, joka luodaan käsin. Lisätavoitteena oli luoda Bottiin ominaisuus, joka voi päivittää rekisteriä IRC-kanavan kautta. Työssä avain sanoja ovat IRC, IRC-Bot, OSGi, Knopflerfish, Bundle, Java. Työmäärä tavoitteena oli 4 opintopistetta per projektin jäsen. 2 Teoriaa 2.1 IRC IRC on lyhenne sanoista Internet Relay Chat. IRC on internetin pikaviestintäpalvelu, joka mahdollistaa reaaliaikaisen keskustelun Internet-käyttäjien välillä. IRC:n keskustelut käydään kirjoittamalla tekstiä ja lukemalla näytöltä muiden kirjoittamia viestejä. IRC:iin pääsee tarkoitusta varten tehdyllä asiakasohjelmalla tai joidenkin WWW-sivujen kautta. IRC:n kehitti Jarkko Oikarinen vuoden kesällä 1988. Nykyään pelkästää Suomessa IRC:llä on kymmeniätuhansia käyttäjiä ja kanaviakin on tuhansia. IRC:n ympärille on Suomessa kehittynyt muutama WWW-palvelu, kuten IRC-Galleria. Lisäksi Internetiin on ilmaantunut IRC:n kaltaisia palveluita, chattejä. IRC:n yleisin käyttö lienee kuitenkin yksityisten henkilöiden välistä keskustelua. IRC:ssä on lähes rajaton määrä kanavia eri aiheista monilla eri kielillä. IRC:ssä on keskustelua vuorokaudenaikaan katsomatta lähes aina.[1] IRC on avoin TCP/IP:n päällä toimiva protokolla. Käyttäjä käyttää IRC:tä ottamalla yhteyden IRC-palvelimeen asiakasohjelmalla. IRC:stä on useita palvelin- ja asiakasohjelmatoteutuksia. IRC-palvelimet muodostavat keskenään IRC-verkkoja. Useimmat IRC-verkot ovat julkisia, eli verkkoon voi liittyä keskustelemaan kuka tahansa. IRC:n käyttäjä saa viestejä ainoastaan olleessaan kytkeytyneenä palvelimeen; jos käyttäjä ei ole verkossa, hänelle lähetetyt viestit jäävät saapumatta. Pysyvä IRC:ssä paikallaolo vaatii koko ajan päällä olevan asiakasohjelman pysyvästi verkossa olevalla koneella. Tämä voi tapahtua Unix-koneessa ajettavalla tekstipohjaisella IRC-ohjelmalla, jolloin puhutaan shell-tunnuksesta tai samankaltaisella ns. bouncer-ohjelmalla, joka toimii välityspalvelimena ja kerää viestejä käyttäjän poissaolon aikana.[1] Nieminen, Sironen 4
2.2 OSGi OSGi alusta on moduuli systeemi Java alustalle, joka implementoi täydellisiä ja dynaamisia komponentti mallia. Sovellukset tai komponentit voidaan tilapäisesti asentaa, käynnistää, pysäyttää, päivittää ja poistaa ilman uudelleen käynnistämistä. Komponentit ovat ihan tavallisia jar-tiedostoja, joiden selitysosassa (manifest-tiedosto) on OSGiin liittyviä headereita. Näitä komponentteja kutsutaan bundleiksi.[2] 2.3 Bundle Bundle on ryhmä Java luokkia ja lisättyjä resursseja varustettuna yksityiskohtaisella manifesti tiedostolla kaikesta sisällöstä ja tarpeellisilla täydentävillä palveluilla, joilla aikaansaadaan lisättyjen ryhmien Java luokkiin kehittyneempiä toimintoja.[2] 2.4 PircBot PircBot on Java ympäristö, jonka avulla pystytään kirjoittamaan IRC botteja helposti ja nopeasti. Sen ominaisuuksia ovat tapahtumapohjainen hallinta yleisille irc tapahtumille, ylivuotosuoja, jatkuva tuki DCC:lle (Direct Client-to-Client), tuki yksilöinnille ja lisäksi monia muita ominaisuuksia. Sen kattava rekisteritiedoston muoto sopii käyttöön yhdessä pisg:in (Perl IRC Statistics Generator) kanssa, kanavan tapahtumien tilastoimiseen. PircBot anta mahdollisuuden erilaisten hauskojen tehtäviensuorittamiseen IRC:ssä, mutta sitä on käytetty myös tärkeissä sovelluksissa Yhdysvaltain laivaston, Yhdysvaltain ilmavoimien, CIA:n (vahvistamaton tieto), useiden kansallisten turvallisuusvirastojen toimesta.[3] Nieminen, Sironen 5
3 Projektin aikataulun seuranta Projekti ositettiin suunnitteluvaiheessa seuraaviin vaiheisiin: 1. IRC / OSGi / Bot / Bundle teoriaan tutustuminen 2. Projektisuunnitelman luonti 3. Suunnitelman esitys 4. IRC:n harjoittelu 5. IRC-Bottiin tutustuminen 6. Knopflerfish-alustaan tutustuminen 7. IRC-kanavan luonti 8. Alkeellisen IRC-botin luonti 9. Simulaattorin rajapintaan tutustuminen 10. Java sovelluksen luonti 11. Väliraportointi 12. Lisäominaisuudet 13. Dokumentointi 14. Loppuraportointi Kuvassa 2 esitetään projektityön jana-aikataulutusuunnitelma ja aikataulun toteuteuma. Kuvassa sinisellä on merkitty suunnitelma sekä punaisella aikataulun toteutuma. Projekti oli alkuvaiheessa aikataulussaan, mutta vaiheessa 8 (alkeellisen IRC-Botin luonti) kohdattiin teknisiä vaikeuksia, jotka aiheuttivat aikataulussa jälkeen jääntiä. Lisäksi opiskelun tuoma muu kuorma rajoitti projektiin kohdistattavia resursseja. Väliraporttointiin (vaihe 11) mennessä tekniset ongelmat olivat voitettu ja projekti eteni kirien aikataulua. Lopulta projekti oli valmis suunnitellussa aikataulussa. Loppuraportointi toteutettiin viikon myöhässä sairastapuksen vuoksi. Kuva 2 Projektin aikataulutus. Nieminen, Sironen 6
4 Kustannusten seuranta Työ oli ohjelmointityö, eikä työstä koitunut muita kustannuksia kuin resurssien tunnit. Ohjelmointiin ei tarvittu maksullisia lisenssejä. Budjetoituina kustannuksina oli 4 opintopistettä/henkilö (4*26,7h = 106,8h). Kuvassa 3 on esitettynä sekä budjetoidut että toteutuneet kustannukset. Kuvaajat ovat jana-aikatauluna mukaiset kumulatiiviset tunnit. Tehdyt jäivät projektin alkuvaiheessa jälkeen suunnitellusta samoista ongelmista johtuen kuin aikataulukin jälkeen jääminen. Väliraporttoinnin jälkeen työssä kirittiin aikataulua ja kustannukset olivat lopulta 124h/henkilö. Tämä on n. 20h enemmän kuin budjetoitu. 140 Projektin tunnit 120 h/henkilö 100 80 60 Suunniteltu kumulatiivinen Toteutunut kumulatiivinen 40 20 0 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 Viikko Kuva 3 Projektin budjetoidut ja toteutuneet kustannukset. Nieminen, Sironen 7
5 Projektin tulokset Projektin tuloksena on bundle, jota ajetaan OSGi alustassa. Bundlen avulla IRC:n kautta voi ohjata kahvinkeitintä sallitut käyttäjät. Bundle koostuu luodusta neljästä javaluokasta, PircBot:n lähdekoodista, OSGi framework:sta, Coffee Maker bundlesta. Luodut neljä Java-luokkaa ovat BotActivator, CoffeeBot, BotListener ja UserList. CoffeeBot luokan pohjana on käytetty Jibble:n PircBot luokkaa. Bundlen käynnistettäessä luodaan uusi CoffeeBot, joka liitetään halutulle serverille ja kanavalle IRC:iin. CoffeeBot kommukoi IRC-kanavan ja Coffee Maker Bundlen välillä. Kun Coffee Maker palvelu on saatavilla (käynnissä samassa OSGi-alustassa) lisätään sille CoffeeListener luokan muokainen BotListener. Tämän avulla Coffee Maker:ltä tulevat viestit voidaan ohjata IRC-kanavalle. BotActivator luokka sisältää ServiceListenerin, joka kuuntelee OSGi-alustaa. Kun Coffee Maker bundle tulee jälleen ajoon, osataan tämän avulla lisätä sille BotListener. Kun Coffee Maker bundle on ajossa, luodaan CoffeeBot:lle CoffeeService, jonka avulla voidaan Coffee Maker bundlen komentoja käyttää CoffeeBot:lla. CoffeeBot reagoi jokaiseen kanavalle tehtyyn viestiin. Jos viesti alkaa!-merkillä, tutkii CoffeeBot viestin sisällön, muuten se ei vastaa mitään. CoffeeBot osaa kertoa häntä kutsuvalle ohjeet, kuinka käyttää CoffeeBot:a. Komennot, jotka CoffeeBot:lla on, ovat!order,! last,!cmonline,!botonline,!listusers,!adduser,!removeuser ja!help. CoffeeBot havaitsee, jos se menettää yhteyden. Parametreillä aseteltavissa yhteyden uudelleen muodostus. Oletusparametriksi sovittiin että CoffeeBot yrittää viikon ajan 5 minuutin välein muodostaa yhteyttä uudelleen. Lisäominaisuuksina toteutettiin käyttäjä rekisterin ylläpito IRC:n kautta. Rekisteri on teksitiedosto, jossa annettu sallittujen käyttäjien IRC-nick ja IRC-login. Bundlea käynnistettäessä, luetaan tiedosto ja tiedostoa päivitetään käyttäjiä lisättäessä tai poistettaessa. Luotu sovellus on kommentoitu ja siitä on muodostettu myös Javadoc:t. Liitteissä 1-8 on esitettynä luodut Java-luokat sekä Javadoc:t. Nieminen, Sironen 8
6 Bundlen käyttö Ennen bundlen käyttöä tulee sovelluksesta asettaa muutama parametri halutuiksi. Seuraavassa on esitelty ohjeet kuinka käytät bundlea. 1. Aseta java luokkaan BotActivator riveille 20, 21, 22 haluttu IRC-kanava, botin nimi sekä serveri. 2. Aseta käyttäjätiedosto haluttuun kansioon ja aseta luokkaan UsersList riville 19 parametriksi FileName tiedoston polku ja nimi. Tiedostossa sallitut käyttäjät tulee olla jokainen omalla rivillään muodossa: Nick,n=Login. Esim jos nick on Matti ja login on Meikäläinen, tulee se olla muodossa: Matti,n=Meikäläinen 3. Tarvittessa vaihda luokkaan CoffeeBot riveille 36 ja 37 parametrit kuinka kauan ja kuinka usein botti yrittää uudelleen yhtettä jos se on menetetty. Parametri WaitTime on millisekunneissa. 4. Jos CoffeeBot bundlen kahvinkeiton rajoituksia (määrä ja vahvuus) ei haluta olvan käytössä ja käytettään vain Coffee Maker bundlen rajoituksia, niin aseta luokkaan CoffeeBot riveille 208 211 parametrit pois alueesta. Eli alarajat nollaan ja ylärajat 9999. Nieminen, Sironen 9
5. Tämän jälkeen käännä projekti uudeksi bundleksi ajamalla build.xml Ant:na. Luotu bundle löytyy projektin out-kansiosta. Kuva 4 Projektin kääntäminen. 6. Asenna luotu bundle OSGi-alustaan ja käynnistä se. Mikäli CoffeeBot ei onnistu luomaan yhteyttä käynnistyksessä ei bundle käynnisty. Tutki miksi yhteyden muodostus IRC:iin ei onnistu ja kun yhteyden muodostus on mahdollista käynnistä CoffeeBot bundle uudelleen. CoffeeBot bundle ei myöskään käynnisty jos käyttäjälistaa ei löydy annetulla nimellä annetusta polusta tai se on tyhjä. Varmista tällöin käyttäjälistan olemassa olo ja sisältö. Nieminen, Sironen 10
Kuva 5 OSGi:n käyttöliittymä. Nieminen, Sironen 11
7 CoffeeBotin käyttö CoffeeBot on jatkuvasti kanavalle jolle se on asetettu. Kun joku liittyy kanavalle, viestittää CoffeeBot kanavalle tervehdyksen. Tervehdyksessä on ohjeet kuinka CoffeeBot:n käytössä pääsee eteenpäin. CoffeeBot:lla on olemassa seuraavat komennot:!order,! last,!cmonline,!botonline,!listusers,!adduser,!removeuser ja!help. Komento kirjoitetaan kanavalle. Komento alkaa aina!-merkillä. Muihin kanaville tulleisiin viesteihin CoffeeBot ei reagoi.!order -komennolla tilataan kahvia. Komento tulee olla muodossa!order määrä strength. Esim!order 10 100. Jos määrä tai vahvuus ei ole sallituissa rajoissa, ei tilaus onnistu.!last -komennolla voit selvittää kuinka kauan sitten viimeisin kahvinkeitto on valmistunut.!cmonline -komennolla voit selvittää kuinka kauan Coffee Maker palvelu on ollut saatavilla.!botonline -komennolla voit selvittää kuinka kauan CoffeeBot on ollut kanavalla.!listusers +komennolla voi selvittää ketkä ovat sallittuja käyttäjiä.!adduser -komennolla voivat sallitut käyttäjät lisätä uusia käyttäjiä. Komento tulee olla muodossa:!adduser nick login.!removeuser -komennolla voivat sallitut käyttäjät poistaa toisia käyttäjiä. Komento tulee olla muodossa:!removeuser nick login.!help -komennolla saadaan selville olemassa olevat komennot. Jos komennosta halutaan lisäapuja annetaan komento!help parametrin kanssa. Paramertrina toimii haluttu komneto. Esim!help order. Nieminen, Sironen 12
8 Projektin analysointi Työn taivoitteet saavutettiin ja myös suunnitellut lisäominaisuudet toteutettiin, joten työ oli onnistunut. Projektissa esiintyi muiden opiskeluiden kuormasta johtuvaa aikataulullista muutosta, mutta työ oli valmis sovittuna päivämääränä, tosin aikaa käytettiin hieman budjetoitua enemmän. Loppuraportin jättäminen viivästyi kahdella päivällä sairastapauksen myötä. Kaikki tämä ajankäyttö on helppo havaita, koska ylläpidimme projektin kulkua seuraavaa päiväkirjaa (liite 9), josta työn eri osissa kulutettu aika on helppo nähdä. Työssä pidettiin tiiviisti yhteyttä asiakkaaseen, jotta saavutettiin molempia osapuolia tyydyttävä tulos. Projektin suunnitteluvaiheessa luodun riskianalyysin mukaisiin riskeihin (kuva 6) ei muuten törmätty kuin edellä mainitut muu opiskelu kuorma sekä sairastapaus. Kuva 6 Riskien todennäköisyys ja vaikutus Nieminen, Sironen 13
9 Yhteenveto Työssä toteutettiin kahvinkeittimen ohjaukseen tarkoitettu IRC-botti, joka mahdollistaa kahvin tilauksen Automaatiotekniikan laitoksen kahvihuoneen kahvinkeittimestä IRC-kanavalla annettavien komentojen avulla. IRC-kanavalla ollessa on mahdollista tilata kahvia ilman aiempaa kokemusta, koska kanavalla päivystävä botti antaa tilaamiseen vaadittavat ohjeet. Työ koostui pitkälti Java koodaamisesta ja valmiiden ohjelmakoodin osien yhteen liittämisestä, jotta aikaansaatiin yksi kokonainen sovellus CoffeeBot bundle, joka kommunikoi laitoksella kahvinkeitintä ohjaavan valmiina olleen CofeeMaker bundlen kanssa. Suurin viivästys suunniteltuun ajankäyttöön ja työllistykseen aiheutui yksinkertaisen PircBotin saamisesta pyörimään Osgi-alustalla. Tämä johtui osin muiden opiskeluiden aiheuttamasta kuormasta, koska ne keskeyttivät tekemisen ja aiheuttivat näin ollen asioiden uudelleen opettelua. Lisäksi merkittävä syy oli Java ohjelmointi taitojen puutteellisuudessa, etenkin luokkien yhteenliittämisen taidot. Työn edetessä ohjelmointitaidot kehittyivät ja ohjelmoinnista tuli helpompaa. Työn loppupuolella esiintynyt sairastelun yhdistettynä muiden kurssien aiheuttamaan rasitukseen aiheutti projektimme demoaminen siirtämistä yhdellä viikolla. Aikaansaamamme bundle toteutti kaikki työssä vaaditut ominaisuudet ja lisätavoitteet, joten työ oli onnistunut. Saimme toimivan bundlen valmiiksi sovittuun päivämäärään mennessä, joten pysyimme myös aikataulussa. Nieminen, Sironen 14
LÄHTEET 1. http://fi.wikipedia.org/wiki/irc 2. http://en.wikipedia.org/wiki/osgi 3. http://www.jibble.org/pircbot.php Nieminen, Sironen 15