Getting Started

This brief guide shows how to setup PHONK and goes through a step-by-step example. It will take around 10-15 mins to complete it.

Installation

Grab your Android device and install PHONK from any of the sources. Once installed, you will have to

  1. Grant certain permissions to PHONK so you can create programs that can do cool stuff with the Camera, sensors, internet, etc*.

  2. Install de Examples. PHONK copies the examples to a part of your device memory that can be visible by other apps. This is nice since it makes it very easy to backup your projects or edit them with other apps.

* PHONK respects your device and privacy. PHONK does NOT send information to the internet and does NOT use any type of analytics to track how you use the app.

Note: If you are updating to a newer version, sometimes you will get a screen asking you to update the examples 🙂

alt text

First run

When you open PHONK you will see a screen like the one below. On the top part, there is an INFO area that shows things like when you launch an app or the IP address of your device, so you can create scripts easily from your main computer. The bottom part is a standard navigation view where you can navigate through the built-in examples and your projects.

Let's open a couple of examples in the next sections.

alt text

Opening and Editing an Example on your Android device (Sound Record)

Navigate to Sound → Record Voice and tap on it so it will launch the script. You should see a screen like this that invites you to click on the top toggle button to record sound and click on the green button to play it back.

alt text

Nice! Let's see how it is made.

Exit the script by pressing back on the bottom bar or doing the back gesture on newer Android devices.
Go again to Sound → Sound Record but this time click on the three dots and click on Edit to see the source code.
Then move to the line where it says 'Record' and change the word to 'Record your voice'. Maybe you want to comment out the first line of code as follows // ui.addTitle(app.name) so we remove the title.
Press on the Save icon and then Play.

Voilà! You have your first script modified!
The source code is pretty straight forward but we are not going to go through the code yet! I invite you thought to make sense of it :)

alt text

Opening and Editing and Example using the Web Editor

Now we are going to do something similar as before but using the remote Editor.

The first thing we need is to make sure that we have a computer with a modern web browser installed. Then connect the Android device and the computer to the same Wifi network. If you do so, PHONK will show an IP address on the INFO area. Now make sure that the button Enable Web Editor is highlighted.

alt text

Type the IP on the computer web browser and press enter. If everything went well, you should see an interface showing the same Examples as your phone. Let's open the example Sensors → Accelerometer.

You can see the code on your web browser. If you click on the Play button, the script should rapidly appear on the Android device.
Press ON and start shaking your Android device. You will see the accelerometer values changing as you move your device!
Press stop on the Web Editor to stop the script running and let's edit the code. Right after line 14, insert the line console.log(data.x)

alt text

Press play again on the Web Editor. Now you should see the accelerometer's X values on the console area, in the bottom right side of the Web Editor.

This is very handy to debug data, but don't overuse it otherwise you might freeze the tab sometimes... 😉

Your first Project

Let's create a basic PHONK's hello world. The project will use the distance sensor of your device to play a sound and change the background color when you hover your hand over it. To start and stop the sensor, we are going to use a couple of buttons.

Open the Web Editor as you did in the previous step. If you had it already opened, click on the top-center area to open the "Projects Area". Write a nice name for your project such as "HelloWorld" and click on Create.

For this example, we need to know 3 things.

  1. Add some user interface
  2. Use the proximity sensor of your device
  3. Play some sounds

You can go to the DOCS, on the top-right area of the Web Editor and do quick browsing on how to use the proximity sensor, add a button and play a sound but being honest, the DOCS are very simple at the moment and is much easier to learn to explore the examples and see how things work.

So I invite you to take some minutes to open the examples to see how things might work (Tip: you can open the examples on different tabs in the web browser)

  • Sensors → Proximity
  • Graphical User Interface → Basic Views
  • Media → Sound Play

So, have a look at them and then continue reading :) ... ... ... ... OK, let's continue!

Step 1 - User Interface

PHONK uses normalized units. Any position and size of a UI element such as a button, text, or image will be in the range of [0.0 - 1.0]. The reason to have them normalized is to be able to quickly create interfaces without using complex layout systems. Of course, it has it's trade-offs but that's for another chapter :)

Most of the user interface components need 4 values, the x, y positions, and the width and h height (w, h).

Let's try to add a couple of buttons with different sizes and positions.

ui.addButton('button 1', 0.1, 0.3, 0.45, 0.1)
ui.addButton('button 2', 0.4, 0.55, 0.3, 0.3)

If we run the code we will get the left screen. To make sense of the coordinates on the right you can see in yellow color which value is wich value. Reference positions are added with blue color. It seems confusing, but it is super easy! :)

alt text

Note: PHONK can use pixel coordinates as well, check the Graphical User Interface > Advanced positioning example to know more about it.

Then to do something when the button is clicked we use the .onClick callback. Any code we write inside the callback will be executed when the button is clicked. Finally, if we try out the following code we can get a button that changes the background color when clicking on it.

ui.addButton('click me', 0.1, 0.3, 0.8, 0.1).onClick(function () {
  ui.background(255, 255, 0)
})

Step 2 - Proximity Sensor

Using sensors in PHONK is quite simple. As we see below, we have an onChange method that gives us the sensor data as soon as the sensor has a new value. The .start() method tells the sensor to start reading values and as you might expect, you can stop the sensor using .stop()

sensors.proximity.onChange(function (data) {
  console.log(data.distance)
})
sensors.proximity.start()

Run the code and hover your hand over the device, you should be getting some values in the console so we can understand the sensors values.

Note: A good tip to understand sensors is to display the sensor data. The examples plot the data graphically so you can see the values and make sense of how they work rapidly.

Note: PHONK will stop automagically the sensor as soon as you exit the project, so most of the time you don't need to call .stop() in your script.

Step 3 - Playing a sound

Playing a sound is easy, with the following code we are ready to go.

var player = media.createSoundPlayer()
player.load("sound.wav")
player.play()

But now you might wonder how to add sounds to the project That's easy! Download this file as an example. Then go to your file explorer and drag and drop the file over the FILES area in the Web Editor. The files will upload quickly.

alt text

Note: As today there is some bug I could not hunt yet on the web editor while uploading. If it happens to you, just reload the tab, sorry! :)

Final Step - Putting all together

Now that we know how to do each part let's combine them as the following code:

/*  
 *  PHONK HelloWorld
 *  by Víctor D.
 */

ui.addTitle(app.name)

var img = ui.addImage(0.2, 0.2, 0.6, -1)
var btn = ui.addButton('Start', 0.1, 0.8, 0.35, 0.1).onClick(function () {
  sensors.proximity.start()
})

var btn = ui.addButton("Stop", 0.5, 0.8, 0.35, 0.1).onClick(function () {
  sensors.proximity.stop()
})

var player = media.createSoundPlayer()
player.load("sound.wav")

sensors.proximity.onChange(function (data) {
  console.log(data)
  
  if (data.distance < 1) {
    ui.background(255, 255, 0)
    player.seekTo(0)
    player.play()
  } else {
    ui.background(0, 0, 0)
  }
})

And that's it! We have our quick "Hello PHONK". I hope this is a good first start to play with PHONK.

alt text

Exercise: We are using 2 buttons to Start / Stop the sensor. Can you combine it into one? You might check in the examples how to use the Toggle button.

Summary

We learned how to run and modify projects using the PHONK app and the remote Web Editor. We sent data to the console, uploaded files into the project and we presented some hints on how to explore functionality in PHONK using the DOCS and the built-in examples.

If you find PHONK and this tutorial interesting, feel free to contribute through Patreon. With your help I could spend more time doing open source software and tutorials. I'd love to write the following:

  • How to use Bluetooth Low Energy with Arduino compatible boards
  • Create music synths with LibPd
  • Interactive Graphics with Processing,
  • Teaching your phone to recognize images with Tensorflow
  • Create a custom OSC controller
  • and many more!

Thanks for your time and enjoy it!