Timers

Introduction

Most of the time, you will need to do some things periodically or after a time, or you would like to wait between two instructions.

MagiScript has several functions to support you.

Wait

This basic call will add a delay to your code. Use it wisely, as it is blocking the script engine, so no other code will run until it ends (like no button presses or timeouts will be executed).

Because of this, we recommend not using it at all. But for experience with MagiScript, it’s OK to use, just don’t add a long wait.

It is a simple function, with one parameter:

				
					wait(100); // wait 100 milliseconds (0.1 seconds)

For example, you can try this code. The LED will go green for 1 second, but this is running in the background, and the code execution goes on. The wait function then waits 2 seconds. The LED will turn off after 1 second and will stay off for a second until the wait function ends. Then it turns yellow and stays on.

				
					function main() {
    atom.led('g='); // green LED for 1 second
    wait(2000);
    atom.led('y*'); // yellow infinitely
}

Read on about the timers below, however, this is the alternative we recommend. It is harder to read, more code, but MagiScript events won’t be blocked at all.

				
					function main() {
    atom.led('g='); // green LED for 1 second
    setTimeout(function() {
        atom.led('y*'); // yellow infinitely
    }, 2000);
    
}

Timers

Timers are to run code parts periodically or after a time. You can work with 16 timers at a time. These functions are coming in a pair:

setTimeout and clear

TimeoutsetInterval and clearInterval

The setTimeout triggers a code once, the setInterval triggers the code infinitely. The clearTimeout will prevent the timer from triggering the code if called before the execution. The clearInterval will stop the timer, so it will not trigger the code again.

Using them is simple:

				
					setTimeout(function() { console.log('hello'); }, 1000);
setInterval(function() { console.log('hey'); }, 100);

Both setTimeout and setInterval need two arguments, a function and an interval in milliseconds.

There are at least three ways to pass a function. You can pass an “anonymous” function like in the code above, you can pass an “arrow function”, and you can pass the name of a function declared before or later:

				
					// anonymous funnction
setTimeout(function() { console.log('howdy'); }, 1000);
// arrow function
setTimeout(() => { console.log('cheers'); }, 1000);
// reference
setTimeout(log, 1000);
function log() { console.log('hiya'); }

Both the setTimeout and setInterval functions are returning a number. You can use this to cancel them:

				
					let timeoutId = setTimeout(() => console.log('I will never run'), 1000);
clearTimeout(timeoutId);

All in all, they are working quite similarly to JavaScript. If you are looking for some ideas about how you can use them, the Atom Time and Atom Level examples can give you some hints.

If Atom is not yet connected to a PeekSmith device, it will start searching for it and then connect. If a PeekSmith device is already connected, this command will be ignored (even if it is a different device). You can use the '*' character to connect to any available PeekSmith device.

The best way to connect is by adding this call to the beginning of the main function, which runs when the code is loaded.

				
					function main() {
  ps.connect('PeekSmith-036666');
  // ...
}

Displaying Text on PeekSmith Screen

Once you have connected to a PeekSmith device, you can display text on its screen using the ps.print method. The method takes a single argument, which is the text that you want to display on the screen. If PeekSmith is not yet connected, MagiScript will collect your messages and send them as soon as a device is connected.

For example, if you want to display the text “Hello World” on the PeekSmith screen, you can use the following code:

				
					ps.print('Hello World');

This will display the text “Hello World” on the PeekSmith screen.

Using PeekSmith’s “Smart Text”, you can display cards or colors on the screen like sending messages:

				
					ps.print('AH');        // displays an Ace of Heart
ps.print('7D KS');     // seven of diamonds, king of spades
ps.pring('star');      // displays a star ESP sign
ps.print('yellow');    // displays a yellow card

Vibrating PeekSmith

You can also vibrate the PeekSmith device using the ps.vibrate method. The method takes a single argument, which is the pattern that you want to vibrate.

For example, if you want to vibrate the PeekSmith device with a pattern of three short vibrations, you can use the following code:

				
					ps.vibrate('...');

This will vibrate the PeekSmith device three times in a short pattern. The latest PeekSmith firmware supports the same patterns as Atom (except the short tick).

Accelerometer Data (since firmware v1.1.31)

PeekSmith 3 has an accelerometer, and Atom can turn it on or off. When turned on, the accelerometer will start reporting raw x, y, and z data.

Accelerometer ON

There are more ways to turn on the accelerometer, but they have the same effect:

				
					ps.accel('on'); // please note that ON or On will not work
ps.accel(true);

Accelerometer OFF

Turning off the accelerometer is similar:

				
					ps.accel('off'); // please note that OFF or Off will not work
ps.accel(false);

Accelerometer Data

You will start receiving events with XYZ data when you turn on the accelerometer via the onEvent function. The value is going to be comma-separated numbers, the type ‘xyz’, and the source ‘ps::accel’.

Example

Here’s an example code of how you can use them:

				
					function main() {
  ps.connect('PeekSmith-031060');
  ps.accel('on');
}

function onEvent(value, type, source) {
  if (type === 'xyz' && source === 'ps:accel') {
    let xyz = strSplit(value, ',');
    let x = parseInt(xyz[0]);
    let y = parseInt(xyz[1]);
    let z = parseInt(xyz[2]);
    console.log(x, y, z);
  }
}

Receiving Button Events

When a PeekSmith is connected, it will start sending button press and release events. PeekSmith has 3 buttons, #0 is the side button, #1 is the front left button, and #2 is the front right button. You can process them with the onEvent function.

Read our Buttons documentation page for more details.

Conclusion

MagiScript provides an easy way to connect to and control PeekSmith devices directly from Atom. By using the ps.connect, ps.print, and ps.vibrate methods, you can interact with the PeekSmith device and display text and patterns on its screen, as well as vibrate it.