This page contains all of the information regarding the specialized FTC Alicorn Server's API and the AndroidFTC Shard. If you're not sure what Alicorn is, please take a look at our home page! If you don't know how to use it with FTC, head on over to the FTC tutorial.

General Notes

This reference assumes that the variable sdk corresponds to a valid AndroidFTC Shard reference; you can use sdk = self.require("AndroidFTC") to obtain a valid reference to the AndroidFTC Shard from within the create or update callbacks in a Javascript Shard at anytime in your code. All of the JS examples here apply to Shards written in Ruby as well.

Upon creation, the AndroidFTC Shard will automatically detect all devices specified by your hardware configuration. This means you do not need to worry about doing any extra configuration within your programs.

Additionally, you do not need to specify what you're getting or setting beyond providing the name for the device (as specified in the configuration file) - the AndroidFTC Shard will automatically figure out what you're trying to get or set, and perform the correct action and/or return the correct value.

Normalized Values

All numbers that Alicorn accepts and provides from its various methods are normalized within a range of -1 to 1. This makes it very easy for the different parts of Alicorn to talk to each other with little to no effort. For both Ruby and JavaScript code, Alicorn adds two additional methods to the built-in numerical classes that can help you when interacting with normalized values:

require, which sets a normalized value to zero if it's value is less than the specified distance from zero (either negative or positive):


    myValue = 0.19;
    myValue = myValue.require(0.18); // myValue will still equal 0.19
    myValue = myValue.require(0.20); // myValue will equal zero
    myValue = -0.9;
    myValue = myValue.require(0.29); // myValue will still equal -0.9
    myValue = myValue.require(0.98); // myValue will now equal zero

invert, which simply flips a normalized value by multiplying it by -1:


    myValue = 0.5
    myValue = myValue.invert() # myValue will now equal -0.5

Additionally, the Alicorn Bundle class exposes a variety of useful utilities for normalizing and denormalizing values. Specifically:

denormalize, which converts a normalized value from it's normalized scale of -1 to 1 to a custom scale of your choosing:


    myNormalizedValue = 0.5
    myRegularValue = Bundle.denormalize(-100, 100, myNormalizedValue) // myRegularValue will now equal 50.

normalize, which converts a denormalized value from its custom scale to a normalized scale of -1 to 1:


    myRegularValue = 50
    myNormalizedValue = Bundle.normalize(-100, 100, myRegularValue) // myNormalizedValue will now equal 0.5.

Gamepads

The AndroidFTC Shard currently provides two gamepads, named gamepad_1 and gamepad_2. You can obtain a reference to either of these via var joy = sdk.get("gamepad_1") and var joy = sdk.get("gamepad_2") respectively. Once you have a valid reference to a gamepad, there are a variety of values you can read, which are covered below:

Buttons

Simple Boolean values that are equal to true when the button is pressed and false otherwise. Their names are, for the most part, rather obvious.


    // Normal buttons.
    joy.get("a")
    joy.get("b")
    joy.get("x")
    joy.get("y")
    joy.get("back")
    joy.get("start")

    // D-Pad buttons.
    joy.get("dpad_up")
    joy.get("dpad_down")
    joy.get("dpad_left")
    joy.get("dpad_right")

    // Bumpers
    joy.get("left_bumper")
    joy.get("right_bumper")

    // This is the button at the center of the controller.
    // On an XBox 360 controller, for example, this is the big "X" button.
    joy.get("guide")

    // These buttons are triggered when their respective joysticks are "pressed" down.
    joy.get("left_stick_button")
    joy.get("right_stick_button")

Triggers

Normalized values that are equal to 1 when fully pressed and -1 when fully released.


    joy.get("left_trigger")
    joy.get("right_trigger")

Joysticks

Normalized values that are equal to 0 when at rest, -1 when pushed all the way forward and 1 when pushed all the way backward. You'll have to do some experimentation to figure out what works best for you.


    // Left joystick axes.
    joy.get("x1")
    joy.get("y1")

    // Right joystick axes.
    joy.get("x2")
    joy.get("y2")

Reading Values

Any of these joystick values can be accessed via joy.get("name_of_value"). For example, to set a motor based on the value of y1, you can do sdk.set("motor_1", joy.get("y1")).

Motors

There are two operations you can perform on a motor:

set, which will set the power of the motor to the specified normalized value:


    // Sets motor_1 to 50% power in the forward direction.
    sdk.set("motor_1", 0.5)

    // Sets motor_2 to 75% power in the backward direction.
    sdk.set("motor_2", -0.75)

get, which will return the current power setting of the motor as a normalized value:


    myNormalizedValue = sdk.get("motor_1")

Servos

There are two operations you can perform on a servo:

set, which will set the position of the servo based on the passed normalized value. A value of 1 will set the servo to its maximum rotation in degrees, a value of 0 will center it, a value of -1 will set it to its minimum rotation, and so on:


    // Sets servo_1's position in degrees to about 270.
    sdk.set("servo_1", 0.5)

    // Centers servo_2, setting its position in degrees to about 180.
    sdk.set("servo_2", 0)

get, which will return the current position of the servo (in degrees) as a normalized value:


    myNormalizedValue = sdk.get("servo_1")

Digital Channels

There are two operations you can perform on a digital channel:

set, which will set the value of the digital channel based on the passed Boolean value:


    // Turns d_channel_1 on.
    sdk.set("d_channel_1", true)

    // Turns d_channel_2 off.
    sdk.set("d_channel_2", false)

get, which will return the current value of the digital channel as a Boolean value equal to true or false:


    sdk.get("d_channel_3")

PWM Inputs and Outputs

Due to a lack of documentation, PWM I/O does not use normalized values yet.

The only operation you can perform on a PWM output is set, which will set the frequency of the PWM output based on the passed Integer value:


    sdk.set("pwm_out_1", 1500) // Sets the frequency of pwm_out_1 to 1500 nanoseconds.

The only operation you can perform on a PWM input is get, which will return the current value of the PWM input as a Double:


    sdk.get("pwm_out_4")

Analog Inputs and Outputs

Due to a lack of documentation, Analog I/O does not use normalized values yet.

The only operation you can perform on an analog output is set, which will set the output;s frequency based on the passed Integer value:


    sdk.set("analog_out_12", 200) // Sets the frequency of analog_out_12 to 200.

The only operation you can perform on an analog input is get, which will return the current value of the analog input as an Integer:


    sdk.get("analog_in_3")

Sensors

Due to a lack of documentation, many sensors do not return normalized values yet. Additionally, the return values of Sensors seems to be erratic; you may have to do some manual testing to figure out what sensors return what kind of values.

Any sensor can be accessed via sdk.get("sensor_name"), where sensor_name is the name assigned to the sensor in your robot's configuration file. While the only operation you can perform on a sensor is get, different sensors have different return values:

Optical Distance Sensors

These sensors return a normalized value, with -1 indicating an object is extremely close and 1 indicating an object is far away.

Touch Sensors

These sensors return a normalized value. On most touch sensors, this value will always be equal to either -1 or 1, but some sensors that read pressure will return different values. For Lego Touch Sensors (legacy module), the value returned by this function seems to be a Boolean.

Acceleration Sensors

These sensors return an Acceleration value indicating their Acceleration in the X, Y and Z axes:


    acceleration = sdk.get("acc_sensor_1")

    // Get the X-axis acceleration as a Double.
    acceleration.x

    // Get the Y-axis acceleration as a Double.
    acceleration.y

    // Get the Z-axis acceleration as a Double.
    acceleration.z

Compass Sensors

These sensors return a Double value representing the current direction they're pointing, in degrees.

Gyro Sensors

These sensors return a Double value representing their current rotation.

IR Seekers

These sensors return a Double value representing the direction any IR signal is coming from:

  • If a signal is coming from straight ahead, a value of 0 is returned.
  • If a signal is coming from the left, a negative value will be returned.
  • If a signal is coming from the right, a positive value will be returned.
  • If no signal is detected, a value of 0 is returned.

Light Sensors

These sensors return a normalized value, with -1 indicating almost no light and 1 indicating the maximum light possible.

Ultrasonic Sensors

These sensors return a Double value representing the current ultrasonic levels of the sensor.