SulaJalmari/README.md

# SulaJalmari

nRF 52840 -pohjainen pöytälelu/opetustyökalu.

## Table of Contents

- [Intro](#intro)
- [Ominaisuudet](#ominaisuudet)
- [Vaatimukset](#vaatimukset)
- [Käyttö](#käyttö)
- [Ohjelmointi](#ohjelmointi)
- [Resurssit](#resurssit)

## Intro

### SulaJalmari on nRF52840-pohjainen opetustyökalu ja pöytälelu, joka on suunniteltu tarjoamaan käytännönläheistä oppimiskokemusta sulautetuista järjestelmistä ja IoT-teknologioista.

<img src="pics/Device.jpg" height=600> 


## Ominaisuudet

### Hardware: 
- 2x RGB LED (silmät)
- 8x sininen LED (jalat)
- Kiihtyvyysanturi
- Tärinämoottori
- Piippari
- Bluetooth
- USB-C

### Software:
- Bootloader
- Valmiita demo-koodeja
- Ohjelmoitavissa USB:n yli

## Vaatimukset

### Demot
Demojen ohjelmoimiseen tarvitset nRF Connect for Desktop -ohjelmointityökalun ja tästä Git-reposta löytyvien demokoodien app_signed.hex-tiedostot. Tämän jälkeen siirry kohtaan: [Ohjelmointi](#ohjelmointi)

### Kehitys
Kehitystä varten tarvitset vähintään nRF Connect SDK:n ja tästä Git-reposta löytyvät "Board"-kansion tiedostot sekä pjr.conf-tiedoston. Suositeltavaa on kuitenkin aloittaa valmiista demokoodista, jossa tulee mukana kaikki tarpeelliset tiedostot ja kyseiseen demoon räätälöity pjr.conf-tiedosto. Parhaiten pääset alkuun asentamalla "nRF Connect for VS Code" -lisäosan Visual Studio Codeen. nRF Connect for VS Code -lisäosasta pääset asentamaan vaatimukset.

![Manage SDK](pics/Manage.png)
<br>
Tarvitset toolchainin sekä SDK:n.
<br>

![Install SDK](pics/Install.png)
<br>
Valitse Install SDK/Toolchain -valikosta, ja valitse sen jälkeen versio, jonka haluat asentaa. Tämän hetkinen versio on rakennettu ja todettu toimivaksi version 2.6.1 kanssa.
<br>

![SDKVER](pics/SDKVER.png)
<br>

## Käyttö

### Aloitus

Toolchainin sekä SDK:n asentamisen jälkeen voit avata valmiin demokoodin nRF Connect for VS Code -lisäosasta.

![Open](pics/OpenExisting.png)

Sovelluksen valinnan jälkeen voit aloittaa ohjelmoinnin src-kansiosta löytyvien tiedostojen avulla.

![Files](pics/ProjectView.png)

### Valmiin sovelluksen ohjelmointi laitteelle

#### Build Configuration

Build configuration vaaditaan sovelluksen build-vaihetta varten. Build configurationin voi luoda nRF Connect -lisäosan "Applications" tai "Build Configuration" -osiosta painamalla "Add Build Configuration". Mikäli "Applications"-osiossa näkyy valmis build configuration, tai projektissa on valmiiksi olemassa "Build"-kansio etkä ole itse niitä lisännyt, poista build configuration ja kansio ennen uuden lisäämistä. Toisella laitteella lisätyt build configurationit eivät välttämättä toimi laitteellasi.

Jos noudatit kehitysvaiheen ohjeita, "Add Build Configuration" -ikkunassa painaessasi "Custom Board" -valintaa, listasta löytyy laitteelle valmiiksi luotu board-tiedosto "nrf52840_qalmari".

![Build](pics/Build.png)

Painamalla "Build Configuration" -painiketta lisäät build configurationin projektiisi. Tämän jälkeen sen tulisi löytyä "Applications" -ikkunasta nRF Connect -lisäosasta.

#### Build

Jos et käyttänyt valmista demokoodia ohjelmoinnin pohjana, varmista pjr.conf-tiedoston sisältö. Laitteen bootloader vaatii ohjelmoidessaan tietyn tunnisteen, jonka Zephyr kirjoittaa app_signed.hex-tiedostoon automaattisesti vain, jos pjr.conf-tiedostosta löytyy rivi: 
```
CONFIG_BOOTLOADER_MCUBOOT=y
```
Ilman tätä riviä Zephyr ei luo app_signed.hex-tiedostoa, eikä laitetta voi ohjelmoida USB:n yli.

Varmista myös että projektin sisältä lyötyy "child_image" kansio, mikäli kansiota ei löydy, luo se itse ja lisää sen sisälle "mcuboot.conf" niminen tiedosto, ja kirjoita sen sisälle rivi:
```
CONFIG_PM_PARTITION_SIZE_MCUBOOT=0x12000
```

![Build](pics/child_image.png)


Tämän jälkeen voit käyttää lisäosan "Actions"-osion "Build" -valintaa, jonka jälkeen projektikansion polkuun luodaan tarvittava .hex-tiedosto:
```
main_project/build/zephyr/app_signed.hex
```

### Ohjelmointi

Ohjelmointi tapahtuu nRF Connect for Desktop -sovelluksessa, josta valitaan "Programmer" (Programmer täytyy asentaa erikseen ennen sen käyttämistä painamalla "Install" "Open"-painikkeen tilalla).

![DesktopStart](pics/Connect_start.png)

Programmer aukeaa erilliseen ikkunaan, josta vasemmassa yläkulmassa olevasta painikkeesta "SELECT DEVICE" aukeaa lista käytettävissä olevista USB-laitteista. Näistä valitaan MCUBOOT.

![Select](pics/programmer_not_chosen.png)

Laitteen valinnan jälkeen aukeaa uusi ikkuna, josta löytyy lista vaihtoehtoja. Tämän jälkeen voit navigoida app_signed.hex-tiedostoon painamalla "Add File" -painiketta. Vaihtoehtoisesti tiedoston voi vetää ja pudottaa "File Memory Layout" -kenttään.

![Selected](pics/programmer_chosen.png)

Kun tiedosto on lisätty ohjelmointityökaluun, vihreä alue ilmestyy "File Memory Layout" -kenttään visualisoimaan sovelluksen aloitusosoitetta ja sovelluksen kokoa verrattuna käytettävissä olevaan muistiin.

![Hex](pics/programmer_hex.png)

Tämän jälkeen on mahdollista ohjelmoida laite painamalla "Write" -painiketta.

![Program](pics/programmer_program.png)

Uudessa ikkunassa voit painaa taas "Write".

Jos laite ohjelmoitiin onnistuneesti, oranssin kentän tilalle ilmestyy vihreä kenttä, jossa lukee "Completed successfully in X seconds."

## Resurssit

Tästä osiosta löydät tarvittavat kehittämiseen.

Suositellut nRF lisäosat VS Codeen (nRF Terminal vanhentunut): <br>

![Ext](pics/ext.png)
- nRF Connect for Desktop:

https://www.nordicsemi.com/Products/Development-tools/nRF-Connect-for-Desktop

- nRF Command Line Tools:

https://www.nordicsemi.com/Products/Development-tools/nRF-Command-Line-Tools/Download?lang=en#infotabs


- Kconfig-komennot (pjr.conf):

https://developer.nordicsemi.com/nRF_Connect_SDK/doc/latest/kconfig/ (Offline 18/6/2024) <br>
https://docs.zephyrproject.org/latest/kconfig.html (Backup)

- Dokumentaatiot:

https://docs.nordicsemi.com/category/nrf52840-category (nRF52840) <br>
https://invensense.tdk.com/wp-content/uploads/2016/10/DS-000176-ICM-20602-v1.0.pdf (ICM-20602 kiihtyvyysanturi) <br>
https://docs.zephyrproject.org/latest/index.html (Zephyr project) <br>


- EasyEDA:

Projektin kytkentäkaaviot sekä linkki projektin EasyEDA sivulle löytyy tämän Git-repon kansiosta Hardware/Prototype2