chevron_left

sa.engine getting-started

2021-11-13

sa.engine Release 4.1.0

Start here

Community Edition Guides

Getting Started

These are the getting started guides for the SA Studio Community Edition.

  1. Getting started with Windows
  2. Getting started with Mac
  3. Getting started with Android
  4. Getting started with Raspberry Pi

Getting started with Windows

Introduction

In this step-by-step guide you will learn how to get started with SA Studio by using a Windows computer as an edge device.

Step 1 - Sign up

To access SA Studio Community Edition you first need to sign up, if you are not already signed up click the button below:

After signing up and verifying your email you can access sa.studio by pressing "START STUDIO", waiting for the studio environment to be started and then pressing "GO TO STUDIO".

NOTE: You can continue this guide from inside your sa.studio by going to the documentation page (1) then expanding Available Online -> streamanalyze.com and clicking Getting started (2) and then wait for the guide to be imported and loaded (3).

loading-getting-started.png

Step 2 - Download and start SA Engine on your edge device

Now that you have signed up it is time to download and start an instance of the SA Engine on your Windows machine.

1. Go to the download page.

streamanalyze-com-studio-download.png

2. Scroll down to the bottom and download sa_engine_core_win_x64.zip.

streamanalyze-com-studio-download-bottom.png

3. Extract the zip archive.

4. Open the Windows command prompt and navigate to the sa.engine\bin folder.

> cd \path\to\sa.engine\bin

5. Start SA Engine.

> sa.engine

This prints the SA Engine database image, version number and presents a prompt.

Database image: sa.engine.dmp
Release 3, v5, 64 bits
[sa.engine] 1>

Step 3 - Connect your edge device to the server

Now that you have SA Engine installed on your Windows machine it is time to start a server in the cloud and connect your local SA Engine instance to the server as an edge device.

1. Go back to the SA Studio Community Edition landing page.

streamanalyze-com-studio.png

2. Start SA Studio with the go-to-studio-button.png button. This will be your server instance.

sa-studio.png

3. Go to the "connect edge devices" page by clicking the Connect edge devices icon in the top left row.

sa-studio-connect-edges.png

4. Under Add clients or edges to the federation change the name in the client name text field from "edge" to "win-edge".

sa-studio-connect-edges-input-win-edge.png

5. Copy the large text blob in the section Connect as edge using base64 blob from within sa.engine to the clipboard and paste it into a new text file (e.g., "connect.osql").

sa-studio-connect-edges-copy-connection-blob.png

connect-blob-notepad.png

6. Go back to SA Engine in your Windows CMD prompt and execute the contents of the text file.

[sa.engine] 1> < "connect.osql";

This connects the local instance of SA Engine to the server. The local SA Engine should print a message confirming that it is awaiting queries from the server.

2021-10-18T13:57:11.212 Edge WIN-EDGE waiting for query from SERVER...

Your browser should also show your Windows machine as "WIN-EDGE" in the list of Connected edge-devices accessed under Edges in the left menu column. You might have to click the refresh icon at the top of the list for "WIN-EDGE" to show up.

sa-studio-connect-edges-edge-list.png

Step 4 - Test your setup

Now that you have added your local Windows machine as an edge device to the server it is time to test some queries.

1. Go to the OSQL editor by clicking the OSQL editor icon.

sa-studio.png

2. Open a new OSQL editor by clicking the open-new-osql-editor-button.png button.

3. Ensure that the queries will be evaluated on the server by selecting "server" in the device list at the bottom.

sa-studio-osql-editor-device-selector-server.png

4. In the editor window, write the query listening_edges();.

sa-studio-osql-editor-enter-query.png

Then run the query by pressing the Run queries icon to run the query. The result is a list of edges that are connected to the server. Your Windows machine should be present with the name "WIN-EDGE".

["WIN-EDGE"]

5. Change the device on which the queries are run by clicking device-selector.png at the bottom (next to the run query button) and select Win-edge from the list.

sa-studio-osql-editor-device-selector-win-edge.png

Now when you run a query it will execute on your Windows edge device.

6. Try executing a query on the Windows edge device by having device-selector-win-edge.png as selected device, delete the previous query from the editor window and execute the new query:

this_peerid();

This should output the string "WIN-EDGE" which is the id of your Windows edge device.

Also note that the local SA Engine instance in your Windows CMD prompt should confirm that it ran the query this_peerid().

2021-10-18T14:38:32.392 Running query 1: this_peerid();
2021-10-18T14:38:32.444 Query 1 finished

Now we have verified that your Windows machine is connected to the server, and that it can run queries retrieved from the server.

Step 5 - Accessing the microphone

Now that you have tested that you can execute queries on the Windows machine it is time to do some tests with the microphone.

Note: This step requires Java. If Java is not installed you can download and install the appropriate version from Oracle's Java Download Page

1. Test that you have your microphone working by running the following query while making some sound (ensure that you have device-selector-win-edge.png as selected device before running the query).

audio(256, 16000);

Now when you make a sound you should see some activity in the output plot.

sa-studio-osql-editor-audio-query.png

Step 6 - Build a model

Now that we have tested the microphone it is time to build a simple model that detects a specific type of sound.

1. Create a simple audio frequency detection model by running the following query (ensure that you still have device-selector-win-edge.png as selected device).

create function audio_band(Number low, Number up)
                         -> Stream of Number
    as select Stream of hz
         from Number hz, Number index, Number max, Number windowSize, 
              Number sampleRate, Vector of Number w
        where windowSize = 512
          and sampleRate = 16000
          and w in rfft(audio(windowSize, sampleRate))
          and max = max(w) 
          and w[index] = max
          and hz = index * sampleRate/windowSize  * 0.5
          and hz >= low
          and hz <= up
          and max > 0.001;

The model analyzes the audio stream in real time to detect whether it contains sound with frequencies in a given interval. To accomplish this it carries out a few steps.

  1. It transforms the audio stream into a stream of frequency spectra windows by applying the Fast Fourier Transform rfft() on each window from the raw audio() function.

  2. It finds the dominating frequency in each transformed window, i.e., the index of the strongest frequency in each spectrum.

  3. It selects only those windows where the dominating frequency is within the given frequency interval.

  4. It only emits the detected result if the strength of the signal is larger than 0.001. This is to filter out background noise.

2. Change the output selector to Line plot.

sa-studio-osql-editor-output-selector-line-plot.png

3. Run the audio_band() model with the frequency interval 80 - 400 Hz.

audio_band(80, 400);

If you make a humming sound the model should detect it and emit the frequencies. If you instead make a whistle sound, which produces frequencies significantly higher than 400 Hz, the model will ignore it and not emit anything.

sa-studio-osql-editor-audio-band-query.png

Conclusion

Congratulations! You have now developed your first model on a Windows edge device.

Where to go from here:

  • Use the documentation to learn more about OSQL and how you can build models and interact with edge devices.

Getting started with Mac

Introduction

In this step-by-step guide you will learn how to get started with SA Studio by using a Mac computer as an edge device.

Note: This guide requires Java to run. To check if you have Java installed open Terminal on your Mac and run the following command.

$ java -version

The command should print out the version number of Java if Java is installed. If Java is not installed you can download and install the appropriate version from Oracle's Java Download Page.

Step 1 - Sign up

To access SA Studio Community Edition you first need to sign up, if you are not already signed up click the button below:

After signing up and verifying your email you can access sa.studio by pressing "START STUDIO", waiting for the studio environment to be started and then pressing "GO TO STUDIO".

NOTE: You can continue this guide from inside your sa.studio by going to the documentation page (1) then expanding Available Online -> streamanalyze.com and clicking Getting started (2) and then wait for the guide to be imported and loaded (3).

loading-getting-started.png

Step 2 - Download and start SA Engine on your edge device

Now that you have signed up it is time to download and start an instance of the SA Engine on your Mac.

1. Go to the download page.

streamanalyze-com-studio-download.png

2. Scroll down to the bottom and copy the large text blob.

streamanalyze-com-studio-download-bottom.png

3. Open the Mac Terminal, paste the text from the clipboard and press return.

This downloads and starts sa.engine. The terminal should display the version number and sa.engine command prompt.

Database image: sa.engine.dmp
Release 4, v0, 64 bits
[sa.engine] 1>

Step 3 - Connect your edge device to the server

Now that you have SA Engine installed on your Mac it is time to start a server in the cloud and connect your local SA Engine instance to the server as an edge device.

1. Go back to the SA Studio Community Edition landing page.

streamanalyze-com-studio.png

2. Start SA Studio with the go-to-studio-button.png button. This will be your server instance.

sa-studio.png

3. Go to the "connect edge devices" page by clicking the Connect edge devices icon in the top left row.

sa-studio-connect-edges.png

4. Under Add clients or edges to the federation change the name in the client name text field from "edge" to "mac-edge".

sa-studio-connect-edges-input-mac-edge.png

5. Copy the large text blob in the section Connect as edge using base64 blob from within sa.engine to the clipboard, paste it into the Terminal window at the sa.engine prompt and press return.

sa-studio-connect-edges-copy-connection-blob.png

This connects the local instance of SA Engine to the server (this might take up to a minute). Once the device has connected to the server sa.engine should print a message confirming that it is awaiting queries.

...
V1JmUUtiZ2twdz09XG4tLS0tLUVORCBSU0EgUFJJVkFURSBLRVktLS0tLVxuIiwi
aXAtZ2V0dGVyIjoiaHR0cHM6Ly9zdHVkaW8uc3RyZWFtYW5hbHl6ZS5jb20vdXNl
ci9pcC9iV0ZuYm5WekxtZGxaR1JoUUhOMGNtVmhiV0Z1WVd4NWVtVXVZMjl0In0=
','mac-edge',true);

2021-11-08T17:37:17.216 Edge MAC-EDGE waiting for query from SERVER...

Your browser should also show your Mac as "MAC-EDGE" in the list of Connected edge-devices accessed under Edges in the left menu column. You might have to click the refresh icon at the top of the list for "MAC-EDGE" to show up.

sa-studio-connect-edges-edge-list.png

Step 4 - Test your setup

Now that you have added your Mac as an edge device to the server it is time to test some queries.

1. Go to the OSQL editor by clicking the OSQL editor icon.

sa-studio.png

2. Open a new OSQL editor by clicking the open-new-osql-editor-button.png button.

3. Ensure that the queries will be evaluated on the server by selecting "server" in the device list at the bottom.

sa-studio-osql-editor-device-selector-server.png

4. In the editor window, write the query listening_edges();.

sa-studio-osql-editor-enter-query.png

Then run the query by pressing the Run queries icon to run the query. The result is a list of edges that are connected to the server. Your Mac should be present with the name "MAC-EDGE".

["MAC-EDGE"]

5. Change the device on which the queries are run by clicking device-selector.png at the bottom (next to the run query button) and select Mac-edge from the list.

sa-studio-osql-editor-device-selector-mac-edge.png

Now when you run a query it will execute on your Mac.

6. Try executing a query on the Mac by having device-selector-mac-edge.png as selected device, delete the previous query from the editor window and execute the new query:

this_peerid();

This should output the string "MAC-EDGE" which is the id of your Mac.

Also note that the local SA Engine instance in your Mac Terminal prompt should confirm that it ran the query this_peerid().

2021-11-08T18:08:55.185 Running query 1: this_peerid();
2021-11-08T18:08:55.242 Query 1 finished

Now we have verified that your Mac is connected to the server, and that it can run queries retrieved from the server.

Step 5 - Accessing the microphone

Now that you have tested that you can execute queries on the Mac it is time to do some tests with the microphone.

1. Test that you have your microphone working by running the following query while making some sound (ensure that you have device-selector-mac-edge.png as selected device before running the query).

audio(256, 16000);

You might need to give Terminal permission to access the microphone. If so then simply press OK.

mac-microphone-access-permission.png

Now when you make a sound you should see some activity in the output plot.

sa-studio-osql-editor-audio-query.png

Step 6 - Build a model

Now that we have tested the microphone it is time to build a simple model that detects a specific type of sound.

1. Create a simple audio frequency detection model by running the following query (ensure that you still have device-selector-mac-edge.png as selected device).

create function audio_band(Number low, Number up)
                         -> Stream of Number
    as select Stream of hz
         from Number hz, Number index, Number max, Number windowSize, 
              Number sampleRate, Vector of Number w
        where windowSize = 512
          and sampleRate = 16000
          and w in rfft(audio(windowSize, sampleRate))
          and max = max(w) 
          and w[index] = max
          and hz = index * sampleRate/windowSize  * 0.5
          and hz >= low
          and hz <= up
          and max > 0.001;

The model analyzes the audio stream in real time to detect whether it contains sound with frequencies in a given interval. To accomplish this it carries out a few steps.

  1. It transforms the audio stream into a stream of frequency spectra windows by applying the Fast Fourier Transform rfft() on each window from the raw audio() function.

  2. It finds the dominating frequency in each transformed window, i.e., the index of the strongest frequency in each spectrum.

  3. It selects only those windows where the dominating frequency is within the given frequency interval.

  4. It only emits the detected result if the strength of the signal is larger than 0.001. This is to filter out background noise.

2. Change the output selector to Line plot.

sa-studio-osql-editor-output-selector-line-plot.png

3. Run the audio_band() model with the frequency interval 80 - 400 Hz.

audio_band(80, 400);

If you make a humming sound the model should detect it and emit the frequencies. If you instead make a whistle sound, which produces frequencies significantly higher than 400 Hz, the model will ignore it and not emit anything.

sa-studio-osql-editor-audio-band-query.png

Conclusion

Congratulations! You have now developed your first model on a Mac edge device.

Where to go from here:

  • Use the documentation to learn more about OSQL and how you can build models and interact with edge devices.

Getting started with Android

Introduction

In this step-by-step guide you will learn how to get started with SA Studio by using an Android phone as an edge device.

Step 1 - Sign up

To access SA Studio Community Edition you first need to sign up, if you are not already signed up click the button below:

After signing up and verifying your email you can access sa.studio by pressing "START STUDIO", waiting for the studio environment to be started and then pressing "GO TO STUDIO".

NOTE: You can continue this guide from inside your sa.studio by going to the documentation page (1) then expanding Available Online -> streamanalyze.com and clicking Getting started (2) and then wait for the guide to be imported and loaded (3).

loading-getting-started.png

Step 2 - Download and start the SA Edge app

Now that you have signed up it is time to download and start an instance of the SA Edege app on your Android phone.

1. Go to the download page.

streamanalyze-com-studio-download-android.png

2. Scan the QR code to download, install and open the SA Edge app. Note: To install this app from the download page you must be able to "side load" applications. Read more about side loading here.

android-app-download-qr.jpg android-app-install.jpg android-app-open.jpg

The app should say that it is not yet configured and needs a sa.studio connection. This means that the app has been installed correctly and is awaiting further instructions.

Step 3 - Connect your edge device to the server

Now that you have the SA Engine app installed on your Android phone it is time to start a server in the cloud and connect your phone the server as an edge device.

1. Go back to the SA Studio Community Edition landing page.

streamanalyze-com-studio.png

2. Start SA Studio with the go-to-studio-button.png button. This will be your server instance.

sa-studio.png

3. Go to the "connect edge devices" page by clicking the Connect edge devices icon in the top left row.

sa-studio-connect-edges.png

4. Change the name in the client name text field under Add clients or edges to the federation from "edge" to "android-edge".

sa-studio-connect-edges-input-android-edge.png

5. Open the SA app on your Android phone and click the "SETUP" button. This will activate the camera so you can scan a QR code. You will have to give the SA app permission to use the camera for this step.

android-app-open.jpg android-app-cam-permission.jpg

6. Scan the QR code in the section QR code for connecting android device and select "CONNECT" to connect the app to the server.

sa-studio-connect-edges-qr-code.png

android-app-ready-to-connect.jpg

7. The SA app should now display a message saying that it is connected to the server and show the host address.

android-app-connected.jpg

8. Check that your edge is listed as a connected device on the Edges page in SA Studio. It should appear in the list as ANDROID-EDGE.

sa-studio-connect-edges-edge-list.png

Step 4 - Test your setup

Now that you have added your Android phone as an edge device to the server it is time to test some queries.

1. Go to the OSQL editor by clicking the OSQL editor icon.

sa-studio.png

2. Open a new OSQL editor by clicking the open-new-osql-editor-button.png button.

3. Ensure that the queries will be evaluated on the server by selecting "server" in the device list at the bottom.

sa-studio-osql-editor-device-selector-server.png

4. In the editor window, write the query listening_edges();.

sa-studio-osql-editor-enter-query.png

Then run the query by pressing the Run queries icon to run the query. The result is a list of edges that are connected to the server. Your Android phone should be present with the name "ANDROID-EDGE".

["ANDROID-EDGE"]

5. Change the device on which the queries are run by clicking device-selector.png at the bottom (next to the run query button) and select Android-edge from the list.

sa-studio-osql-editor-device-selector-win-edge.png

Now when you run a query it will execute on your Android edge device.

6. Try executing a query on the Android edge device by having device-selector-android-edge.png as selected device, delete the previous query from the editor window and execute the new query:

this_peerid();

This should output the string "ANDROID-EDGE" which is the id of your Android edge device.

Now we have verified that your Android phone is connected to the server, and that it can run queries retrieved from the server.

Step 5 - Examine the sensors

Now that you have tested that you can execute queries on the Android edge device it is time to examine how we can interact with the sensors on the phone.

1. First we check what sensors (signals) we have access to. We do this by executing the following query (ensure that you have device-selector-android-edge.png as selected device).

signals();

The query returns a set of the names of all the signals on the device and should include some of the following.

"accelerometer"
"magnetometer"
"gyroscope"
"light"
"step_detector"
"step_counter"

2. Plot the accelerometer signal by executing the folowing query.

signal_stream("accelerometer");

This shows the accelerometer readings in the output window. Shake the phone a bit it to see how the readings change. See if you can determine which movement direction corresponds to which line in the plot.

sa-studio-osql-editor-accelerometer-plot.png

Step 6 - Develop a detect-shake model

Now that we have examined the accelerometer it is time to develop a simple model. Our model will use the accelerometer to signal if the phone is shaking. In its final form the model will signal 1 if the phone starts shaking, and 0 if it stops.

1. First we define a helping function that combines the three gravitation vectors in the stream from the accelerometer. This is done by typing in the function below and running it as a query (ensure that you still have device-selector-android-edge.png as selected device).

create function gravity_acceleration() -> Stream of Number 
  as select Stream of sqrt(sum(g .^ 2))
       from Vector of Number g
      where g in signal_stream("accelerometer")

The query should return a string #[OID <NUM> ] which is the id of the function.

2. Test the helping function by running the following query.

stdev(winagg(gravity_acceleration(),50,5));

The query passes "a window" over the stream and computes the standard deviation on each window. The standard deviation will be zero when the phone is not moving and some positive value when the accelerator readings change. Shake the phone and see how the plot changes.

sa-studio-osql-editor-gravity-acceleration-plot.png

3. Define a function that signals if the shaking is above some threshold. This is done by running the following query.

create function shake_state(Number threshold) -> Stream of Number
  as select Stream of shakes
       from Number shakes, Number elem
      where elem in stdev(winagg(gravity_acceleration(),50,5))
        and shakes = case when elem > threshold then 1 
                          else 0 end

4. Test the shake state function by running the following query and shaking the phone.

shake_state(5);

The output plot should show a step function with value 1 if the phone is shaking and 0 when the phone is still.

sa-studio-osql-editor-shake-state-plot.png

5. We want the final model to only emit values if the shake state changes. This is done by wrapping the function call in a changed() statement. We do this in a separate function by running the following query.

create function shakes(Number threshold) -> Stream of Number
  as changed(shake_state(threshold));

The output of shakes is better visualized by simply printing the values than plotting it in a diagram. So change the output from Automatic to Text in the output selector at the bottom next to the device selector.

sa-studio-osql-editor-output-selector-text.png

6. Now our final model is ready. Try it by running the following query.

shakes(5);

It should emit the value 1 when the phone starts shaking, and the value 0 when it stops. Just what we wanted!

Conclusion

Congratulations! You have now developed your first model on an Android edge device.

Where to go from here:

  • Use the documentation to learn more about OSQL and how you can build models and interact with edge devices.

Getting started with a Raspberry Pi or Pi Zero

Introduction

In this step-by-step guide you will learn how to get started with SA Studio by using a Raspberry Pi as an edge device. This guide also works for Raspberry Pi Zero as long as you download sa.engine for the Pi Zero.

Step 1 - Sign up

To access SA Studio Community Edition you first need to sign up, if you are not already signed up click the button below:

After signing up and verifying your email you can access sa.studio by pressing "START STUDIO", waiting for the studio environment to be started and then pressing "GO TO STUDIO".

NOTE: You can continue this guide from inside your sa.studio by going to the documentation page (1) then expanding Available Online -> streamanalyze.com and clicking Getting started (2) and then wait for the guide to be imported and loaded (3).

loading-getting-started.png

Step 2 - Download and start SA Engine on your edge device

Now that you have signed up it is time to download and start an instance of the SA Engine on your Raspberry Pi. Make sure you have an open SSH session to your Raspberry Pi before continuing this guide.

1. Go to the download page.

pi-download.png

2. Scroll down to the bottom and download sa_engine_core_linux_armv7.tar.gz (or sa_engine_armv6.tar.gz for the Pi Zero) and click the clipboard icon (see the red arrow in the picture). This will copy a command that you can just paste into the ssh session of your Raspberry Pi

pi-image-download-link.png

pi@pi-gw2:~ $ curl -o "sa_engine_core_linux_armv7.tar.gz" "<LONG-DOWNLOAD-URL>"
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100 3147k  100 3147k    0     0  3540k      0 --:--:-- --:--:-- --:--:-- 3544k
pi@pi-gw2:~ $ ls -la | grep sa_engine
-rw-r--r--  1 pi   pi   3222714 Nov  9 10:03 sa_engine_core_linux_armv7.tar.gz

If using Raspberry Pi Zero:

pi-image-download-link.png

pi@rpi03:~ $ curl -o "sa_engine_armv6.tar.gz" "<LONG-DOWNLOAD-URL>"
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100 2725k  100 2725k    0     0  2206k      0  0:00:01  0:00:01 --:--:-- 2208kl
pi@rpi03:~ $ ls -la | grep sa_engine
-rw-r--r-- 1 pi   pi   2790410 Nov  9 09:05 sa_engine_armv6.tar.gz

3. (optional) If you do not wish to use this command you can download the archive sa_engine_core_linux_armv7.tar.gz or sa_engine_armv6.tar.gz to your PC and then transfer it to your home directory on the Raspberry Pi in any way you see fit.

4. In your open SSH session where you are logged into the Raspberry Pi, extract the sa_engine_core_linux_armv7.tar.gz (or sa_engine_armv6.tar.gz for the Pi Zero) and cd into sa.engine/bin.

pi@pi-gw2:~ $ tar -xzf sa_engine_core_linux_armv7.tar.gz
pi@pi-gw2:~ $ cd sa.engine/bin
pi@pi-gw2:~/sa.engine/bin $

5. Start SA Engine by executing ./sa.engine.

pi@pi-gw2:~/sa.engine/bin $ ./sa.engine

This prints the SA Engine database image, version number and presents a prompt.

Database image: sa.engine.dmp
Release 4, v0, 32 bits
[sa.engine] 1>

Exit sa.engine by typing quit; and press enter.

[sa.engine] 1> quit;
pi@pi-gw2:~/sa.engine/bin $

Step 3 - Connect your edge device to the server

Now that you have SA Engine installed on your Raspberry Pi it is time to start a server in the cloud and connect your local SA Engine instance to the server as an edge device.

1. Go back to the SA Studio Community Edition landing page.

streamanalyze-com-studio.png

2. Start SA Studio with the go-to-studio-button.png button. This will be your server instance.

sa-studio.png

3. Go to the "connect edge devices" page by clicking the Connect edge devices icon in the top left row.

sa-studio-connect-edges.png

4. Under Add clients or edges to the federation change the name in the client name text field from "edge" to "pi-edge".

sa-studio-connect-edges-input-pi-edge.png

5. Copy the large text blob in the section Connect as edge using base64 blob from within sa.engine to the clipboard, open a new file "connect.osql" on the Raspberry Pi using nano (or your preffered editor) and paste your clipboard content.

sa-studio-connect-edges-copy-connection-blob.png

pi@pi-gw2:~/sa.engine/bin $ nano connect.osql

sa-studio-connect-edges-paste-pi-connblob.png

Note: You can change the call connect_using_config_blob to reconnect_using_config_blob if you want the pi-edge to override the current peer when connecting.

Save the file with Ctrl+o and press Enter. Then exit nano with Ctrl+x.

6. Go back to your ssh session and start SA Engine on the Raspberry Pi.

./sa.engine
Database image: sa.engine.dmp
Release 4, v0, 32 bits
[sa.engine] 1>

Execute the contents of the text file by loading connect.osql.

[sa.engine] 1> < "connect.osql";

This connects the local instance of SA Engine to the server. The local SA Engine should print a message confirming that it is awaiting queries from the server.

2021-11-08T10:13:42.437 Edge PI-EDGE waiting for query from SERVER...

Your browser should also show your Raspberry Pi machine as "PI-EDGE" in the list of Connected edge devices. You might have to click the refresh icon at the top of the list for "PI-EDGE" to show up.

sa-studio-connect-edges-list-connected.png

Step 4 - Test your setup

Now that you have added your Raspberry Pi as an edge device to the server it is time to test some queries.

1. Go to the OSQL editor by clicking the OSQL editor icon.

sa-studio.png

2. Open a new OSQL editor by clicking the open-new-osql-editor-button.png button.

3. Ensure that the queries will be evaluated on the server by selecting "server" in the device list at the bottom.

sa-studio-osql-editor-device-selector-server.png

4. In the editor window, write the query listening_edges();.

sa-studio-osql-editor-enter-query.png

Then run the query by pressing the Run queries icon to run the query. The result is a list of edges that are connected to the server. Your Raspberry Pi should be present with the name "PI-EDGE".

["EDGE1","PI-EDGE"]

5. Change the device on which the queries are run by clicking device-selector.png at the bottom (next to the run query button) and select Pi-edge from the list.

sa-studio-osql-editor-device-selector-pi-edge.png

Now when you run a query it will execute on your Raspberry Pi.

6. Try executing a query on the Raspberry Pi edge device by having device-selector-win-edge.png as selected device, delete the previous query from the editor window and execute the new query:

this_peerid();

This should output the string "PI-EDGE" which is the id of your Raspberry Pi edge device.

Also note that SA Engine instance on the Raspberry Pi should confirm in your SSH session that it ran the query this_peerid().

2021-10-18T14:38:32.392 Running query 1: this_peerid();
2021-10-18T14:38:32.444 Query 1 finished

Now we have verified that your Raspberry Pi is connected to the server, and that it can run queries retrieved from the server.

Step 5 - Deploy and run a model

Now that you have tested that you can execute queries on the Raspberry Pi edge device it is time to deploy a simple model. Our model will be a simple mathematical transform that converts temperature values from Celsius to Farenheit. First we will create the model and save it on our server. Then we will deploy it to the edge and run it.

1. Right click on "User models" and then select "Create new model".

add-user-model.png

2. Write the model name "my_ctof" in the dialog that appears and click "Ok".

new-model-dialog2.png

This creates a new folder "my_ctof" with three files.

sa-studio-osql-editor-user-models-my-ctof.png

3. Click on the master.osql file and add the following to the file by pasting it into the editor window:

create function ctof(Number c) -> Number
  /* Convert a Celsius degree `c` to Fahrenheit */ 
  as c * 9 / 5 + 32;

4. Save the file by clicking the Save icon in the top right corner (or pressing Ctrl-s).

Unsaved files are marked in the editor tab with an aterisk * next to its name. When you save the file the asterisk disappears.

5. Verify that my_ctof has been added to your models by running the user_models(); query in a new OSQL tab. The steps for running a query in a new tab is:

  1. Click the plus sign in the top right corner and select "New OSQL tab".

sa-studio-osql-editor-new-osql-tab.png

  1. Ensure that you have selected the correct device (now it should be set to device-selector.png).

  2. Write the query (user_models();) in the editor tab.

  3. Run the query with the Run queries icon in the bottom left corner.

The output should include "my_ctof".

6. Now you can deploy the model by running the following query (on the device-selector.png):

deploy_model(["pi-edge"],"my_ctof");

The edge device answers with its peer id ("PI-EDGE") when the model has been deployed. Note that the SA Engine instance confirmes that the model was loaded in the Raspberry Pi SSH session.

2021-11-08T10:33:33.306 Running query 2: _download_commit_model('my_ctof')
Reading OSQL statements from "/home/pi/SA/models/my_ctof/master.osql"
2021-11-08T10:33:36.930 Query 2 finished
2021-11-08T10:33:36.932 Terminating coroutines for 2
2021-11-08T10:33:36.932 Query 2 cancelled
2021-11-08T10:33:36.950 Query 2 cancelled

7. Now you can run the model on the edge by simply changing device to device-selector-win-edge.png and run the following query:

ctof(32);

You should get the result 89.6 from your edge device.

8. You can also ship queries to edges from the server by using the built-in function edge_cq(Charstring edge, Charstring query) which evaluates query on edge.

Try this by first ensuring that you have selected device-selector.png as your device and run the following query:

edge_cq('pi-edge', 'ctof(72)');

You should get the result 161.6 from your edge device.

Step 6 - Get a stream of readings from the temperature sensor.

On a Raspberry Pi you can access the temperature reading by the file /sys/class/thermal/thermal_zone0/temp. Each reading is in celsius * 1000

To get a stream of temperature readings you can use the csv:file_stream function with "loop" as option.

edge_cq("pi-edge", "
        csv:file_stream('/sys/class/thermal/thermal_zone0/temp', 'loop',0.1)/1000
        ");;

pi_read_sensor_csv.png

You are now looking at a stream of temperature readings from the internal sensor on the CPU.

Defining a signal of the temperature sensor.

To wrap this up, let's add some meta-data to my_ctof model that contains the necessary steps to add the temperature sensor as a signal in sa.engine. Copy the following OSQL-statements and paste them into the master.osql file for the model my_ctof:

create Signal (name, doc) instances
 ("CPU_temp", "Temperature reading from the CPU tempereature sensor");

set ts_signal_stream(signal_named("CPU_temp")) =
  (select stream of ts(temp)
    from Number temp
   where [temp] in csv:file_stream('/sys/class/thermal/thermal_zone0/temp', 
                                   'loop',0.1)/1000);

sa-studio-model-with-metadata.png

Save the file and then re-deploy the model to pi-edge:

deploy_model(["pi-edge"],"my_ctof");

If you call the function signals() on the Raspberry pi now you will see that we have a signal called CPU_temp defined:

sa-studio-osql-editor-signals-pi-edge.png

You can now get a stream of the temperature signal by running:

edge_cq('pi-edge', 'signal_stream("CPU_temp")');

sa-studio-osql-editor-signal-stream-temp-pi-edge.png

To get a stream of readings in Fahrenheit simply apply the function ctof to each number in the signal stream:

edge_cq('pi-edge', '
          select ctof(c) 
            from Number c 
           where c in signal_stream("CPU_temp")
        ');

sa-studio-osql-editor-signal-stream-f-temp-pi-edge.png

Conclusion

Congratulations! You have now deployed your first model to a Raspberry Pi edge device and used it on the built in CPU temperature sensor.

Where to go from here:

  • Use the documentation to learn more about OSQL and how you can build models and interact with edge devices.
chevron_right