The sequence editor is an easy to use tool for automating FarmBot operations. However, advanced users who are familiar with computer programming concepts may opt for a more advanced interface. For these users, we provide several methods to insert Lua code fragments directly into sequences:

By using the Lua command (learn more).
By using the Assertion command (learn more).
By adding a formula to a Move command input field (learn more).

The table below shows the features available to each of the methods:

Command	Executes Lua code	Variable access	Recovery options
Lua
Assertion
Move formula inputs

All of the available Lua functions are listed below. Additionally, you may access most of the functions available in the Lua 5.2 standard library. If you have questions about the available functions or would like us to make new features available, please let us know in the FarmBot Forum.

For examples of how to use Lua to send data to third party APIs like chat apps, see our Slack chat app tutorial

coordinate()

Generate a coordinate for use in location-based functions such as move_absolute and check_position.

coordinate(1.0, 20, 30)
-- Returns:
-- {x = 1.0, y = 20,  z = 30}

check_position()

check_position(coordinate, tolerance) returns true if the device is within the tolerance range of coordinate.

if check_position({x = 0, y = 0,  z = 0}, 1.23) then
  send_message("info", "FarmBot is at the home position")
end

home = coordinate(0, 0, 0)
if check_position(home, 0.5) then
  send_message("info", "FarmBot is at the home position")
end

emergency_lock()

Emergency locks the Farmduino microcontroller, preventing motor and peripheral usage. Some features, such as send_message, are still available while emergency locked.

-- Lock the device:
emergency_lock()

emergency_unlock()

Unlock a previously locked device.

-- Unlock the device:
emergency_unlock()

env()

Store and retrieve key/value pairs to disk. This information will be stored on the device SD card and eventually synced with your web app account.

key and value must be strings. No other values are allowed. Values may not exceed 1,000 characters in length.

To create or update a key/value pair:

env("key", "value")

-- Example:
env("MY_API_TOKEN", "abc123")

To retrieve a previously stored value:

env("key")
-- Returns `nil` if no value is found.

-- Example:
api_token = env("MY_API_TOKEN")
if api_token then
  send_message("info", "Token value is " .. api_token)
else
  send_message("info", "Value not found")
end

fbos_version()

Returns a string representation of FarmBot OS’s version.

fbos_version()

find_axis_length()

Determines the length of an axis using stall detection, rotary encoders, or limit switch hardware.

-- Single axis:
find_axis_length("x")
find_axis_length("y")
find_axis_length("z")

-- Every axis in the order Z, Y, X:
find_axis_length()
find_axis_length("all")

find_home()

Finds the 0 (home) position for an axis using stall detection, rotary encoders, or limit switch hardware.

-- Single axis:
find_home("x")
find_home("y")
find_home("z")

-- Every axis in the order Z, Y, X:
find_home("all")
find_home()

firmware_version()

Returns a string representation of the firmware version on the Farmduino/Arduino.

firmware_version()

get_device()

Fetch device properties. This is the same device resource found on the API.

-- Every property:
get_device()

-- Single property:
get_device("name")

get_fbos_config()

Fetch FarmBot OS configuration properties. This is the same FarmBot OS configuration resource found on the API.

-- Fetch all properties:
get_fbos_config()

-- Fetch single property:
get_fbos_config("disable_factory_reset")

get_firmware_config()

Fetch firmware configuration properties. This is the same firmware configuration resource found on the API.

get_firmware_config()
get_firmware_config("encoder_enabled_z")

get_position()

Return a table containing the currrent X, Y, Z value of the device.

position, error = get_position()

if error then
  send_message("error", error, "toast")
else
  message = "Y position is " .. position.y
  send_message("info", message)
end

go_to_home()

Move to the 0 (home) position of a given axis.

-- Single axis:
go_to_home("x")
go_to_home("y")
go_to_home("z")

-- Every axis:
go_to_home("all")
go_to_home()

http()

Performs an HTTP request. Example:

response, error = http({
  -- REQUIRED
  url="https://my.farm.bot/api/farmware_envs",
  -- OPTIONAL. Default value is "get".
  method="POST",
  -- OPTIONAL. Only strings and numbers.
  headers={
    Authorization="bearer eyJ....4cw",
    Accept="application/json"
  },
  -- OPTIONAL. Must be a string. Use included JSON lbrary for
  --           JSON APIs
  body=json.encode({
  })
})

if error then
  -- The `error` object is reserved for non-HTTP errors.
  -- Example: missing URL.
  -- `error` will be `nil` if no issues are found.
  send_message("info", "Unknown error: " .. inspect(error))
else
  -- The `response` object has three properties:
  --   `status`: Number              - Response code. Example: 200.
  --   `body`: String                - Response body. Always a string.
  --   `headers`: Map<String, String> - Response headers.
end

inspect()

Alias for json.encode.

json.decode()

Converts a JSON encoded string to a Lua table:

result, error = json.decode('{"foo":"bar","example":123}')
-- { foo="bar", example=123 }

json.encode()

Converts a Lua variable into stringified JSON.

result, error = json.encode({ foo="bar", example=123 })
-- => '{"foo":"bar","example":123}'

move_absolute()

Move to an absolute coordinate position.

move_absolute(1.0, 2, 3.4)
-- Alternative syntax:
move_absolute(coordinate(1.0, 20, 30))

new_sensor_reading()

Plot a sensor reading point on the sensors panel. Please note that calling new_sensor_reading() does not perform any readings, it only records a value. See also: read_pin()

DIGITAL = 0
ANALOG = 1
position, error = get_position()

i = 0
while (i < 10) do
  i = i + 1
  new_sensor_reading({
    x=position.x,
    y=position.y,
    z=position.z,
    mode=ANALOG,
    pin=0,
    value=(math.random() * 1024)
  })
end

read_pin()

read_pin(pin_num, mode?) reads a pin when given a pin number and read mode ("analog" or "digital"). Defaults to "digital" if no mode is given:

pin23 = read_pin(23) -- Digital is the default mode
pin24 = read_pin(24, "digital")
pin25 = read_pin(25, "analog")

read_status()

read_status(...path?) reads the entire device state tree into memory.

The device state tree contains numerous properties that are relevant to the device’s operation. It is the same state tree seen in FarmBotJS.

-- Provide a path to the property you are interested in:
read_status("location_data", "raw_encoders", "x")

-- Alternative syntax:
status = read_status().location_data.raw_encoders.x

send_message()

send_message(type, message, channels?)

The first required parameter is a log type, which is one of the following string values: "assertion", "busy", "debug", "error", "fun", "info", "success", "warn"

The second required parameter is the message, which may be either a string or a number.

The third parameter is optional. It can be a single string or an array of strings. The strings must be one of the following: "ticker", "toast", "email", "espeak"

-- Send a message to the default channel ("ticker"):
send_message("error", "Hello")

-- Send a message to a single channel:
send_message("success", "You've got mail!", "email")

-- Send a message to multiple channels:
send_message("info", "All systems running.", {"toast", "espeak"})

take_photo()

KNOWN BUG: Take photo may return errors asyncronously, which may lead some developers to believe the take_photo operation has succeeded when it actually fails in the background.

Takes a photo using the device camera. Returns nil on success. Returns an error object if capture fails.

error = take_photo()

if error then
  send_message("error", "Capture failed " .. inspect(error))
else
  send_message("info", "Capture OK")
end

update_device()

Update device properties. This is the same device resource found on the API.

update_device({key = "value"})
update_device({name = "Test Farmbot"})

update_fbos_config()

Update FarmBot OS configuration properties. This is the same FarmBot OS configuration resource found on the API.

update_fbos_config({key = "value"})
update_fbos_config({disable_factory_reset = true})

update_firmware_config()

Update firmware configuration properties. This is the same firmware configuration resource found on the API.

update_firmware_config({key = "value"})
update_firmware_config({encoder_enabled_z = 1.0})

variable()

BETA

The variable() function is not yet available to Move input formuals or the Assertion command.

If the sequence executing the Lua command contains a sequence variable, you can access its content by calling the variable() function:

-- Assumes you are inside of a function that has a variable:
x_pos = variable().x
send_message("info", x_pos, {"toast"});

What’s next?

Lua Examples
Advanced FarmBot customization via Lua scripts.

FarmBot Developer

Documentation

Python

How it works

Other Resources

Lua

Page Contents

coordinate()

check_position()

emergency_lock()

emergency_unlock()

env()

fbos_version()

find_axis_length()

find_home()

firmware_version()

get_device()

get_fbos_config()

get_firmware_config()

get_position()

go_to_home()

http()

inspect()

json.decode()

json.encode()

move_absolute()

new_sensor_reading()

read_pin()

read_status()

send_message()

take_photo()

update_device()

update_fbos_config()

update_firmware_config()

variable()

BETA

What’s next?