Package: kb-controller
Coding Pirates Kuglebane controllerControlleres er lavet tilCoding Pirates Viborg/Bjerringbros kuglebane-projekt i forårssæsonen 2023.Controlleren kan modtage et (simpelt) serielt signal med en kommando - f.eks. fra en fra micro:bit.Ud fra den modtagne kommando sender controlleren et request tilkuglebane centralenog sender efterfølgende et svar tilbage til micro:bit'en.Når controlleren starter op (se afsnit herunder) startes en tråd der pollerkuglebane centralenfor at høre om der er kommet events til den kuglebane controlleren er tilknyttet.Coding Pirates Kuglebane controllerInstallation af kuglebane-controllerenStart kuglebane controllerenKonfiguration af micro:bit og kuglebane-centralForbinde micro:bit til controllerenLogin med API bruger ved opstartController initialiseres ved opstartHentning af beskeder til kuglebanen i baggrundenLogning af kommunikation i konsollenKommandoer der kan sendes til controllerenKommando:init:<<bane_id>>Kommando:send:<<til_bane_id>>Kommando:eventsKommando:popKommando:pop:<<event_id>>ERROR: ukent kommandoMicro:bit emulatorEksempelkode til micro:bit'enFinde den port micro:bit'en kommunikerer påLinux (Pi)Installere screen på UbuntuMacInstallation af kuglebane-controllerenDet anbefales at installere controlleren i et virtuelt miljø.Lav en mappe, hvor du vil have controlleren installeretStart en kommandoprompt/Terminal og gå ind mappenLav et virtuelt environment inde i mappen ved at skrive: \python -m venv venvder kan godt gå lidt tid, før det er oprettetAktiver “venv” med:activateeller (Windows): \venv\Scripts\activateDu kan se at det virtuelle miljø er aktiveret, når det står (venv) forrest i kammondo-prompten - f.eks.:\(venv) kuglebane-controller $Installer kuglebane controlleren med pippip intall kb-controllerHusk at installere Python først :-)Start kuglebane controllerenDenne kan startes fra et aktiveretvenv:python venv/lib/python3.7/site-packages/kb_controller/controller.pyBemærk:i Windows, ser det typisk sådan ud:python venv\Lib\site-packages\kb_controller\controller.pyeller via Python medkb_controller.controller.start()F.eks.:>>>fromkb_controllerimportcontroller>>>controller.start()eller fra source filen (hvis koden er klonet fra Github):python src/kb_controller/controller.pyKonfiguration af micro:bit og kuglebane-centralFørste gang controlleren startes oprettes enkbc-config.inikonfigurationsfil, hvor port-angivelse til micro:bit'en, url'en til kuglebanecentralen og polling-intervallet til kuglebanecentralen angives.Der kan være forskllige konfigurationer, afhængigt af om micro:bit'en emuleres og om man bruger en lokal version af kuglebane-centralen eller ej. Dette styres med disse to flag i konfig-filen:is_production = True eller False
is_emulator = True eller FalseSom standard er controlleren sat op til at brugekuglebane centralender ligger "i skyen" (påhttps://kuglebane.pythonanywhere.com) og er sat til at spørge hvert minut (polling_interval=60) om der er beskeder til den kuglebane, controlleren hører til.Tilret konfigurationsfilen, så den passer med hvilken seriel port micro:bit'en er forbundet til (se næste afnsit).Forbinde micro:bit til controllerenControlleren forventer at der sidder en enhed på den serielle port - f.eks. en micro:bit (eller emulatoren - se herunder).Hvis der ikke kan skabes forbindelse på angivne serielle port stopper controlleren med en fejl og lister de porte der lige nu er tilgængelige.Hvis du tilslutter micro:bit'en (via USB kablet), så hold øje med den port der hedder noget med "USB" og/eller "microbit", f.eks.:-------------------------------------
  FEJL under etablering af forbindelse!
  (2, "could not open port /dev/cu.usbmodem1410: [Errno 2] No such file or directory:")

  Tjek om microbit'en er forbundet, eller om portnavnet er korrekt.

  Tilgængelige porte:
  /dev/cu.BLTH - n/a
  /dev/cu.Bluetooth-Incoming-Port - n/a
  /dev/cu.usbmodem14102 - BBC micro:bit CMSIS-DAP - mbed Serial Port      <--
  -------------------------------------for Windows, vil det være en afCOMportene (f.eks.COM4)Åbn filenkbc-config.iniog ret værdien for porten i[MICROBIT]afsnittet, f.eks:[MICROBIT]
  tty_name = COM4Login med API bruger ved opstartNår den serielle port er forbundet, skal api-bruger og adgangskode angives. API brugeren, er den bruger der har adgang til at lave forespørgsler tilkuglebane centralen(se evt. ogsåhttps://kuglebane.pythonanywhere.com)Controller initialiseres ved opstartNår controlleren er startet op skriver den ud i konsollen hvilken afdeling den hører til og hvilke kommandoer man kan sende til den.Herefter venter den på at der sendes eninitkommando fra microbit'en, der fortæller hvilken kuglebane den tilhører.Dette gøres ved at få micro:bit'en til at sende eninit:<<ID>>kommando, hvorIDer kuglebanens ID (en oversigt over kuglebane-ID'er kan ses påkuglebane centralen-https://kuglebane.pythonanywhere.com/tracks/).I eksempelkoden til micro:bit'en prøver den at sende eninitkommando når dnstarter - og ellers når man ryster micro:bit'en.Se desuden afsnittetKommandoer der kan sendes til controllerenherunder.Når controlleren har fået at vide hilken kuglebane den tilhører skrives listen af kuglebaner per afdeling ud i konsollen, f.eks.:============================================================
    M I C R O : B I T   S E R I A L   C O N T R O L L E R
  ============================================================
  Kuglebane central........: https://kuglebane.pythonanywhere.com/
  API bruger...............: CpvApi
  Controller for afdeling..: CPV
  -----------------------------------------------------------

  [2023-03-19 22:56:16] m:b <<< init:1

  -----------------------------------------------------------
  Tilgængelige kuglebaner:

    CPV (egen afdeling):
    -------------------------------------
      1 - Gargamel
      2 - Smølfine    [CONTROLLER]
    -------------------------------------

    CPB:
      3 - Gammelsmølf
      4 - Stærkesmølf

    CPS:
      5 - Astrosmølf
  -----------------------------------------------------------

  [2023-03-19 22:56:16] m:b >>> OK:INIT:1Controlleren herover er placeret i afdelingCPVog tilsluttet kuglebaneSmølfinemed ID = 2.Hentning af beskeder til kuglebanen i baggrundenI eksempelkoden til micro:bit'en sendes der eneventskommando til controlleren hvert minut.Hvis der er en eller flere events, skrives dette ud i konsollen.Hvis der f.eks. er modtaget én besked fra bane-ID 1 (i CPV) til bane-ID 5 (i CPS):[2023-04-10 18:14:58] m:b <<< events

Henter events for kuglebanen
-----------------------------
[2023-04-10 18:14:58] KB-CENTRAL >>> http://kuglebane.pythonanywhere.com/api/events/5  [GET]
[2023-04-10 18:14:59] KB-CENTRAL <<< Response status OK!


 Event id: 9 - kommando: START
   - afsendt: 10-04-2023 16:12:07.974412
   - fra CPV, bane 1 (Gammelsmølf)


Antal beskeder modtaget til bane-ID: 5 = 1
[2023-04-10 18:14:59] m:b >>> OK:EVENTS-TRACK:1:1BEMÆRK: Dette fortæller kun OM der er beskeder. Det er efterfølgende op til micro:bit'en at hente en besked.Man henter en besked ved at sendepopkommandoen til controlleren. Dette vil hente den ældste besked, der er sendt (altså den første besked), hvorefter denne slettes frakuglebane centralen.Når beskeden er "poppet" uden fejl, kan micro:bit'en gøre noget med den - hvilket typisk vil være at starte kuglen. :-)Logning af kommunikation i konsollenGenerelt skrives al kommunikation ud i konsollen. Ud over tidsstemplet, benyttes der disse præfiks:m:b >>>besked sendt TIL micro:bitm:b <<<besked modtaget FRA micro:bitKB-CENTRAL >>>request send TILkuglebane centralenKB-CENTRAL <<<response modtaget FRAkuglebane centralenSå hvis der opstår kommunikationsfejl et eller andetr sted, kan man forsøge at spore det ved at kigge i konsollen.Kommandoer der kan sendes til controllerenHver gang en kommando modtages vil controlleren svare på formen:STATUS:KOMMANDO:SVARHvor:STATUS =OKellerERRORKOMMANDO = den kommando der er modtagetSVAR = forOKer dette svaret på kommandoen og forERRORer dette noget yderligere fejlinformationSvarene er uddybet herunder.P.t. understøttes disse kommandoer:Kommando:init:<<bane_id>>Initialisere controlleren til den kuglebane (med id=bane_id), som controlleren er tilknyttet.Svar fra controller:OK:INIT:<<bane_id>>Svar hvis der opstår en fejl::ERROR:INIT:<<bane_id>>:<<eventuel fejlbesked>>Kommando:send:<<til_bane_id>>Sender enSTARTevent til bane<<til_bane_id>>Svar fra controller:OK:SEND:<<fra-bane_id>>:<<til-bane_id>>Hvorfra-bane_ider ID på den kuglebane, som controllren selv er tilsluttet.Svar hvis der opstår en fejl::ERROR:SEND:<<til_bane_id>>:<<eventuel fejlbesked>>Kommando:eventsHenter alle events der er sendt til den kuglebane controlleren er tilsluttet (dvs. kuglebanen man har angivet fra micro:bit'en medinitkommandoen)Svar fra controller:OK:EVENTS-TRACK:<<bane_id>>:<<antal-events>>bane_id= den kuglebane controlleren er tilnkyttet (dvs. det ID der er modtaget fra micro:bit'en medinitkommandoen)antal_events= antallet af beskeder der er modtaget til denne kuglebaneBeærk: i svaret ses bare antallet af events. Kig på konsollen for controlleren for at se hvilke events der er modtaget.For at afvikle den første (ældste) event sendespopkommandoen.For at afvikle en bestemt event sendespop:<<event_id>>kommandoenSvar hvis der opstår en fejl::ERROR:EVENTS:<<eventuel fejlbesked>>Kommando:popFjerner den ældste event frakuglebane centralenog sender kommando-id fra eventen til enheden (f.eks. en micro:bit) på den serielle port, så denne kan udføre kommandoen (f.eks.STARTfor at starte en kugle) på kuglebanen den er tilnkyttet.Desuden medsendes hvilken afdeling og kuglebane eventen blev afsendt fra.Svar fra controller:OK:POP:<<fra_afdeling>>:<<fra-bane_id>>:<<kommando_id>>EKSEMPEL: ældste besked er etSTARTevent afsendt fra afdelingCPBkuglebane nr.2:OK:POP:CPB:2:STARTSvar hvis der opstår en fejl::ERROR:POP:<<eventuel fejlbesked>>Kommando:pop:<<event_id>>ENDNU IKKE IMPLEMENTERET!Samme sompopmen med et specifikt<<event_id>>i stedet for den ældste event.Svar fra controller:OK:POP:event_id:kommando_id- f.eks.OK:POP:6:STARTERROR: ukent kommandoHvis der modtages ne kommando, der ikke er en af ovenstående, sendes denne fejl:ERROR:unknown-commandHvilket også vil være tilfældet, hvis den kommando der sendes fra micro:bit'en af en eller anden årsag bliver korrupt (f.eks. pga. støj på kablet el.l.).Man kan derfor overveje at lade micro:bit'en forsøge igen et par gange, hvis den modtager et fejlsvar.Micro:bit emulatorP.T. IKKE UNDERSTØTTET I WINDOWS!Medubit_emulator.start(<<track_id>>)startes en simpel emulator, hvor man kan emulere de tekst kommandoer der sendes fra f.eks. en micro:bit der er forbundet serielt til controlleren.Emulatoren defaulter til track-id=1. Dette skal sættes til det ID der passer med en kuglebane i den forening, controlleren er konfigureret til.For at sætte emulatoren til at "lege" kugelbane 3, sættestrack_id=3i start parameteren, f.eks:>>>fromkb_controllerimportubitemulator>>>ubitemulator.start(3)eller fra et aktiveretvenv:python venv/lib/python3.7/site-packages/kb_controller/ubitemulator.py 3eller (hvis koden er klonet fra Github):python src/kb_controller/ubitemulator.py 3Når emulatoren starter, skriver den hvilken seriel port den er startet på og hvilket track ID den er startet op med, f.eks.:=============================
     micro:bit emulator
=============================

Brug denne port på controlleren:
--------------------------------

/dev/ttys006

--------------------------------

micro:bit track-ID: 3

Venter på controller...Og den venter nu på eninitforespørgsel fra controlleren, som emulatoren svarer på. Herefter kan man sende en vilkårlig kommando til controlleren.--------------------------------

micro:bit track-ID: 1

Venter på controller...
Controller forbundet.
Sender bane-ID "3" til controller
--> init:1

<-- OK:INIT:3
Emulator klar - skriv kommando og tryk <Enter>

Skriv kommando:Eksempelkode til micro:bit'enEt eksempel, hvor micro:bit'en kan modtage og sende kan ses ihttps://github.com/Coding-Pirates-Viborg/microbit-controllerFinde den port micro:bit'en kommunikerer påLinux (Pi)Plug in the micro:bit and open a new terminal window.Typing dmesg | tail will shows you which /dev/ node the micro:bit was assigned (e.g. /dev/ttyACM0).UBUNTU: dmesg | grep ttyType sudo screen /dev/tty0 115200, replacing the number with the number you found in the previous step. You may need to install the screen program if you don't already have it.To exit, press Ctrl-A then Ctrl-D.Eks på tty for micro:bit’en: ttyACM0: USB ACM deviceInstallere screen på Ubuntusudo apt install screenMacPlug in the micro:bit and open a new terminal window.Typels /dev/cu.\*to get a list of connected serial devices; one of them will look like /dev/cu.usbmodem1422 (the exact number depends on your computer).Typescreen /dev/cu.usbmodem1422 115200, replacing the 'usbmodem' number with the number you found in the previous step. This will open the micro:bit's serial output and show all messages received from the device.To exit, press Ctrl-A then Ctrl-D.