DreamLover Laboratories - Scripting tutorial #2 - Your first random DreamLover 2000 command

Disclaimer

When purchasing a DreamLover Labs device, you are purchasing a hardware device, and not software development services, or a guarantee that such services will be extended, or a commitment to extend such services at a specific price. There is no guarantee, either implicit or explicit, that you will be able to implement a specific new feature using the Javascript API, to extend functionality beyond what is described in the User's Guide. DreamLover Labs are under no obligation to provide any programming assistance beyond the tutorials on this site. In particular, we are unable to offer assistance to non-programmers trying to create their own scripts. Do not expect to be able to use the API if you have never programmed in Javascript. Programmers trying to code scripts are normally aided by pointing them to the relevant functions if the need arises. We do not normally take on programming/software development tasks on behalf of our users. If a quote for such a project is ever given on an exceptional basis, it will likely be substantially higher than market rates, due to this kind of service being outside of our line of business. If your choice to own a device is conditional to the possibility of realizing a specific feature, please consult with us first. Please understand that while we can tell you whether a specific new mode of operation is possible or not with our API, we absolutely cannot guarantee that you will be able to accomplish the relative programming tasks. Additionally, should you have difficulties in the attempt, we will not be able to come to the rescue and do the programming work necessary. Therefore by purchasing a device you agree to being entirely responsible for carrying out or outsourcing the programming work relative to whatever new features you will wish to create. We do not accept returns past the review period stated on the terms of sale, and your inability to program or hire someone to program some vital feature that makes the device useful to you does not constitute an exception to this rule.

In the previous tutorial we learned how to create a simple HTML page and load it inside the DL Browser. Today we will actually deliver a command in JavaScript.

Add the script section

In today's tutorial we will create a button which randomly deivers a vibration or an electric pulse. For the vibration we will use Silent Command #1. The first thing we want to do is to add a script section to the HTML. Any code within this tag will be parsed as JavaScript (as opposed to HTML). In JavaScript, all characters on a line after // are considered a comment and ignored. This allows us to insert plain English comments in the code for explanatory purposes.

Add a button

Note that this does not produce any output yet, because there are no HTML tags and no Javascript code. So we move forward and add a button. We insert the code for the button within the HTML block, but after the script section, because the button is just a plain HTML tag, so it must not be parsed by JavaScript.

The code above will produce a button like this one:

This button is rendered by the browser and is clickable, but it doesn't do anything. To make it do something we do this:

Popup when the button is clicked

This is telling the browser that when the button is clicked, the JavaScript code alert(1) must be executed. Alert is a function that creates a popup box, and in parentheses we specify what is to be written within the box. In this case, just the number 1. Try it below.

OnClick calls a function

In this tutorial we want to do something more complicated than just opening a popup, so to avoid creating confusion, we rewrite the code we've just written in a way that makes it easier to build functionality. Instead of specifying the code to execute right inside the button tag, we move it to the script section and create a function. A function is just a piece of code which can be given a name and executed. The name doesn't matter at all so use your fantasy. Once the function is there, we put the function name inside the OnClick attribute, so that it will get called when the button is clicked.

This button does the exact same thing as the previous one, but by calling a function.

Now, when the button is clicked, the browser calls our function, which in turn calls alert(1) and displays the box.

About parentheses

If you've never programmed before you may be confused about the many parentheses. Functions use round parentheses to accept arguments, that is, parameters which the function will use. In this case our function won't need any parameters, because its behavior does not depend on context - it does the same thing every time it's executed. Some functions do need parameters. For instance, alert takes the text or number you want to show in the popup as a parameter. Even though doSomething has no parameter, it still needs its parentheses, just there won't be anything in them.

As for the curly brackets, those just tell JavaScript the beginning and end of the function. For a more detailed explanation, try this link about functions.

JavaScript to DL2K-LINK communication

Next step, we try to deliver a command to the DreamLover 2000 within JavaScript. We also rename the function for clarity and change the button text.

From here on you must test the code in the DL Browser. The following buttons will not actually communicate with the DL2K-LINK under standard browsers. To see the code working, paste the code in your test.html file from the previous tutorial and open it in the DL Browser. Or, if you wish to just read this page and click the buttons below and see them operate, open this page in the DL Browser (you will need to authorize this URL the same way you authorized your own test.html file in the previous tutorial).

Arming the DL Browser

When you click the button within the DL Browser, the DL Browser should show the error message "Disarmed, ignoring comand" on the status bar at the bottom.

This informs us that we need to "arm" the browser (allow it to send commands to our Male Management devices) in order to proceed. This is a basic safety precaution.

Clicking the arm/disarm button at the right side of the DL Uplink will change its text to "armed" and its color to red. Now try clicking the "Send a random command" button again. The LED on the DL2K-LINK will turn on for a second or so, indicating that radio transmission is occurring.

Your DreamLover 2000 unit will respond by delivering a low level pulse.

Random choice of pulse or vibration

All that remains is to implement the logic whereby we randomly deliver either a pulse or a silent command.

The above code randomly delivers either a pulse or a vibration. It does that by first generating a random number (with many decimal digits) between 0 to 1. Then, it examins that number, and if it's larger than 0.5 (which will happen 50% of the time) it sends a low pulse. Otherwise, it sends a the Silent Command. Either way, after the command has been delivered, it opens a popup box to tell us which command has been delivered.

Try it below.

There's a lot going on in the function above. randomNumber is a variable, i.e. a symbol which can contain a value. Variables are declared in JavaScript by preceding their first occurrence with var. Their value is set with the = assignment operator. In this case, the variable is set to the value returned by the function Math.random (this is the function that returns a random number each time it's called). Then we see an if-else statement, which again uses curly bracks to delimit which instructions to execute if the condition (randomNumber > 0.5) is true, and which to execute if it's false.

Further study

Notes for programmers

The method used above to communicate with the DreamLover 2000 is quite unsophisticated. It will generate JavaScript errors under other browsers. It is not checking if the code is being run under the DL Browser. It will not check if the browser is armed. It will not ensure the "Arm/disarm" button is visible. It will not check if the DL2K-LINK is connected. To do all these things, it is best to use the functions in the class DLBrowser.js (available here, but subject to sudden changes). In particular, check out isDL2KLINKConnected(), DLBrowserShowToolsPanel(), isDLBrowserArmed(), and SendDL2KCommand().