ScratchLink Commands Reference Manual

Contents hide

Introduction

ScratchLink Commands are conveyed to a ScratchLink Microcontroller in data packets via serial USB or wirelessly through Bluetooth or Wifi (HTML, WebSockets or BSD Socketes). Once received, these ScratchLink commands cause the ScratchLink Firmware (program) on the ScratchLink Microcontroller to do the tasks commanded.  

Commands tell ScratchLink Controller to send data back or control peripherals like LEDs or motors etc.

ScratchLink Firmware on the ScratchLink Controller remembers configurations after it is turned off by storing in the on board memory.  It can also remember data collected from sensors until you send a command to send it up to the App i.e. Scratch etc.

There is always a live “link” between the ScratchLink Device and ScratchLink Coding Apps.  The ScratchLink system does not “compile” code that is stored on the Microcontroller but rather just runs in your Browser or AppInventor Android Phone App

Syntax

Syntax” refers to the precise format of ScratchLink Commands i.e. the “rules” of how the commands must be written so that the ScratchLink Controller will recognise them as ScratchLink Commands.  ScratchLink Commands have been developed for easy use and understanding by educational users and use everyday English language and simple rules.

ScratchLink Syntax Summary

  1. Space between values and arguments
  2. No space for command device addressing
  3. Terminating semicolon
  4. Multiple commands acceptable
  5. Set order for arguments
  6. Optional arguments
  7. Defaults apply
  8. Symbols:  “[ ]” means optional and “|” means OR 
  9. “value” means whole number input OR anything appended with “Value” eg “pinValue”
command[device] [argument1 value] [argument2 value] [argument3 on|off]; 

ScratchLink Syntax Details & Examples

1. Space between values and arguments and all successive arguments.

Correct syntax:

servo degree 90;

NOT correct syntax:

servo degree90;

2. No space for command device addressing.

Correct syntax:

servo2 degree 90;

NOT correct syntax:

servo 2 degree 90;

3. Terminating semicolon: all commands must have a semicolon “;” at the end.  

Correct syntax:

servo2 degree 90;

NOT correct syntax:

servo2 degree 90

4. Multiple sequential commands acceptable eg:

led blue; servo1 degree 90; wheels drive;

5. Set order for arguments:  arguments cannot be in any order for commands but must be in the specified order for that command.

Correct servo syntax:

servo[device] degree [value] [hold on|off];

Correct example: 

servo2 degree 90 hold yes;

NOT correct example: 

servo2 hold yes degree 90;

6. Optional Arguments:  ScratchLink syntax allows for many command arguments and values to be omitted if not required and are enclosed in square brackets “[ ….]”. 

Generic servo syntax: 

servo[device] degree [value] [hold on|off];

Correct examples: 

servo2 degree 90 hold yes;
servo2 degree 90;
servo degree 90;

NOT correct example: “degree is omitted”

servo2 90;

7. Defaults:  If an argument is optional i.e. […] and none provided, then the default prevails which is defined for each Command but usually means “all devices” for commands and “off” for arguments.

Example:  The following led command has omitted all optional arguments and values so defaults to “all led devices off” and is syntactically correct.

led;

7. Symbols:  “[ ]” means optional and “|” means OR 

Example:  The syntax for “stream” is:

stream [on|off];

This means that an argument is optional and can be either “on” or “off” if provided.  If no argument is provided, then the default applies which is “off”.  So there are 3 valid syntactically correct commands:

stream on;
stream off;
stream;

“stream;” is the same as “stream off;” and both are valid as “off” is the default argument for the stream Command.

Further General Examples:  

LED syntax:

led[device] [[color] colorValue] [pixel1...pixeln|pixel_start-pixel_end][bright value];

The following statements are all syntactically correct:

led2 color red 1 5 16 bright 50;
led2 red 1 5 16 bright 50;
led red 1-10 bright 50;
led2 red 1-10;
led2 red;
led;

System Commands

System Commands affect the way in which data is transmitted/received or act upon the ScratchLink Firmware or ScratchLink Controller System.

reset

Command Syntax:

reset;

Purpose:  resets all devices to their default state.

reboot

Command Syntax:

reboot;

Purpose:  reboots i.e. power cycle restart the ScratchLink Controller which is the same as physically unplugging the power.  Note that communication connection will be lost and will need to be established again.

stream

Command Syntax: “[ ]” means optional argument  — “|” means OR 

stream [on|off] [on|off];

Purpose:  Controls sensor data collection and streaming to ScratchLink Apps.  

First argument controls collection of data by ScratchLink Controller from sensors.

Second argument controls automatic sending of data packets i.e. “streaming” from ScratchLink Controller.

ScratchLink Controller Firmware is capable of collecting sensor data and storing for later streaming to ScratchLink App.  Data can only be streamed if it is being collected.

Default:  Data collection and streaming is “on”

Example 1:  Turn on all streaming using default.

stream;

Example 2:  Turn off all streaming with argument.

stream off;

Example 3:  Turn on sensor data collection by ScratchLink Controller but not streaming which results in sensor data being stored by ScratchLink Controller until asked for it.

stream on off;

Example 4:  Data collection on and streaming on.

stream on on;

read

Command Syntax:

read;

Purpose: Read current sensor values from ScratchLink Controller and return values.  “read” returns one set of values and is not a “stream” which is continuous.

ping

Command Syntax:

ping;

Command generates a “pong” response in the form:

{pong:time in ms}
eg. {pong:10}

Purpose: generates a response “pong” packet indicating the time since the last “ping” command. You can use this to see how fast, and at what intervals, packets are getting to the robot, over any of the connection mechanisms. You do this by calling it multiple times. For example from JavaScript:

for (i=0;i<50;++i) { await sleep(5); socket.send('ping;'); }

Example output: shows that it was about 177 seconds since the last “ping” command and thereafter 4ms and 1ms…

{pong:177877}
{pong:4}
{pong:1}
{pong:1}
{pong:1}
{pong:1}
{pong:1}
{pong:38}
{pong:2}
{pong:2}
{pong:2}
{pong:0}
{pong:1}
{pong:0}
{pong:1}
{pong:7}
{pong:9}

Configuration Commands

Config Command sets global configuration options for hardware attached to ScratchLink Controller.  It can also show what hardware is visible to the ScratchLink Controller and the current configuration.

Wifi config commands

ScratchLink currently does not support Enterprise Wifi.

If you don’t want a password when using ScratchLink as an Access Point then just leave the password blank during configuration.

Wifi passwords must be a minimum of 8 characters to a maximum of 63 characters long.

Wifi Network names i.e. SSID must be 6-32 characters.   Characters are case sensitive, thus “abc” is treated as a different name than “aBc”. Special characters (spaces, periods, dashes, underscores etc) are allowed.

Reboot required for Wifi config commands to take effect.

Please note that four communication types will work concurrently i.e. USB Serial, WebSockets, BSDsockets and HTML ports are able to be opened at the same time (if configured properly). All buffering and queuing is handled automatically by ScratchLink firmware.

Wifi on/off

Purpose: turn the wifi on/off and configure as either Access Point or Station mode. Wifi is automatically turned off if Bluetooth is enabled as they both cannot run at the same time. Conversely, BT is automatically turned off if you enable Wifi. You must reboot after turning BT/Wifi on.

Command Syntax:

wifi config enable on|off AP|station;

Access Point

Purpose: config ScratchLink as Access Point.

Default SSID = current device name (max 32 bytes), Default password=ebot(max 64 bytes), default ip=192.168.5.1(IP4 only)

Command Syntax:

wifi config AP ['SSID'] ['Password'] [ip];

Station Mode

Purpose: config ScratchLink in Station Mode.

Default SSID = none, Default password=none, uses dhcp for ip address.

wifi config station ['SSID'] ['Password'];

WebSockets

Purpose: config WebSockets.

Default is ON, Port=8080

Command Syntax:

wifi config webskt [on|off] [port];

BSD Sockets

Purpose: configure BSD Sockets.

Default is “ON”, port=8081

Command Syntax:

wifi config bsdskt [on|off] [port];

HTML

Purpose: config HTML.

Default is “ON”, port=80

Command Syntax:

wifi config html [on|off] [port];

Bluetooth

Bluetooth does not require any configuration commands but just needs to be turned on or off. Wifi is automatically turned off if Bluetooth is enabled as they both cannot run at the same time. You must reboot after turning BT/Wifi on.

bluetooth on; // enables BT & turn off Wifi- must reboot
bluetooth off; // disable BT
bluetooth info; // returns current BT status info
bluetooth; // returns current BT status info

config info

Command Syntax:

config info;

Purpose: Reports the currently configured hardware options for that ScratchLink Controller.

Example: Sending “config info;” could result in the following output report (depending on actual config of ScratchLink):

{LED_Strip:0,Enabled:1,Pin:15,Count:16,order:"RGB"}
{Ultra:0,Enabled:1,Pin:21,Max:300}
{Ultra:1,Enabled:1,Pin:17,Max:200}
{Analog:0,Enabled:1,Pin:35}
{Matrix:0,Enabled:1,MOSI:23,CLK:18,CS:5,Count:8,Format:1,Startup:2}

config confirm

Command Syntax:

config confirm on|off;

Purpose: Enables a “confirmation” return packet upon successful receipt of command. If the command is not successful the normal error will be returned. Volatile setting i.e. returns to “off” after reboot.

Example: 

config confirm on;
{OK}
led green;
{OK}
fly 57;
{error:cmd,txt:fly 57,size:7}

config echo

Command Syntax:

config echo on|off;

Purpose: echos back all commands sent. Volatile setting i.e. returns to “off” after reboot.

Example:

config echo on;
led green;

Returns:

{echo:led green}

config name

Purpose: set the ScratchLink’s device name which also be it’s SSID for Wifi AP mode. All ScratchLinks have a default name comprised of its hardware profile and partial Serial number eg. ‘eBotMax-8364-146A’

Command Syntax:

config name [name];

Examples:

config name john-robot; //  this robot is now called "john-robot"
config name; // returns the currently stored name of ScratchLink

config profile

Purpose: set the hardware profile of the ScratchLink.

Syntax to set the profile:

config profile [ebotmax|ebotpro|wii|wiiexp];

Syntax to return the currently set hardware profile:

config name;

Servo Commands

Control the position and movement of up to 8 individual servo motors (servos).

Servo motors are designed to “hold position” after they move (same as stepper motors but unlike normal DC brushed motors).  So this means that once “attached” or “on” servos will consume significant current (energy) and get hot and drain your battery faster.  To avoid this, it is best to turn servos “off” or “detach” them unless you specifically need it to “hold position” for gripping etc.

Servo motors, unlike normal brushed DC motors, are position controlled and are primarily used to move to a particular fixed position rather than continually rotate.  Servo motors normally rotate clockwise and anticlockwise through an arc of 180 degrees, however, this may be less or more depending on the manufacturing of that servo motor and its pulse input range specifications.  Some servos only rotate through 120 degrees but 180 degrees is normal.

Servo motors have an on board motor controller that responds to square wave pulses that indicate the desired servo position.  Normally, a pulse gap of 0.75 milliseconds (ms) being 750 microseconds (us) causes servo to rotate to minimum position.  Mid position is 1.5ms or 1500us and 180 degree position is 2.25ms or 2250us.  These pulse widths are the basis of the PWM command, however, ScratchLink simplifies servo control by allowing degrees or percent to be used for servo position.

servo config

Up to 8 servos can be controlled by ScratchLink and are addressed as “servo0′ to “servo7”

The config command allows the names of servos from servo0 – servo7 to be set to physical Input/Output pins on the ScratchLink Controller.

Reporting Config Info:

Command Syntax:

servo config info;

Purpose:  Reports currently stored servo configuration for all servos.

Example Report:

{Servo:0,Enabled:1,Pin:2,Low:200,High:8000,Reverse:0,Width:16,Freq:50}
{Servo:1,Enabled:1,Pin:4,Low:100,High:8000,Reverse:0,Width:16,Freq:50}

Enable & Disable Servos:

Command Syntax:  “[ ]” means optional argument and “|” means OR 

servo[device] config enable [on|off];

Purpose:  Enables individual or all servos- default is enable all servos.

Example 1:  Enable all servos.

servo config enable;

Example 2:  Disable all servos.

servo config enable off;

Example 3:  Enable servo1 only.

servo1 config enable;

Example 4:  Disable servo1 only.

servo1 config enable off;

Set Servo Config Parameters:

Command Syntax:  “[ ]” means optional argument and “|” means OR 

servoDevice config set pinValue lowPWM highPWM;

Defaults: [low] = 750us and [high] = 2250us

Example:  Attach servo0 to pin 2 , with a low PWM duty cycle of 200 and high PWM duty cycle of 8000

servo0 config set 2 200 8000;

Reverse Servo Direction:

Command Syntax:  “[ ]” means optional argument and “|” means OR 

servoDevice config reverse yes|no;

Example: Reverse the direction of servo2

servo2 config reverse yes;

Remove servo from Configuration:

Command Syntax:

servoDevice config remove;

Example:  Remove servo2 from the Configuration.

servo2 config remove;

servo on|off

Servo on or off (attach or detach):

Note on how servos work:  Servo motors are designed to “hold position” after they move (same as stepper motors but unlike normal DC brushed motors).  So this means that once “attached” or “on” servos will consume significant current (energy) and get hot and drain your battery faster.  To avoid this, it is best to turn servos “off” or “detach” them unless you specifically need it to “hold position” for gripping etc.

Command Syntax:  “[ ]” means optional argument and “|” means OR 

servo[device] [on|off];

Default:  Disable servo.

Example 1: Enable servo 3.

servo3 on;

Example 2: Disable servo 3.

servo3 off;

Example 3: Disable all servos using default.

servo;

servo pwm

Servo duty cycle or PWM (Pulse Width Modulation)

Command Syntax:  “[ ]” means optional argument and “|” means OR

servo[device] pwm value hold yes|no;

Defaults: pwm 1500us and hold noNote: Not subject to “servo reverse” command.

Example 1: Move servo 4 to position pwm (pulse width modulation) 1500us and hold position.

servo4 pwm 1500 hold yes;

Example 2: Move servo 2 to position pwm (pulse width modulation) 750us and release i.e. disable.

servo2 pwm 750 hold no;

servo percent

Set the Servo Position Using 0-100%:

Command Syntax:  “[ ]” means optional argument and “|” means OR

Default: percent 50 hold no

servoDevice percent value hold yes|no;

Example 1: Set servo 5 to its 1/4 position and release

servo5 percent 25 hold no;

Example 2:  Set servo 3 to midway and hold.

servo3 percent 50 hold yes;

servo degree

Set the Servo Position Using 0-180 degrees:

Command Syntax:  “[ ]” means optional argument and “|” means OR

servoDevice degree value hold yes|no;

Default:  degree 90 hold no

Example 1: Set servo 5 to its 1/4 position and release

servo5 degree 45 hold no;

Example 2:  Set servo 3 to midway and hold.

servo3 degree 90 hold yes;

i2c Commands

There are two i2c buses on ScrachLink, i2c bus 0 and i2c bus 1.

Default:  scan all enabled i2c busses and print the config.

i2c;

Example Results: 

{i2c:0,id:[82]}{i2c:1}

i2c config info

Command Syntax:

i2c config info;

Purpose: Reports i2c bus configuration.

Example Report:

{i2c:0,enabled:1,sda:21,scl:22,speed:400000}
{i2c:1,enabled:0,sda:12,scl:13,speed:400000}

i2c config set

Command Syntax: “[ ]” means optional argument and “|” means OR 

i2c[0|1] config set [SDA SCL Speed];

Purpose:  set the i2c bus serial data and serial clock lines to specified esp32 pins at the specified clock speed.

Default: sets i2c bus 0 to sda 21 scl 22 speed 400k AND i2c bus 1 to sda 12 scl 13 speed 400k

Example 1:  set both i2c busses to defaults.

i2c config set;

Example 2:  set i2c bus 1 sda 12 scl 13 speed 400k AND set i2c bus 0 to sda 21 scl 22 speed 100k.

i2c1 config set 14 13 400000;
i2c0 config set 21 22 100000;

i2c config enable

Command Syntax:  “[ ]” means optional argument and “|” means OR 

i2c[0|1] config enable [yes|no];

Purpose:  enable or disable i2c buses

Default i2c bus: both buses.

Default enable: yes.

Example 1:  Enable both i2c bus 1 and i2c bus 2.

i2c config enable;

Example 2:  Turn off both i2c buses.

i2c config enable no;

Example 3:  Turn off i2c bus 1 and enable i2c bus 0.

i2c1 config enable no;
i2c0 config enable yes;

i2c scan

Command Syntax:  “[ ]” means optional argument and “|” means OR 

i2c[0|1] scan;

Purpose: Report what devices are visible to ScratchLink on i2c buses.

Default:  Scan both buses and report i2c config.

Example 1: Scan both buses for devices and report.

i2c scan;

Example 2: Report devices visible on i2c bus 1.

i2c1 scan;

LED Commands

ScratchLink LEDs are WS2811, 5Volt, individually addressable, full color RGB LEDs.

ScratchLink can have a total of 6 separate LED devices with a combined total of 300 individual leds (pixels).

LED Addressing

Devices, such as LED Rings may have multiple pixels (individual LEDs) i.e. a common LED Ring has 16 x LEDs.  So, the Device is the LED Ring with 16 pixels being individual LEDs on that Device.

LED Addressing Syntax:  “[ ]” means optional argument and “|” means OR

led[Device] [[color] colorValue] [pixel1 pixel2..pixeln|pixel_start-pixel_end][bright value];

Default No Argument Case:  All devices and pixels.

Example 1:  address all led devices and make all pixels red at default brightness

led red;

Example 2:  address led device 0 only and make all pixels red at default brightness

led0 red;

Led pixels (individual leds on an led device) are addressed either as a contiguous range or non-contiguous individual pixels or a combination of both.

Contiguous range: use “pixel_start-pixel_end” i.e. hyphen between pixel start and end.

Example 3:  turn on led pixels 5 to 16 as a contiguous series to blue at half bright i.e. 12 pixels in a row.

led blue 5-16 bright 50;

Individual pixels:  space separated values, i.e. 3 5 7″

Example 4:  turn on led pixels 5 and 16 only to blue at half bright i.e. two pixels only.

led blue 5 16 bright 50;

LED config

LED Configuration Commands:  LED strips and rings come in many sizes so each LED device needs to be configured so ScratchLink knows how many individual LEDs (pixels) are present and which esp32 GPIO pin each LED device is connected to.

[pins]: refers to physical input/output pins of the ScratchLink Controller that the LED device is plugged into, being the esp32 GPIO pin number.  ScratchLink can have a maximum of 6 LED devices.

[pixels]: refers to the individual LED along that LED strip or ring i.e. pixel 2 means the 2nd led along that LED strip.

Command Syntax:  “[ ]” means optional argument and “|” means OR

led config save;

Purpose: saves the led config settings to memory on the ScratchLink Controller which remains until changed.

led config default;

Purpose: loads the stored default LED config from memory on the ScratchLink Controller..

led config info;

Purpose: Reports current LED configuration.  Example report below indicates  

{LED_Strip:0,Enabled:1,Pin:15,Count:16}
ledDevice config set pinValue countValue GRB|RGB; 

Purpose:  Sets LED device to esp32 GPIO pin and defines how many pixels (individual LEDs) and if order is GRB or RGB.

Example:  Set LED device 0 to esp32 GPIO pin 15 and define it as a 16 x LED pixel strip.

led0 config set 15 16 GRB;
ledDevice config size countValue; 

Purpose:  Defines how many pixels (individual LEDs) on LED device.

Example:  Set LED device 0 to a 16 x LED pixel strip.

led0 config size 16;
ledDevice config enable [yes|no]; 

Purpose:  Enable/disable config for LED device.

ledDevice config remove;

Purpose:  Remove config for LED device.

LED

Command Syntax:  “[ ]” means optional argument and “|” means OR

led[Device];

Purpose:  Turns specified led device OFF, with a white flash.

Example 1:  all pixels OFF on all led devices with a white flash.

led;

Example 2:  all pixels OFF on led device 1, with a white flash.

led1;

LED demo

Command Syntax:

led[Device] demo;

Purpose:  Demonstrates color display on specified LED device.

Example 1:  Demo on LED 3.

led3 demo;

Example 2:  Demo on all LEDs.

led demo;

LED flash

Command Syntax:

led[Device] [flash];

Purpose:  Quick flash of all LEDs with colour white at 100% brightness

Both [Device] and [flash] are optional which means that “led;” will flash all configured led devices.

Example 1: Flash LED device 2.

led2 flash;
led2;

Example 2: Flash all LED devices.

led flash;
led;

LED color

Command Syntax:  “[ ]” means optional argument and “|” means OR

led[Device] [[color] colorValue] [pixel1...pixeln|pixel_start-pixel_end][bright value];

Purpose:  Set color of Individual pixels i.e non-contiguous pixels OR a contiguous range (series of led pixels next to each other) or a combination of both.

Defaults:  ie. when no arguments provided.

Default colorValue is white.

Default brightValue is 100 or “bright”

Default device is all attached led devices.

Note 1: “color” is also optional i.e. the “colorValue” can be specified without being preceded by “color”- so both the following are correct:

led0 color red;
led0 red;

Note 2:  led pixels can also be turned off with the led color command by using the colorValue “black”.

Example 1:  Turn on all pixels green then pixels 10-16 off.

led green bright 100;
led black 10-16;

brightValue: either 0 to 100 or off | soft | warm | bright

colorValue: words, hex or RGB as defined below.

Preset Colors as Words: black*, white, red, green, blue, yellow, cyan, magenta, silver, grey, maroon, olive, purple, teal, navy, slateblue.

*black will cause the led to not illuminate i.e. turn off.

Color Hex string format:  Use an online hex color picker to generate your hex string for the color you want.  https://htmlcolorcodes.com/color-picker/

Color RGB format:  Red, Green, Blue format expressed in decimal i.e. each RGB needs to be 0 to 100 not 0 to 255.

Example 2:  All pixels to Red on all Led devices at 50% brightness using words or rgb or hex:

led red bright 50;
led (100,0,0) bright 50;
led #FF0000 bright 50;

Example 3:  First, third and tenth pixel on LED Device 1 to green at full brightness

led1 green 1 3 10 bright 100;

Example 4: All LED devices and  pixels to magenta color entered as decimal RGB values (0 to 100 not 0 to 255) at 1/4 brightness.

led (100,0,100) bright 25;

Example 5: All LED pixels to magenta color entered as a hex string.

led color #FF00FF;
led #FF00FF;

Example 5:  LED Device 2, all pixels warm red except 4,5,6 which are bright blue.

led2 red bright warm;
led2 blue 4-6 bright bright;

LED percent

Command Syntax:

led[Device] percent value;

Purpose:  Proportionately adjust the current luminosity of all led pixels, on the specified device, by the specified value as a percentage.  

Notes: percent value can be any whole number, however, the maximum brightness is capped at the maximum physical luminosity for the leds. 

Beware that this “led percent” command does not set the absolute luminosity or brightness as does the “bright” argument in the “led color” command.  But rather it adjusts the current brightness by the percentage value down to off or up to maximum brightness.

Example 1:  halve the current led luminosity of all pixels on all led devices i.e. 50% brightness of current luminosity.

led percent 50;

Example 2:  Double the current pixel brightness on led device 1 i.e. 200%.

led1 percent 200;

Note:  If the current led brightness was set at 100 i.e. maximum, then “led1 percent 200” will have no effect as leds are already at maximum brightness.  However, if original led brightness was set at 20 then the “led1 bright 200” will double that luminosity to 40. 

The “bright” command is absolute luminosity while “percent” is a percentage adjustment of the currently set brightness.

LED off

Command Syntax:  “[ ]” means optional argument and “|” means OR

led[Device] off [pixel_start-pixel_end];

Purpose:  turn off specified pixels or entire led device.

Default:  All LED devices and pixels off.

Note that the command “led black;” will also cause the led to turn off as black is no light.

Example 1:  Turn off LED ring 0.

led0 off;

Example 2:  Turn off pixel range 3-10 on all LED devices.

led off 3-10;

Note:  led pixels can also be turned off with the led color command by using the color value “black”.

Example 3:  Turn on all pixels green then pixels 10-16 off.

led green bright 100;
led black 10-16;

Example 4:  Turn all leds off using the color command rather than the led off command.

led black;

LED shift

Command Syntax:  “[ ]” means optional argument and “|” means OR

led[Device] shift [up|down] [count] [on|off];

Purpose:   shift all the pixels up or down, by count amount, with either wrap around on or off

Default:  shifts all leds up one with wrap on.

led shift;

Example 1:  shift all leds down 1 pixel.

led shift down;

Example 2:  shift all leds down 3 pixels.

led shift down 3;

Example 3:  shift all leds up 5 pixels with wrap off i.e. pixels at end, when shifted, will be lost not wrapped to the other end.

led shift up 5 off;

Analog Commands

Analog sensors produce a voltage which is measured by an Analog to digital converter on the Controller.

Zero Volts becomes digital 0 while 3.3 Volts becomes 1024.

analog

Command Syntax:

analog[Device];

Purpose:  Reports the value of analog device (sensor) i.e. “analog read”

Default:  No argument default is all analog devices.

Example 1:  Report the analog reading on analog device 1.

analog1;

Reports:  {Analog:549}

Example 2:  Report the analog reading on all analog devices.

analog;

Reports:  {Analog:549,1024,0} i.e. there are 3 x analog devices.

analog config info

Command Syntax:

analog config info;

Purpose:  Reports the configuration information for all analog devices

Example Report:

{Analog:0,Enabled:1,Pin:35}
{Analog:1,Enabled:1,Pin:36}

analog config pin

Command Syntax:

analogDevice config set pinValue;

Purpose:  Sets the specified analog device to specified esp32 GPIO pin.

Example:  Set analog device 2 to esp32 GPIO pin 36.

analog2 config set 36;

analog config default

Command Syntax:

analog config default;

Purpose:  set all analog devices to defaults.

analog config remove

Command Syntax:

analog config remove;

Purpose:  Remove all analog inputs.

analog config enable

Command Syntax:

analog[Device] config enable;

Purpose:  Enables analog reading from device specified.

Example:  Enable analog device 1.

analog1 config enable;

Ultrasonic Commands

ScratchLink can utilise up to four SR04 Ultrasonic Range Finders.  The default max distance is 200cm.

ultra config info

Command Syntax:

ultra[device] config info;

Purpose:  Reports configuration information of ultrasonic devices.  For example:

{Ultra:0,Enabled:1,Pin:16,Max:300}
{Ultra:1,Enabled:1,Pin:17,Max:200}

ultra config enable

Command Syntax:

ultra[Device] config enable [on|off];

Purpose:  Enables/disables ultrasonic device.

Example 1:  Enable ultrasonic device 0.

ultra0 config enable on;

Example 2:  Enable all configured ultrasonic devices.

ultra config enable on;

Example 3:  disable all configured ultrasonic devices.

ultra config enable off;

ultra config default

Command Syntax:

ultra config default;

Purpose:  Set to ultrasonics to defaults.

ultra config pin

Command Syntax:

ultraDevice config set pinValue [maxValue];

Purpose:  Sets specified ultrasonic device to specified esp32 GPIO pin and sets the maximum detection range.

Example 1:  Set ultrasonic range finder 0 to GPIO pin 17 with a maximum range of 200cm.

ultra0 config set 17 200;

ultra config max

Command Syntax:

ultraDevice config max value;

Purpose:  Sets specified ultrasonic device to maximum detection range in cm.

Example 1:  Set ultrasonic range finder 1 to a maximum range of 200cm.

ultra1 config max 200;

ultra

Command Syntax:

ultraDevice;

Purpose:  Returns the ultrasonic range finder reading in cm.

Example 1:  Read Ultrasonic device 0 and return value.

ultra0;

Returned data example:

{Ultra:[227]}

Example 2:  Return all values from all configured Ultrasonics.

ultrax;

Returned data example:

{Ultra:[227,200]}

Dot Matrix

The Dot Matrix (DM) Displays are comprised of 8×8 monochrome dot matrix modules joined together.

Supported display configurations:

“2×2”: comprising four 8×8 DM modules arranged in a 2×2 configuration.  This results in a 16×16 DM display.

“inline”:  comprising up to 8 single 8×8 DM modules in series.  So the maximum DM display size accommodated is 8 dots high by 64 dots wide (64:8).

Dot Matrix coordinates are defined as x:y with the origin being x=0 and y=0 which is the physical led dot at the bottom left hand side.  This accords with normal Cartesian geometry conventions and facilitates students plotting formula from code on the DM displays and calculating transition movements.  

Examples:

bottom left origin is 0:0

top right of a 16×16 Dot Matrix is 15:15

matrix config

Command Syntax:

matrix config set MOSI CLK CS panel_count panel_type;

Purpose:  configure the physical SPI (serial peripheral interface) pins, number of DM modules and DM display type.

Default: matrix config set 23 18 5 4 inline;

matrix config set 23 18 5 4 inline;

Notes:  default uses hardware SPI pins, however if other pins are used performance will be slower and use more resources.

“panel_count”:  2, 4 or 8 panels.

“panel_type”: “inline” or “2×2”.

Example 1: set an 8 X 1 Dot Matrix Display to hardware SPI

matrix config set 23 18 5 8 inline;

Example 2: set an 2 X 2 Dot Matrix to hardware SPI

matrix config set 23 18 5 4 2x2;

Command Syntax:

matrix config save;

Purpose:  saves Dot Matrix configuration to memory.

Command Syntax:

matrix config info;

Purpose:  Reports currently saved DM configuration.

Command Syntax:

matrix config enable yes|no;

Purpose: enables or disables the DM display.

Command Syntax:

matrix config default;

Purpose: configure a DM display using the default settings, as above.

Command Syntax:

matrix config remove;

Purpose:  removes from memory any stored DM Display configuration.

Command Syntax:

matrix config size panel_count;

Purpose:  configure the DM Display with specified number of DM modules.

Command Syntax:

matrix config type panel_type;

Purpose:  configure the DM Display with specified DM module orientation i.e. “panel_type” being “inline” or “2×2”.

Command Syntax:

matrix config startup startup_number;

Purpose:  runs startup animation- “0” is none.

matrix clear

Command Syntax:

matrix clear;

OR

matrix;

Purpose:  turns all the LED dots off i.e. clears the display of all illumination

matrix flash

Command Syntax:

matrix flash;

Purpose:  Quickly turns all the LED dots on then clears i.e. flashes all LED dots.

matrix demo

Command Syntax:

matrix demo [value];

Purpose: displays a demonstration animation- currently 1 to 2.

Example 1: Display demo 2 on the Dot Matrix display.

matrix demo 2;

Example 2: Display default demo on the Dot Matrix display.

matrix demo;

matrix random

Command Syntax:

matrix random;

Purpose:  Draws random lines in an infinite loop until commanded otherwise.

matrix up|down|left|right

Command Syntax:

matrix up|down|left|right;

Purpose:  shifts image one pixel in the specified direction.

Example 1:  Shift image 1 pixel to the left.

matrix left;

matrix bright

Command Syntax:

matrix bright value;

Purpose: sets the luminosity (0-100) or brightness or the pixels that are “on”.

Example 1:  Set the image to half brightness

matrix bright 50;

matrix point

Command Syntax:

matrix point x y on|off;

Purpose:  Turns an individual LED dot on or off at the specified coordinate

Example 1:  turn on dot at middle of a 16×16 DM.

matrix point 7 7 on;

Example 2:  turn on origin of any size DM i.e. the 1st dot in x and y.

matrix point 0 0 on;

Example 3:  turn on the 2nd dot in and up of any size DM.

matrix point 1 1 on;

matrix line

Command Syntax:

matrix line x1 y1 x2 y2;

Purpose:  Draws a line i.e. illuminates the dots between the two specified coordinates. 

Example 1:  Draw a line from the origin to midpoint of a 16×16 DM.

matrix line 0 0 7 7;

matrix rectangle

Command Syntax:

matrix rectangle x1 y1 x2 y2 on|off;

Notes: The rectangle fill can be either “on” or “off” i.e. last parameter.

Example 1:  Draw a non-filled rectangle on the periphery of a 16×16 DM.

matrix rectangle 1 1 16 16 off;

Example 2:  Draw a filled rectangle one dot in from the boundary on a 16×16 DM

matrix rectangle 2 2 15 15 on;

matrix text

Command Syntax:

matrix text speed 'your text';

Purpose:  Scrolls specified text from right to left at the specified speed.

speed can be 0-9999 (milliseconds between updates) or “slow”, “medium”, “fast”

Example 1:  Scroll text “medium” speed.

matrix text medium 'This is my message to scroll at medium speed';

Example 2:  Scroll text with 100 milliseconds between updates.

matrix text 100 'This message refreshes every 1/10th of a second';

matrix show

Command Syntax:

matrix show;

Purpose: Illuminates or shows the default 0 image.

matrix show value;

Purpose: Shows stored image number [n] 

where value = 0-999 i.e. 1000 images can be stored on ScratchLink.

OR

where value = hex string that must start with 0x and followed by 64 hex bytes

Example 1: Show stored image # 25 on the Dot Matrix

matrix show 25;

Example 2: Show image hex string “0x000F102040000301000018180000000000F00804020000000000303000000001”

matrix show 0x000F102040000301000018180000000000F00804020000000000303000000001;

matrix save

Command Syntax:

matrix save;

Purpose:  Saves current image as image 0.

matrix save value;

Purpose:  Saves current image as image number [n].

where value = 0-999 i.e. 1000 images can be stored on ScratchLink.

OR

where value = hex string that must start with 0x and followed by 64 hex bytes

Example:  Save currently displayed image on DM as image 10.

matrix save 10;
matrix save value hex_string;

Purpose:  Saves specified hex string as specified image.

Example:  Save hex string 0x000F102040000301000018180000000000F00804020000000000303000000001 as image 15

matrix save 15 0x000F102040000301000018180000000000F00804020000000000303000000001;

Matrix Get

Command Syntax:

matrix get [num];

Purpose: Reports the hex code for the stored Dot Matrix bitmap for given file number.

Example: What is the hex code for the image stored at file location 27?

matrix get 27;
Will return
{mtx:[27,0×0080804040402020101010080804040000000000000000000000000000000000]}

Wheels Commands

ScratchLink ebots utilise stepper motors for drive power to the wheels and will respond to the “wheels” commands which have functionality specifically designed for a mobile robot.The scratchlink and eBot stepper motor driver can control two bipolar stepper motors up to to 3 Amps.  eBot uses two Nema17 bipolar stepper motors producing 45 Ncm torque with 2 Amps.

wheels config

ScratchLink firmware will auto-detect the ScratchLink stepper controller and configure it to default and enable it without any user input.  

ScratchLink has an inbuilt 3 speed automatic software “gearbox” that automatically provides the highest torque for the selected speed by utilising microstepping of the stepper motors that drive the wheels.  This function is automatically enabled but can be disabled so that only single stepping is used.

The following configuration commands are available.

Command Syntax:

wheels config info;

Purpose:  Reports currently stored wheels configuration.

Command Syntax:

wheels config enable [on|off];

Default: On

Purpose: Disable or enable wheels configuration.

Command Syntax:

 wheels config save; 

Purpose: saves wheels settings to configuration.

Command Syntax:

 wheels config default; 

Purpose: set wheels configuration back to default settings.

Command Syntax:

 wheels config auto [on|off]; 

Purpose: turns the microstepping based auto gearbox on or off

Command Syntax:

 wheels config set [circ][track][auto_off_ms]; 

Purpose: set the wheels configuration where:

“circ” is the circumference of the wheels in mm
“track” is the distance in mm between the vertical center of the two wheels in mm
“auto_off_ms” is how many msecs that the steppers will stay on if they aren’t doing anything (default is 3000).

Wheels Off & Brake

Command Syntax:

wheels off;
wheels; 

Purpose:  Turn off all power to the wheels – this is the same as off with coast.

Command Syntax:

wheels off brake;

Purpose:  Stop the wheels with a brake i.e. wheels “hold” their position

Note: wheels will brake and “hold” their position for 2 seconds (unless issued another command)

Command Syntax:

wheels off coast;

Purpose:  Stop the wheels with a coast i.e. wheels do not “hold” their position but are in “free wheel mode”

Wheels Distance Counter

The wheels distance counter is configured for the wheel diameter and calculates the theoretical distance traveled for the robot (ignoring slippage and obstructions). The distance counter calculates net distance so is increase when the robot moves forward and is reduced when the robot moves backwards for each wheel and can be “read” and “reset”.

Command Syntax:

wheels zero;

Purpose:  Zero the distance counter for both wheels.

Command Syntax:

wheels read;

Purpose:  Reports total distance traveled by each wheel since last it was set to zero and if wheels are going (“0” means not moving while “1” means wheels are going)

Example report: {Wd: [247.1,230.4,1]} 

Wheels Distance

The purpose of the “wheels distance” commands is to move the robot based on travel distance.

Note: Distance units are cm and can have one decimal point eg 3.1cm

Command Syntax:  “[ ]” means optional argument and “|” means OR

Command Syntax:

wheels distance [distance_cm];Purpose: both wheels move [distance_cm] at full speed.

Example: move both wheels forward 3.1cm

wheels distance 3.1;

Command Syntax:

wheels distance [lhs_cm][rhs_cm] [speed] [brake];

where:

  • [lhs_cm][rhs_cm] are distance for left and right wheels
  • [speed] are whole numbers from 0-100-
  • [brake] is either “on” for stop with brake (holds for 2 seconds automatically) or “off” for stop with coast

Purpose: wheels move desired distance at speed (optional) with either brake or coast (optional).
Example: move both wheels forward 3.1cm at full speed with coast after stop

wheels distance 3.1;
wheels distance 3.1 3.1 100 off;

Example: move left wheel 10cm and right wheel 9cm at half speed with a brake stop

wheels distance 10 9 50 on;

Wheels Speed

he purpose of the “wheels speed” command is to move the robot based on travel speed subject to travel time and with or without brake stop.

Note:  “[ ]” means optional argument and “|” means OR

Command Syntax:

wheels speed [lhs_speed] [rhs_speed] [time] [brake];

where:

  • [lhs_speed][rhs_speed] are speed for left and right wheels from -100 to 100 (default is 100 i.e. full speed)
  • [time] is duration for travel in seconds which can have a single decimal value (default is indefinite)
  • [brake] is either “on” for stop with brake (holds for 2 seconds automatically) or “off” for stop with coast (default is “off” i.e. coast stop)

Example: move both wheels forward at half speed indefinitely with a coast stop i.e. no brake

wheels speed 50 50 off;  OR  wheels speed 50;

Note: to stop the wheels issue “wheels off;” OR “wheels off coast” OR “wheels off brake” as desired.

Example: move left wheel at half speed and right wheel at full speed for 2 seconds with a brake stop

wheels speed 50 100 2 on;

Wheels RPM

Purpose: move the robot based on travel speed defined as revolutions per minute (rpm) subject to travel time and with or without brake stop.

Note:  “[ ]” means optional argument and “|” means OR

Command Syntax:

wheels rpm [lhs_rpm] [rhs_rpm] [time] [brake];

where:

  • [lhs_rpm][rhs_rpm] are rpm for left and right wheels from -150 to 150 (default is 150 i.e. full speed)
  • [time] is duration for travel in seconds which can have a single decimal value (default is indefinite)
  • [brake] is either “on” for stop with brake (holds for 2 seconds automatically) or “off” for stop with coast (default is “off” i.e. coast stop)

Example: move both wheels forward at half speed i.e. 75 rpm indefinitely with a coast stop i.e. no brake

wheels rpm 75 75 off;  OR  wheels rpm 75;

Example: move left wheel at half speed (75 rpm)  and right wheel at full speed (150 rpm) for 2 seconds with a brake stop

wheels rpm 75 150 2 on;

Wheels Circle

Purpose: turn the robot in a defined circle for a specific arc segment, at a defined speed with or without brake stop.

Note:  “[ ]” means optional argument and “|” means OR

Command Syntax:

wheels circle [degrees] [radius] [speed] [brake];

where:

  • [degrees] defines the traveled arc segment of the outer wheel
  • [radius] of the circle to be traveled to the outer wheel in cm
  • [speed] of the outer wheel from -100 to 100
  • [brake] is either “on” for stop with brake (holds for 2 seconds automatically) or “off” for stop with coast (default is “off” i.e. coast stop)

Defaults: 50cm radius for 90 degrees at full speed

Example using defaults: turn 90 degrees with a radius of 50 cm at full speed

wheels circle;

Example: move both wheels forward at half speed i.e. 75 rpm indefinitely with a coast stop i.e. no brake

wheels circle

Example: turn 180 degrees at 1/4 speed with 30 cm radius with a brake stop

wheels circle 180 30 25 on;

Wheels Drive

Purpose: move the robot based on drive commands at desired speed with optional conditions of either distance or time.

Note:  “[ ]” means optional argument and “|” means OR

Command Syntax:

wheels drive [direction] [speed] (distance [cm] | time [sec]) [brake];

where:

  • [direction] can be forward [f], right turn [rt], left turn [lt], hard right turn [hrt], hard left turn [hlt], backwards [b]
  • [speed] of the fastest wheel from -100 to 100
  • [cm] is distance in cm
  • [sec] is time in seconds
  • [brake] is either on or off after stop (default is no brake stop)

Defaults: forward at full speed
Example using defaults: drive forward at full speed

 wheels drive;  

Example: drive forwards with a hard right turn at half speed

wheels drive hrt 50;

Example: reverse hard right turn at half speed

wheels drive hrt -50;

Example: reverse hard right turn at half speed for a distance of 30cm (measured by LHS wheel)

wheels drive hrt -50 distance 30;

Example: reverse hard right turn at half speed for 10 seconds.

wheels drive hrt -50 time 10;

Example: reverse hard right turn at half speed for 10 seconds with a brake stop.

 wheels drive hrt -50 time 10 on; 

Black/White Processing

Black/White (bw) processing is a firmware function i.e. it operates on the ScratchLink Hardware itself rather than calculated in the browser by Scratch or JavaScipt.

Purpose: To rapidly detect changes between Black/White under the colour sensors to enable rapid halting of the robot and improve response time reactions to lines while moving quickly and thus avoiding “driving through” black lines such as line following or Sumo. Dramatically improves robot reaction time to black lines.

How it works: The values for the “Black” or “White” surface under the colour sensor can be “captured” and used to quickly send a data packet to the browser (over wifi/BT) and additionally the robot can automatically be stopped during when over “Black” while it waits for the data to go up to the browser and instructions to come back (this can take up to 100ms depending on how it is configured).

How to use BW Processing

1. “Scan” either your typical “Black” or “White” surface by the placing eBot’s colour sensors over your surface then call:

bw scan black;  OR  bw scan white;  OR don't call and use default

2. Turn on bw processing and optionally turn on auto stop.

bw [on|off] [on|off];

Examples explained:

bw on on;  // turns on bw processing and autostop on black
bw on off; // turns on bw processing but autostop is off
bw on; // same as "bw on off;"
bw off on; // NOT allowed

3. Utilise returned bw data packets which are put at the front of eBot’s packet que so they get to the browser and your Scratch or JS program as quickly as possible.

Once bw processing is turned on then data packets are automatically generated upon any “state change” of the colour sensors. Returned data packet when bw processing is on:

{BW:[LHS Black?, RHS Black?, Just done autostop?]};
///where data values are 1 for "yes" or 0 for "no" eg.///
{BW:[0,0,0]}; // LHS sees white, RHS sees white, not just done stop
{BW:[1,0,1]}; //LHS sees black, RHS sees white, just done autostop

HTML Commands

There are two commands you can send over the html link to scratchlink

If there is no data you will get an empty packet back ie {} 

/readjson
ie 
http://127.0.0.1:42429/readjson
which will return the latest data from the attached device ie 

{ts:15000,Ultra:[227,200],Analog:[655,0],WiiCC:[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0]} 

and /readjsonall

which will return all the data packets since the previous readjsonall or readjson.
ie http://127.0.0.1:42429/readjsonall

ts:87600,Ultra:[227,200],Analog:[661,0],WiiCC:[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0]} {ts:87700,Ultra:[226,200],Analog:[656,0],WiiCC:[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0]} {ts:87800,Ultra:[227,200],Analog:[639,0],WiiCC:[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0]} {ts:87900,Ultra:[226,200],Analog:[653,0],WiiCC:[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0]} 

Note the Wii are now NunC0 and NunC1 or WiiCC0 and WiiCC1eg NunC1:[0,0,0,0,239,81,64]

The i2c color sensor is: RGB0:[50,37,19,209,9,5],RGB1:[513,411,139,967,103,5]

The compass is {cmp:244} being whole numbers from 0 to 360.

Note that matrix get packets will come back between normal data packets in their own packets.

matrix show 0x1000000000000000200000000000000030000000000000004000000000000005;

then 


matrix save; // which will save it as the deault image 0.

Then 

matrix get; // ie get the default one, you could use a number after it

will return 

{mtx:[0,0×1000000000000000200000000000000030000000000000004000000000000005]}

If you are streaming it will come back between two of the stream packets..

For the nunchuck – 

NunC:[0,0,0,0,195,163,91]

where the values are – [joyx, joyy, cbutton, zbutton, gyrox, gyroy, gyroz]

For the classic controller –

WiiCC:[100,78,-100,12,0,0,0,0,1,1,1,1,0,0,0,0,0,0,0]

where the values are –
[left joys x,y,
right joys x,y,
Diamond- Y,A,X,B,
Trigger – LHS top, RHS top, lsh bottom, rhs bottom,
Pad – left,right,up,down,
control – select,home,start]

Joysticks are all scaled -100 to 100.
You must power cycle if swapping between the two controllers (we can change that later if required).

RGB0:[red,green,blue,white,AmbientLight,color_detected]

The light sensor in scratch is taken from “ambientLight”

with color_detected being 0 to 6 meaning:

COLOR_NONE =0;
COLOR_WHITE = 1;
COLOR_RED = 2;
COLOR_GREEN = 3;
COLOR_BLUE = 4;
COLOR_BLACK = 5;
COLOR_SILVER = 6; 

Returned Data

For the nunchuck – 

NunC:[0,0,0,0,195,163,91]

where the values are – [joyx, joyy, cbutton, zbutton, gyrox, gyroy, gyroz]

For the classic controller –

WiiCC:[100,78,-100,12,0,0,0,0,1,1,1,1,0,0,0,0,0,0,0]

where the values are –
[left joys x,y,
right joys x,y,
Diamond- Y,A,X,B,
Trigger – LHS top, RHS top, lsh bottom, rhs bottom,
Pad – left,right,up,down,
control – select,home,start]

Joysticks are all scaled -100 to 100.
You must power cycle if swapping between the two controllers (we can change that later if required).