About This is Dexter Development Environment
version: 1.1.10
released: Jun 23, 2017

DDE helps you create, debug, and send software to a Dexter robot. You can use any Javascript augmented with DDE-specific functions to help find out about, and manipulate, a robot.
Videos on Dexter

Why Use DDE? Dexter has a limitless variety of capabilities. We couldn't think of them all let alone program them. And if we could, finding the right button for each program would be extremely difficult, besides overfilling screen real estate.

By providing a general purpose language that is broad enough to cover all the bases, yet detailed enough to specify the action details, users can specify the precise behavior they desire. We've extended JavaScript, most common web page programming language, with dexter-specific functions like "move" and ways to gets values from its sensors (like camera"). This allows you to specify things like: If part X is in the workspace, then move it 10 millimeters to its left.

You need a general purpose language to customize that "10" with any computable number in a myriad of ways. We may want to create actions that depend on conditions that differ with the environment, time, or materials. Instead of move, we might want to rotate, or grasp, or drill, etc.
Won't a Text Editor Do? You could use any old text editor to write code. But you'd need to know:
  1. What capabilities are available?
  2. What do they actually do? (semantic details)
  3. How do I use them? (syntactic details)
  4. How do I run the code?
  5. How do I localize bugs?
  6. How do I understand and fix them?
  7. How do I store and re-run programs I've created?
  8. How do I change and extend existing code?
DDE helps you with all of the above.
Prerequisites You'll need a Dexter robot and a basic knowledge of JavaScript to make full use of DDE. DDE provides a lot of help for learning JavaScript directly and the Learning JavaScript section of this documentation gives you a number of very good on-line sources to smooth your path. Without a robot, you can still use DDE to simulate one.
Installation
First Install To get the latest DDE release,
Updating to the latest DDE Follow the directions under First Install above. This will not change any files in your dde_apps folder.

Twist down the About row in the Doc pane to see the installed version number of DDE.

Launch DDE On Windows, the DDE application is installed in C:\Program Files\dexter_dev_env\dexter_dev_env.exe and on the desktop.
On Mac, Macintosh HD/Applications/dever_dev_env.app

Double click on the file to launch DDE. If there is a file Documents/dde_apps/dde_init.js, it will be loaded automatically. Thus you can put any code in that file that you want to be evaled at start-up, such as libraries you've written, etc.

Configuration DDE requires that you create a folder under your Documents folder named dde_apps. If this does not exist when you launch DDE, you'll see a warning in the output pane.

DDE requires that you define a default robot named "dexter0". Usually the one that is automatically inserted into the file dde_apps/dde_init.js is fine. However, in that file you will need to set the ip_address and port number of Dexter. {todo: document how to find Dexter's ip_address.} The port number is typically "50000".

When you plug in and power on Dexter, you will see LEDs light up on Dexter's processor board.

User Interface Video tutorial of DDE
Editor Pane The Editor pane is a text editor. You can view and edit any text documents in it, but primarily you will be editing JavaScript that defines a job to make something with Dexter. DDE expects you to save such "apps" in your Documents/dde_apps/ folder.
Output Pane DDE prints information in the Output pane that will be useful in your current context. You can explicitly print in the output pane with a call to the JavaScript function out. Example:
out("hi world", "blue")
out accepts any valid HTML as its first argument. It will be rendered in the Output pane.
Start Job Button Clicking this button evals and starts the job that the cursor is in.

If the cursor is in a job's source code but not in the do_list, then the job source will be evaled, and the job started.

If the cursor is on an instruction in the do_list with no selection, the job will be evaled and started with the first instruction run being the one the cursor is on.

If there is a selection within the do_list, then the first instruction run will be the one that contains the start of the selection, and the last instruction run will be the one that contains the end of the selection. This works by setting the job's program_counter and ending_program_counter properties.

If you have selected the source code for one or more instructions (with comma's between them) and there is no new Job wrapper around the instructions, then a Job wrapper will be automatically made behind the scenes, the job will be defined, and started.

Just before an instruction is run, it will be selected in the editor.

Documentation Pane The Documentation pane attempts to describe the core knowledge you'll need to command Dexter to make things. Admittedly we'll always fall short of this goal, but let us know if some crucial information is missing and we'll do our best to fill the void.

You can find out what version of DDE is running and the latest changes under the Release Notes section of the documentation. Details about programming Dexter are in the Reference Manual section.

Simulate Pane
The simulate pane shows a graphical simulation of Dexter with joint angles of the last heartbeat robot status returned. (By default, heartbeats happen every 100ms.)

Use the mouse in the Simulate pane to:

  • Rotate table: mouse-down then drag.
  • Zoom: shift-down then mouse-down then drag.
  • Pan: alt or option down, then mouse-down, then drag.

shows Dexter randomly flailing around, not correlated to a connected Dexter.

The menu in the Simulate pane header let's you browse several videos showing off Dexter's capabilities.

Stepping Instructions To understand a Job's behavior, its useful to step through each instruction. Checking the pause checkbox will cause running jobs to pause when they have completed their current instruction. Jobs started when the pause button is checked will pause right before the first user instruction on the do_list is run.

When a job is paused, clicking the button will cause it to execute the next instruction, print out useful information in the Output pane, and pause. If a job is paused, and you uncheck the pause checkbox, then click the button, the job will begin running normally.

"debugger" The instruction of "debugger" in a do_list will cause the pause checkbox to be checked and the job to pause. A function that returns the string "debugger" or even an array that has an element of "debugger" will cause a pause.

Note that using the string "debugger" is intentionally similar to using the JavaScript constant debugger. If you have the constant debugger in the body of a function that is a do_list item, or is called by a do_list item, it will cause a JavaScript breakpoint and you can step through that code using the Chrome dev tools. See Documentation top level section Debugging.

JavaScript DDE let's you control a Dexter robot with Javascript. You can execute all of JS. DDE extends JavaScript with a library of functions that control Dexter, allow access to Unix commands on Dexter's computer, Window system extensions, as well as ROS specific function calls allowing you to find out about and control Dexter.

In DDE, console.log sends its output to the (usually hidden) Chrome console. Use out (on the menu) to see output in the Output pane.

Learning JavaScript The quickest way to learn most of the JavaScript you'll need is from the Editor Pane's menu. Read menu item tooltips, choose an item to insert code, then click to eval all the code in the Editor. If there's a selection when you click Eval, just the selected code will be evaluated. Choose menu items under in depth-first order for a consistent overview, and later you can choose exactly those items you need to insert a code snippet.
Warning Code in the editor that has not been evaled will have no effect.

A nice interactive tutorial is available at: https://www.codecademy.com/learn/javascript Beware that console.log prints to the normally hidden chrome console. DDE's out is easier to use.

If you want more prose, there are lots of JavaScript tutorials on the web. You will not need to know HTML, CSS or JQuery that are commonly taught in conjunction with JavaScript.

A very gentle intro to JavaScript. Ignore the parts that use the Underscore library.
A more formal (and long) tutorial.

JS for Programmers If you're already a competent programmer but don't know JS specifics, here's a few tips:
JavaScript is an untyped language. That means you don't declare types of variables, function parameters, or return values. So for instance,
C's      int foo = 32;
in Js is var foo = 32;
The type system is, um, weak. The object system is also in somewhat of disarray. Because of that there are many packages adding a more rational Object system, but they all differ, confusingly.

There's no compiler in JavaScript. There are no "includes" or "pre processors" or "macros". The code is run in an iterpreter inside a browser (every browser, actually). The major browsers also offer a debugging environment, though typically no Editor. DDE gives you an editor and a lot of other convenieces for developing code.

Whitespace characters are those characers that "take up space" but you can't otherwise see. This includes space, tab, newline and a few others. In Javascript, mostly its the case that 1 whitespace character is equivalent to any number of contiguous whitespace characters. Except that function calls need to be ended with either a semicolon or a newline, not just a space. For example:
Math.min(3, 4); Math.min(5, 6)
is legal, as is:
Math.min(3, 4)
Math.min(5, 6)

but not:
Math.min(3, 4)  Math.min(5, 6)

There is no Window System per se in JavaScript but it ties into HTML, CSS and the browser's Document Object Model. This is confusing since it requires several different syntaxes and ways-of-thinking. DDE simplifies this by providing the key window system facilites you'll need for commanding Dexter via the function show_window, the Human.enter_* instructions and a few other utilities. See the menu.

Javascript's functionality greatly expanded in 2016 with a new version who's name itself is confusing. You'll see EcmaScript 6, JavaScript 2015 and a few variants. Browsers vary as to how much of this they implement, but Chrome, the browser DDE uses, has nearly 100% of this new standard implemented as of June, 2016. DDE depends on these new features.

See in, this documentation, Installation/Keep Chrome up to date. JS 6 can run code from earlier versions of JS, but there's an awful lot of new functionality that isn't in most existing JS documentation.

Like all popular programming languages, JavaScript has its problems. But its unique in its "deployability". JS and DDE runs on Windows, Macs, Linux, and Chromebooks. Its new features are quite powerful, and DDE strives to make learning and using JS as simple as possible. Your new skills will serve you well in Web programming for billions of users.

Recommended JS Tutorials for the experienced programmer (both of which ignore the new JS 6 extensions):
JS re-introduction
more comprehensive

Eventually you will need to know the concepts of ROS (the Robot Operating System), though not the syntax of BASH, C++ and Python normally required to work with ROS.
Workflow DDE let's you execute arbitrary JavaScript that is entered into the Editor pane.
  1. The Editor pane's menus allow you to insert useful code snippets into the Editor pane.
  2. You can edit and extend the inserted code. Use any valid JavaScript.
  3. Click the button. The result of the last expression evaluated will appear in the Output pane.
  4. If there is a selection when the button is clicked, only the selected code will be executed.
  5. Triple click on a line to select it.
  6. Alt-click on a JS function call to select it.
Try this: type into the editor
2 + 3
Click and see 5 in the Output pane.
Persistent Data When you have defined a named function, set a global variable or a property reachable by a global variable, that data will remain in the JS environment until you relaunch DDE. This is even true if you bring a new file into the editor.

Overall this facilitates programming, but it does have some behavior that may be unexpected. Imagine you define
function foo(){return bar()} and
function bar(){return 'stuff'}
You call foo() and it returns 'stuff'. Now you rename bar to baz and test baz(). It returns 'stuff' as expected, as does calling foo(). Now

The call to foo will error because bar is no longer defined. When redefining function and global variables, its a good idea to save your code in file(s), relaunch DDE, and reload your code periodically, to check against such issues.
Working with Dexter
  1. In the output pane, enter any Unix BASH shell command in the shell type in and hit enter. It is run on Dexter's computer. Returned text will be printed below. The command you typed in will also be added to the Output pane's menu under "User Commands" should you want to execute it again.
  2. The Output pane's menu allows easy access to finding out about the ROS environment.
  3. If you click on underlined text in the Output pane, it will pop up a help window about the clicked on item. Often the help window will have buttons allowing you to insert relevant JS function calls into the Editor pane.
Series A useful way to organize knowledge is to construct lists of similar-typed concepts. DDE calls such lists series. There are over 30 series in DDE, including numbers, dates, colors, functions for math, strings, arrays, etc. The most useful functions and data structures in DDE are in a series.

The menu allows you to insert into the editor, an example item from each series. When you click on a series item in the editor, help is given on that item in the Output pane. Using the Right and Left arrow keys, you can replace a selected series item with the next or previous item in its series. The Up and Down arrow buttons replace a selected series item with an item from another series. Effectively this uses the series of series.

An example of a series is boolean. Choose it from the menu. It inserts true. Now hit the right arrow key to see additional items in the series (false, null, etc.) The left arrow goes backwards through the series.

With any series item selected, hit the down arrow. If you're on a member of the boolean series, this will replace the selection with an item from the integer series. Press the up and down arrows to go to a new series.

Each time you go to a new item from series or click on one already in the editor, help on it will be displayed in the Output pane.

Jobs A job feeds the instructions in its do_list to a robot for making things. Most users of DDE will spend most of their time creating and running jobs.

The menu gives help on Jobs and Robots.
The menu contains numerous examples of defining Jobs and how to run them. Choose Insert example 1 and read the comments to understand Job syntax. See the Reference Manual on Job for the details of specifying a job.

Robots A robot is a machine capable of performing the instructions in its instruction set. The class hierarchy of DDE Robots is:
To get a robot to perform instructions, you create an instance of its class, giving it at least a name (and in the case of Dexter, an ip_address and a port number) then create an instance of Job and give it a robot property of the robot you created. The job should also have a do_list, which is the sequence of instructions to run on the robot. When the start method is called on a Job, it sends the items on its do_list to the associated robot, sequentially, one at a time.

From a software standpoint, a robot is its instruction set. The key difference between different kinds of Robots is the difference between their instruction sets. If a robot is sent an instruction not in its instruction set, it will error, because it doesn't know how to perform that kind of instruction.

Robot is the superclass of all robot classes. It contains instructions that can run on all robots. These are control instructions because they help manage the flow of instructions in a job. Examples include: Robot.stop to end a job immediately without processing the insructions after the stop instruction, and Robot.wait_until which pauses execution of the job's instructions until the calling of the given JS function returns true.

See submenu "robot" for details about robots as well as the Reference Manual section on Robots.

TestSuite DDE has the capability to compose, run and report on Test Suites. DDE comes with several Test Suites and you can define more.

Each Test Suite has a name and an array of tests. A test is composed of an array of 1, 2, or 3 literal strings.

  1. A literal string of JavaScript code to evaluate that returns a value to be tested.
  2. The expected value of the above JavaScript code, also represented by a literal string of JavaScript.
  3. A literal string of a comment to aid in understanding the purpose or behavior of this test. If the comment starts with "known", then if the test does not pass, it will be reported on as an "known" failure. Other failures will be reported as "unknown". Often it is convenient to mark a test as "known" when you'd like to defer fixing it and just want to see the "unknown" failures.
Choose Insert Example to see a demonstation Test Suite.

You run a Test Suite by selecting it and hitting the right arrow key or choosing the Editor pane's Test/naviation/Run & sel next item menu item. Use the down arrow key to select the next level down item such as a test or even a part of a test. In each case, the right arrow executes the item and selects the next item at that level.

To create a Test Suite, type in the JavaScript source of the suite's first test, select it, and choose Selection to test. This will wrap a Test Suite around the item and fill in the test's expected value with the result of evaluating the code you have selected. If you do that again for a second JavaScript selection, it will also create a test, but this time, because the test is already in a Test Suite, it will not create a new Test Suite.

Other operations on the menu are documented with tooltips.

Debugging Most programmers spend most of their time debugging. We recommend entering just a bit of code at a time; a line or less before testing it. That way, when a bug shows up, you'll know it was in the last bit that you added. If you fail to do this, and have a large amount of code that has a bug, comment out lines incrementally and test to isolate the bug.

DDE uses an automatic syntax checker named ESLint. It indicates syntax errors in the Editor pane as soon as you enter them. There are many different styles of JS coding and different versions of JS so its hard to get such errors correct. Even if you have syntax errors indicated, your code may run fine. As a first pass though, try to fix such errors before evaling. If you can't, go ahead and evaluate your code. Perhaps runtime errors will help you fix the bug, or perhaps it will run OK and you'll know to just ignore the JS Pane syntax bug indication.

Evaling just selected portions is another way to isolate bugs. If there is a selection of JavaScript code, only that code will be evaled when you click

Another technique is to comment out code until your bug goes away.
// comments out to the end of the line.
/* comment */ Wrap JavaScript in
slash-star ... star-slash
to comment out code in the middle of a line or multiple lines. See the Editor pane's debugging menu items.

Entering debugger; into the body of a JS function definition will set a breakpoint there. When debugger; is evaluated (after you call the function) and the Chrome Developer Tools window is open, execution will pause and highlight the debugger;" statement in a copy of your source code. (To open the Chrome Developer Tools window, click right on any DDE pane and choose Inspect. If you don't see "Inspect" on the menu, read the documentation under "Installation" on "Configure Chrome".) Use the arrow buttons stepper buttons in the Developer Tools window upper right to step execution.

Wrapping console.log(...) around a complex data structure will print it out in the Chrome Developer Tools console with arrows to allow you to expand data pieces of your choice to inspect. To see the console, click right anywhere in DDE and choose "Inspect".

You can print strings into the Output pane with a call to out. Because out returns its 1st argument, you can embed it in code to see an intermediate value.
(out(2 + 3)) * 4
will print out 5, but return 20.
Print to output has items that print in a few different colors so that you can distinquish some outputs from others in a complex debugging session.

speak behaves similarly to out in that it returns its 1st arg. It can be useful in contexts where you want to know a value but don't want to look at the screen to find it. speak is on the Insert menu, under Learn Javascript/debugging.

Because JavaScript, like all popular textual programming languages, has not been designed with the "user experience" in mind, it is full of ideosyncracies that make learning how to use it require remembering a lot of "gotchas". The web has pages on common JavaScript programming errors. A good one is: https://www.w3schools.com/js/js_mistakes.asp , incomplete, but a good start.

Contact Please help us by emailing a bug report or suggestion to cfry@hdrobotic.com Take a look at the latest Release Notes and the Known Issues to avoid duplication.