Projekti: Onnenpyörä pikkujouluihin

Pikkujoulukauden lähestyessä tuli tarvetta kehitellä ohjelmaa työpaikan pikkujouluihin.

Yhtenä ideana oli Onnenpyörä -projekti: onnenpyörä esitetään näytöllä selainsovelluksena ja ohjaus tapahtuisi erillisellä ”boksilla” eli ESP32 -pohjaisella laitteistolla, joka olisi koteloitu hienosti. Laitteessa olisi erilaisia valoefektejä sekä näyttävä onnenpyörän käynnistyspainike.

Laitteiston osalta tavoitteena oli täysi langattomuus, jotta ohjausboksi voidaan sijoittaa joustavasti. Tarvittaessa boksi voitaisiin sijoittaa vaikka siten että onnenpyörä esitetään valkokankaalla videotykin kautta ja ohjaus on huoneen toisessa reunassa.

Tässä artikkelissa esitellään Onnenpyörä -projektia!

Koodaustyökalun valinta

Tässäkin projektissa käytin edellisissä blogipostauksissa mainittua agenttisen ohjelmakehityksen työkalua Cline. Asensin siitä CLI-version, jolloin koodaus on nopeampaa ja itsenäisempää kuin IDE-pluginilla.

Olen ollut erittäin tyytyväinen Clineen ja minulla on tilattuna kuukausiveloitteinen ClinePass-tilaus joka maksaa noin 10 dollaria kuukaudessa. Tilauksen kautta voi käyttää monenlaisia AI-malleja, mutta olen käyttänyt paljon DeepSeek v4.1 Flash -mallia. Se on taitava ja itsenäinen koodaamaan. DeepSeekin käyttö on minulle käytännössä ”ilmaista” ClinePass -tilauksen ansiosta eli minulla ei ole huolia krediittien loppumisesta kesken.

Teknologiavalintoja

Kuten yllä todettiin, pääteknologiat oli valittu melko nopeasti: käyttöliittymä toimisi selaimessa ja ohjaus olisi ESP32 -pohjaisen laitteiston kautta.

Frontend-teknologiaksi valitsin Reactin, jota itse käytän frontissa eniten.

Koska kokonaisuuteen tulisi frontendin ja laitteiston integraatio, tarvittiin jonkinlainen kevyt ”backend” tai oikeammin kevyt ohjauslogiikka. Laitteen pitää minimissään pystyä lähettämään komento ”käynnistä”. Lisäksi laitteella on tarve seurata onnenpyörän tilaa jotta laitteen valoja ja muuta logiikkaa voidaan ohjata reaaliaikaisen tilanteen mukaisesti. Frontendin on tarpeen seurata käynnistyskomentoja ja lisäksi ilmoittaa pyörän tilamuutokset backendiin. Onnenpyörän voi käynnistää myös suoraan selaimesta klikkaamalla. Tilaton ratkaisu ei siis ole riittävä, koska molemmat osapuolet tarvitsevat reaaliaikaisen tilannetiedon.

Olen käyttänyt projekteissani kustannussyistä paljon AWS:n serverless-ratkaisuja. Niinpä ohjasin Clineä suunnittelemaan backend-osuuden AWS Lambda-pohjaiseksi.

Tilanhallintaan tarvittiin kevyt ratkaisu ja DeepSeek ehdotti kevyttä DynamoDB–tietokantaratkaisua ja sehän kuulosti oikein hyvältä: DynamoDB on kevyt, erittäin halpa ja serverless-ratkaisuna huoleton valinta.

Infra-ratkaisuna pyysin käyttämään CDK:ta, josta on tullut minulle luottotyökalu AWS-infran hallintaan.

Frontend Reactilla

Projektin toteutus lähti käyntiin MVP:llä: toteutetaan alkuun pelkkä React-sovellus jota ohjataan selaimessa hiiren avulla.

React-sovelluksen tekemiseen annettiin melko kevyt ohjeistus, mutta DeepSeek koodasi heti ensimmäisestä versiosta lähtien varsin näyttävän toteutuksen: onnenpyörän sektorit olivat hienosti väritettyjä ja pyörässä oli ”viisari” kuten oikeassakin Onnenpyörässä.

Kuva: DeepSeekin suunnittelema värimaailma

Pyysin heti aluksi koodaamaan näytölle mukaan myös valintakomponentin, jolla voi valita sektorien määrän. Ensimmäisessä versiossa oli heti mukana myös naksahdusäänet onnenpyörän pyöriessä.

Satunnaisuus toteutettiin siten, että pyörä pyörii ensin satunnaisen ajan täysillä kierroksilla ja pyöriminen hidastuu sen jälkeen pysähdykseen asti.

MVP:ssä onnenpyörässä oli vain numeroidut sektorit. Melko nopeasti lisättiin kuitenkin kaksi voittosektoria: numeroidut osiot ovat ”ei voittoa” -sektoreita ja kaksi numeroimatonta sektoria ovat voittosektoreita. Voittosektoreille lisättiin myös hauska kuva, joka pyörii pyörän mukana.

Muutamia asioita piti korjata ensimmäisen toteutuksen jäljiltä: pyörän nastojen lukumäärä ei ensin vastannut sektorien määrää, pyörän keskiön ja ulkoreunan renderöinti ei toiminut kunnolla, käyttöliittymässä oli turhia tekstejä. Muutamalla lisäpromptilla asiat kuitenkin korjaantuivat.

Teknisesti kaikki piirto tapahtuu yhdelle canvas-elementille. Heti alussa logiikka erotettiin renderöinnistä, jolloin koodi on testattavissa komentoriviltä ilman selainta. DeepSeek koodasi testit mukaan heti ensimmäiseen committiin.

Kuva: Onnenpyörän ulkoasu

Kevyt backend

Kun pyörän toiminta ruudulla alkoi näyttämään jo hyvältä, lisättiin seuraavaksi etäohjauksen mahdollistava backend-toteutus.

Rajapinta on pelkkiä GET-kutsuja (tai OPTIONS CORS:ia varten):

KutsuMerkitys
GET /registerPyörä rekisteröityy taustan kuuntelijaksi; vastaus kertoo viimeisimmän käskyn ajan, jotta vanha käsky ei laukea heti
GET /status?since=<ms>&spinning=0|1&clicksPerSecond=<n>Kysely + heartbeat; since on vesileima (viimeksi nähty käsky)
GET /startKäynnistyskäsky (esim. laitteen nappi)
GET /startedPyörä ilmoittaa: pyöräytys alkoi
GET /stopped?won=0|1Pyörä ilmoittaa pysähtyneensä ja tuliko voitto
GET /stateTilakysely: seis / pyorii / timeout (+ clicksPerSecond)
GET /health{ ok: true }

Koska rajapinta on julkinen, siihen toteutettiin muutamia suojaavia ominaisuuksia:

  • API Gatewayn throttling kahdella tasolla: koko API 25 req/s ja reittikohtaisesti esimerkiksi /start vain 3 req/s – nappia ei voi pommittaa.
  • Lambdaa ei voi kutsua suoraan: ei Function URLia, API Gateway saa kutsua sitä vain tämän API:n omilla reiteillä (SourceArn-rajaus).
  • Varattu konkurrenssi 10 rajaa vahingon, jos API:a kuormitetaan.
  • Reitit ovat vain lukuoperaatioita (GET/OPTIONS), ei POST/PUT/DELETE

API toteutettiin siis Lambda-funktiona. Mutta mistä frontend tietää API:n osoitteen? API:n osoite nimittäin ratkeaa vasta kun backend julkaistaan CDK:n kautta.

Ratkaisu tehtiin CDK:n avulla. Deploy koostuu kahdesta stackista: OnnenpyoraWheelApiStack ja OnnenpyoraWebStack. API-stack julkaistaan ensin, ja se tuottaa API-osoitteen, joka annetaan eteenpäin frontin julkaisuun.

Laitteiston rakentaminen

Seuraavaksi rakennettiinkin jo laitteistoa ja koodattiin sille ohjelmistoa!

Laitteisto rakennettiin Julasta hankitun puisen boksin sisälle. Tässä tapauksessa laitetta ei tarvinnut suunnitella mahdollisimman pieneen tilaan, joten kotelointi oli miellyttävää kun kerrankin kotelossa oli hyvin tilaa komponenteille! Boksi maalattiin ennen asennuksia harmaalla spray-maalilla.

Boksiin tuli päälle kolme ledikaulusta joiden sisään laitettiin keltaiset ledit. Lisäksi asennettiin iso käynnistyspainike, johon saa palamaan vihreän valon. Vihreän valon palaessa käynnistäminen on mahdollista ja pyöriessä valo sammutetaan ja painike ei tee pyörän pyöriessä mitään vaikka sitä painaisi.

Boksin kylkeen asennettiin vielä ”virtapainike”, jossa on sininen valo kun virta on kytketty. ”Virtapainike” lainausmerkeissä siksi, että oikeasti painike ei katkaise virtaa, vaan toimii ainoastaan logiikkatason kytkimenä: kun kytkin on pois päältä, wifi-yhteys sammutetaan, ledeissä ei pala valoja ja painikkeet eivät luonnollisesti tee mitään. Mutta ESP32:n virta ei katkea, koska ESP32:lle syötetään koko ajan virtaa USB-virtapankista kotelon sisällä. Virtapainikkeella voi kuitenkin säästää virtaa tarvittaessa ja onhan se hienokin!

Vihreän painikkeen polttimoksi ei riittänyt ESP32:lla ohjattu pieni ledi. Tarvittiin kunnon polttimo, jossa riittää valotehoa. Painikkeessa oli paikka T10-kantaiselle polttimolle ja siihen asennettiinkin 12V 3W polttimo.

Mutta mistä saadaan 12V jännite ja riittävä virta polttimolle? Ratkaisuksi valittiin 18650-akku ja siihen kytketty ”DC-DC buck-boost Converter module”. Muunnin muuntaa 18650 akulta tulevan 3,0–4,2 V jännitteen 12V jännitteeksi.

Kuva: DC-DC buck-boost Converter module Automatic Adjustment Step Down/Up Power Voltage

Lisäksi tarvittiin komponentti, jolla 12V jännitteen pystyy katkaisemaan ja kytkemään päälle. Tätä kokeiltiin ensin MOSFET-moduulilla, mutta valitettavasti ESP32:n 3,3V ohjausjännite ei riittänyt tämän MOSFET-moduulin ohjaukseen ja moduulin ulostulo pysyi mykkänä, vaikka kuinka yritin saada sen toimimaan.

Kuva: IRF520 MOSFET moduuli ei toiminut ESP32:n kanssa

Lopulta erinäisten mutkien kautta eräältä tuttavalta, joka on harrastanut paljon ESP32-rakentelua, löytyi ratkaisu: 3.3V ohjausjännitteellä toimiva pieni relemoduuli. Se toimikin heti kerrasta.

Kuva: 3V Relay Module with Optocoupler

Tässä vielä kuvat koko boksista:

Kuva: ohjausboksi ulkoa
Kuva: ohjausboksi sisältä

Laiteohjelmisto

Myös laitteen ohjelmisto koodattiin DeepSeek v4.1 Flash -mallilla. Raudan ohjelmointi sujui siltä aivan yhtä helposti kuin frontin ohjelmointi.

Itse tykkään käyttää ESP32 laitteen ohjelmoinnin hallintaan VS Coden PlatformIO -laajennosta. Sen kautta voi päivittää laitteelle ohjelmiston ja seurata laitteen lokeja. Toki samat asiat voi tehdä myös komentoriviltä, mutta itse tykkään operoida laitetta käyttöliittymän kautta. Cline toki ohjaa laitetta suoraan komennoilla.

Laitteen käynnistyessä se ottaa ensimmäisenä yhteyden ennalta määrättyyn WiFI-verkkoon jotta API-kutsut netin kautta tulevat mahdollisiksi. WiFi-verkkona käytetään puhelimen hotspottia, jolloin verkko on aina helposti saatavilla missä laite sitten onkaan omistajansa mukana.

Lopulta ohjausboksin logiikka on varsin yksinkertainen:

Käynnistysnappi lähettää rajapintaan GET /start.

Tilavalot kertovat, mitä voi tehdä:

Vihreä + keltaiset = pyörän voi käynnistää

Keltainen ”aalto” = onnenpyörä on käynnissä

Tila kysytään API:sta (GET /state)

Summeri piippaa hyväksytyn painalluksen merkiksi

Kuten aiemmin mainittiin: jos päävirtakytkin on OFF-asennossa, se estää toiminnan, sammuttaa tilavalot ja kytkee WiFi-radion pois.

Ensimmäinen versio luki käynnistysnappia ja teki verkkokutsut samassa loopissa. Se toimi jotenkuten, mutta lyhyt painallus saattoi hukkua kokonaan: hidas HTTP-kutsu, TLS-kättely tai WiFi-uudelleenyhdistäminen esti napin lukemisen sekunneiksi.

Korjaus oli siirtää WiFi-yhteyden hallinta, /state-kyselyt ja /start-komennot omaan FreeRTOS-tehtävään. Napin painallus alkoi toimimaan paljon paremmin.

Yhteenveto

Projekti eteni vaihe kerrallaan: MVP frontend, kevyt backend, laitteen rakentaminen ja laiteohjelmisto. Lopuksi tietysti viimeiset viilaukset ulkoasuun ja suorituskykyyn.

Olen tyytyväinen lopputulokseen: sekä frontend että laitteisto ovat hienoja!

Pidän erityisesti siitä, että ohjausboksi toimii täysin mobiilisti eikä tarvitse verkkovirtaa tai muita piuhoja toimiakseen.

Kustannusten kannalta ratkaisu on käytännössä ilmainen: serverless ja pyyntöperusteinen laskutus tarkoittavat, ettei kiinteitä kuluja synny lainkaan, vaikka laite olisi päällä.

Teknisesti opettavaisin osa oli laitteisto. ESP32:n 3.3 voltin logiikkataso ja 12 voltin polttimo eivät pelanneet yhteen ensimmäisellä yrittämällä ja toteutuksen varrella selvisi myös että hidas verkkokutsu samassa loopissa söi napin painalluksia. Kumpikin ongelma ratkesi lopulta: relemoduuli hoiti 12V jännitteen kytkemisen ja oma FreeRTOS-tehtävä auttoi painikkeen tuntumaan.