Tekninen määrittely

IoT-alusta

AWS IoT Core

IoT-laitteen yhdistäminen AWS IoT Core:en vaatii:

Tilin AWS:n palveluihin: Set up your AWS account
IoT-käyttöoikeuksien määrittelyn ja
IoT-laitteen määrittelyn.

IoT-käyttöoikeuksien ja -laitteen määrittely onnistuu helpoiten AWS:n web-hallintakonsolissa tämän ohjeen mukaan. Ohjeen mukainen määrittely antaa IoT-laitteille oikeudet: ottaa yhteyden MQTT-välittäjään sekä tilata, lukea ja kirjoittaa MQTT-viestejä.

IoT-laitteen käyttöönottoon tarvitaan täältä:

Private key
Device certificate
Root CA certificate
Thing name

Näiden lisäksi tarvitaan vielä endpoint, joka löytyy: AWS IoT | vasemman reunan valikosta settings | Endpoint.

IoT-laite, Raspberry Pi

Käyttöjärjestelmä

Raspberry Pi:n käyttöjärjestelmäksi asennetaan Raspberry Pi OS Lite, mallista riippuen 32-bit/64-bit. 64-bit kannattaa asentaa niihin malleihin, joihin se on mahdollista. Käyttöjärjestelmän asentaminen microSD-kortille onnistuu helpoiten ohjelmalla Raspberry Pi Imager.

Raspberry Pi Imager-ohjelman valinnat asennuksessa:

Operating system:
- Raspberry Pi OS (other)
  - Raspberry Pi OS Lite (32-bit/64-bit)
Storage: (SD-kortti)
Advanced options (Ratas)
- X Enable SSH
  - X Use password authentication
- X Set username and password
  - Username: [Raspberrylle tuleva käyttäjätunnus]
  - Password: [Raspberrylle tuleva salasana]
- Configure wireless LAN (tarvittessa)
  - SSID: [Verkon nimi]
  - Password: [Verkon salasana]
  - Wireless LAN country: FI
- X Set locale settings
  - Time zone: Europe, Helsinki
  - (Keyboard layout: fi)
- Save
Write

Laitetaan SD-kortti Raspberry Pi:n korttipaikkaan ja kytketään virta. Etsitään reitittimen hallinnasta Raspberry Pi:n IP-osoite ja otetaan siihen ssh-yhteys.

ssh -l [username] [IP-osoite]

Haetaan ja asennetaan käyttöjärjestelmän päivitykset.

sudo apt-get -y update
sudo apt-get -y upgrade
sudo apt-get -y autoremove

Tarkistetaan asetukset.

sudo raspi-config

Uudelleenkäynnistetään Raspberry Pi.

sudo shutdown -r now

Yhteysohjelman kääntäminen

IoT-laitteen yhteysohjelma on aws-iot-device-client, jonka lisenssi on Apache License 2.0. Nämä ohjeet on otettu (erittäin) vapaasti soveltaen täältä.

Asennetaan tarvittavat muut ohjelmat.

sudo apt-get install build-essential libssl-dev cmake git

Tehdään yhteysohjelmalle hakemisto ja haetaan sinne lähdekoodit.

cd ~
mkdir IoT_DeviceClient
cd IoT_DeviceClient
git clone https://github.com/awslabs/aws-iot-device-client

Siirrytään lähdekoodihakemistoon

cd aws-iot-device-client

Huom! 32-bittisissä pitää ohjelman linkitykseen lisätä hakemisto atomic. Se onnistuu lisäämällä lähdekoodihakemistossa olevaan tiedostoon CMakeLists.txt rivi. (Lihavoitu, italic)

...
target_link_libraries(${DC_PROJECT_NAME} ${DEP_DC_LIBS})
target_link_libraries(${DC_PROJECT_NAME} OpenSSL::SSL)
target_link_libraries(${DC_PROJECT_NAME} OpenSSL::Crypto)
target_link_libraries(${DC_PROJECT_NAME} atomic)

# If you're linking statically against the SDK but dynamically against libraries such as OpenSSL,
...

Tottahan näin vaativasta muutoksesta on patch, joka on tehty versiolle: CMakeLists.txt / commit 56d6221. Huom. Tämä tarvitaan vain 32-bit järjestelmille!

wget http://esko.viiru.eu/CMakeLists.patch
patch CMakeLists.txt CMakeLists.patch

Kääntämisvaiheessa voidaan valita, mitä toimintoja ei oteta mukaan. Turhien toimintojen poisjättäminen pienentää (hiukan) suoritettavan tiedoston kokoa.

Available CMake flags for feature exclusion:
EXCLUDE_JOBS
EXCLUDE_DD
EXCLUDE_ST
EXCLUDE_FP
EXCLUDE_SAMPLES
EXCLUDE_PUBSUB
EXCLUDE_SHADOW
EXCLUDE_CONFIG_SHADOW
EXCLUDE_SAMPLE_SHADOW

Siirrytään build-hakemistoon ja käännetään ohjelma. Tämä sitten kestää hyvän aikaa!
Seuraavassa käännöksestä on jätetty pois kaikki muut paitsi JOBS, SAMPLES ja PUBSUB.

mkdir build
cd build
cmake ../ -DEXCLUDE_DD=ON -DEXCLUDE_ST=ON -DEXCLUDE_FP=ON -DEXCLUDE_SHADOW=ON -DEXCLUDE_CONFIG_SHADOW=ON -DEXCLUDE_SAMPLE_SHADOW=ON
cmake --build . --target aws-iot-device-client

Käännöksen onnistumisen voi alustavasti kokeilla ohjelman help-toiminnolla.

./aws-iot-device-client --help

Yhteysohjelman asetukset

Hakemistot ja tiedostot

Tehdään ohjelman hakemistoon tarvittavat alihakemistot ja määritetään niille oikeudet.

cd ~/IoT_DeviceClient
mkdir certs jobs logs mailbox
chmod 700 certs jobs
chmod 745 logs mailbox

Siirretään certifikaattitiedostot tietokoneelta IoT-laitteelle. Tietokoneen certifikaattihakemistossa pakataan certifikaatit tar-pakettiin ja lähetetään se IoT-laitteelle.

tar -cvf certs.tar [Private key] [Device certificate] [Root CA certificate]
scp certs.tar [username]@[IP-osoite]:~/IoT_DeviceClient/certs

IoT-laitteella puretaan paketti ja määritetään tiedostoille oikeudet.

cd ~/IoT_DeviceClient/certs
tar -xvf certs.tar
chmod 644 *
chmod 600 [Private key]

Huom. Yhteysohjelma on aika tarkka näiden oikeuksien kanssa, joten kannattaa olla huolellinen.

Asetukset

Ohjelman asetuksien määrittelyä varten lähdekoodihakemistossa on ohjelma setup.sh.

cd ~/IoT_DeviceClient/aws-iot-device-client
./setup.sh

Vastaillaan asetusohjelman kysymyksiin. Tässä kirjoitus-/luku-kanava on test_topic. Endpoint ja certifikaatit pitäisi löytyä kohdan: "IoT-alusta | AWS IoT Core" perusteella. (Vastaukset: lihavoitu, italic)

Do you want to interactively generate a configuration file for the AWS IoT Device Client? y/n
y
Specify AWS IoT endpoint to use:
[Endpoint]
Specify path to public PEM certificate:
/home/[user]/IoT_DeviceClient/certs/[Device certificate]
Specify path to private key:
/home/[user]/IoT_DeviceClient/certs/[Private key]
Specify path to ROOT CA certificate:
/home/[user]/IoT_DeviceClient/certs/[Root CA certificate]
Specify thing name (Also used as Client ID):
[Thing name]
Would you like to configure the logger? y/n
y
Specify desired log level: DEBUG/INFO/WARN/ERROR
DEBUG
Specify log type: STDOUT for standard output, FILE for file
FILE
Specify path to desired log file (if no path is provided, will default to /var/log/aws-iot-device-client/aws-iot-device-client.log:
/home/[user]/IoT_DeviceClient/logs/aws-iot-device-client.log
Would you like to configure the SDK logging? y/n
y
Specify desired SDK log level: TRACE/DEBUG/INFO/WARN/ERROR/FATAL
WARN
Specify path to desired SDK log file (if no path is provided, will default to /var/log/aws-iot-device-client/sdk.log:
/home/[user]/IoT_DeviceClient/logs/sdk.log
Enable Jobs feature? y/n
y
Specify absolute path to Job handler directory (if no path is provided, will default to /home/[user]/.aws-iot-device-client/jobs):
/home/[user]/IoT_DeviceClient/jobs
Enable Secure Tunneling feature? y/n
n
Enable Device Defender feature? y/n
n
Enable Fleet Provisioning feature? y/n
n
Enable Pub Sub sample feature? y/n
y
Specify a topic for the feature to publish to:
test_topic
Specify the path of a file for the feature to publish (if no path is provided, will default to /home/[user]/.aws-iot-device-client/pubsub/publish-file.txt):
/home/[user]/IoT_DeviceClient/mailbox/publish-file.txt
Specify a topic for the feature to subscribe to:
test_topic
Specify the path of a file for the feature to write to (if no path is provided, will default to /home/[user]/.aws-iot-device-client/pubsub/subscribe-file.txt):
/home/[user]/IoT_DeviceClient/mailbox/subscribe-file.txt
Enable Config Shadow feature? y/n
n
Enable Sample Shadow feature? y/n
n
Does the following configuration appear correct? If yes, configuration will be written to /home/[user]/.aws-iot-device-client/aws-iot-device-client.conf: y/n
y
Do you want to copy the sample job handlers to the specified handler directory (/home/[user]/IoT_DeviceClient/jobs)? y/n
y
Do you want to install AWS IoT Device Client as a service? y/n
n

Nyt ohjelmaa voisi kokeilla.

./build/aws-iot-device-client

Jos taivas ei peittynyt virheilmoituksiin, niin viestien kulkua voisi sitten kokeilla AWS:n ohjeen mukaan.

Jos vieläkin kaikki näyttää hyvältä, niin yhteysohjelman voisi laittaa taustapalveluksi. (service/daemon) Pysäytetään ensin yhteysohjelma (cntrl-c) ja suoritetaan sitten asetusohjelma uudelleen sudo-oikeuksin ja vastaamalla lopussa service-kyselyyn: y. Alkuosa service-kyselyyn asti samoin kuin edellä.

sudo ./setup.sh
...
Do you want to install AWS IoT Device Client as a service? y/n
y
Enter the complete directory path for the aws-iot-device-client. (Empty for default: ./build/aws-iot-device-client)
[Empty]
Enter the complete directory path for the aws-iot-device-client service file. (Empty for default: ./setup/aws-iot-device-client.service)
[Empty]
Do you want to run the AWS IoT Device Client service via Valgrind for debugging? y/n
n
Installing AWS IoT Device Client...
AWS IoT Device Client is now running! Check /var/log/aws-iot-device-client/aws-iot-device-client.log for log output.

Lisätään vielä asetus, että viesti lähtee automaattisesti, kun lähetystiedosto muuttuu. Ensin pysäytetään palvelu.

sudo systemctl stop aws-iot-device-client.service

Sitten lisätään tiedostoon /etc/.aws-iot-device-client/aws-iot-device-client.conf (ja ~/.aws-iot-device-client/aws-iot-device-client.conf) pilkku ja rivi. (lihavoitu, italic) Pilkku tulee lisättävää riviä edeltävän rivin loppuun.

sudo nano /etc/.aws-iot-device-client/aws-iot-device-client.conf
...
"samples": {
  "pub-sub": {
    "enabled": true,
    "publish-topic": "test_topic",
    "publish-file": "/home/[user]/IoT_DeviceClient/mailbox/publish-file.txt",
    "subscribe-topic": "test_topic",
    "subscribe-file": "/home/[user]/IoT_DeviceClient/mailbox/subscribe-file.txt",
    "publish-on-change": true
    }
  },
...

Sitten käynnistetään palvelu.

sudo systemctl start aws-iot-device-client.service

Nyt MQTT-viestin pitäisi lähteä automaattisesti, kun lähetystiedosto (/home/[user]/IoT_DeviceClient/mailbox/publish-file.txt) muuttuu.