Skip to main content

Set Up Your Development Environment

important

The steps presented here are only necessary if you want to run SmartThings Lua code locally, or if you want advanced autocomplete and type hints for Lua libraries as part of your driver development workflow.

LUA_PATH​

caution

The luasocket implementation provided by lua_libs is only functional when run on a SmartThings Hub. After configuring the Lua libraries on your development machine as described below, you will be unable to run other (non-Edge) Lua code that expects the luasocket implementation when running other (non-Edge) code locally.

Before getting started, make sure you have Lua 5.3 installed on your development machine.

When running Lua code, it is necessary to have a LUA_PATH environment variable. This informs your system of where to find code that can be used in a Lua require call. For any SmartThings Edge Device Driver, it is necessary that you use the SmartThings Lua libraries to provide the functionality needed to interact with the SmartThings Platform and devices.

Your LUA_PATH should look something like:

LUA_PATH=/path/to/lua_libs-api_vX/?.lua;/path/to/lua_libs-api_vX/?/init.lua;./?.lua;./?/init.lua;;
tip

Your LUA_PATH should use the internal folder name (lua_libs-api_vX) in this library release), not a top level folder you may have created when unzipping the Lua library release and should not include the docs folder found within the library release. This ensures all SmartThings Lua library functionality is available under the same paths it will be available in when executing in the SmartThings sandbox. It also allows any working directory folders and files to be available as they will be for files provided in the src/ directory of your Edge Driver.

If you've installed luasocket using luarocks you will also need to make sure you include the luarocks include folders in this path. You can do this semi-automatically with eval $(luarocks path --append) after configuring the LUA_PATH for the lua_libs folder.

IDE and Auto-completion​

The Lua libraries are tagged with EmmyLua comments to describe the types and functions available within the libraries. These comments allow for powerful auto-completion and suggestions when working in an IDE. IDE setup is IDE-specific; we cover a few popular options below.

IntelliJ​

  1. Install the EmmyLua IntelliJ plugin (not the Lua plugin).
  2. Download the API release version from github that you will be developing with.
  3. Extract the contents of the release into the git repo directory for your project (the two extracted folders are .gitignored by default).
  4. Navigate to the EmmyLua settings and add the lua_libs-api_vX extracted directory as a "Lua Additional Sources Root".

At this point, IntelliJ will run an indexing task. The auto-completion and type hints should now be available while developing. In order to run an individual test file (the only way to "run" your driver outside the context of the sandbox on a SmartThings Hub), you need to set up the run configuration:

  1. Open the "run" configurations in your IDE.
  2. Create a new Lua Application (or edit an existing one).
  3. Set the working directory to path/to/your-driver/src.
  4. Set the entry file to path/to/your-driver/src/test/test_file.lua.
  5. Set an environment variable for the LUA_PATH described above.

From here you should be able to "run" the configuration and see the test output in your IDE.

VSCode​

  1. Install the Lua Language Server VSCode plugin.
  2. Download the API release version from github that you will be developing with.
  3. Extract the contents into the git repo directory for your project (the two extracted folders are .gitignored by default).

Alternatively, you can extract the API release to a location of your choice and add the folder path as a Workspace Library source in the Lua Language Server settings. Be sure to use the internal folder path, not a top level folder you potentially created when unzipping the release (i.e. it should not include the docs folder).