How To Use Electric Imp Code Libraries And Integrations

To use any of Electric Imp’s code libraries, you need to follow these simple rules:

• To include a library in your code, add a #require statement to the top of your program, ahead of your application code. Library links are processed by impCentral™’s code compiler, not by Squirrel, which ignores any characters after a #.

• The statement must include the name of the library you want, followed by a colon and then the required version number, all within double-quote marks. For example, to add version 1.2.0 of the Twitter class to your agent code, you would write:

#require "Twitter.class.nut:1.2.0"

• Do not place a semi-colon after the #require statement.
• #require statements must include a version number. If the version is omitted, the compiler will issue a build error.
• You can add any number of libraries to your code, memory permitting.
• Do not include the same library more than once — this will generate a build error.
• Do not include wildcards in the version information (see below).
• Do not include more than 100 #require statements.

If you are experiencing errors, please check the errors table and the troubleshooting guide.

Library Versions

The Electric Imp library system employs semantic versioning. Version numbers are written in the form:

#require "Library.class.nut:x.y.z"

where x is the major version, y the minor version and z a patch version. Changes reflected in either the minor or patch values can safely be assumed not to alter the functionality and operation of the library — the changes will not break your code. However, major updates should be checked carefully as they may involve substantial changes to the library’s API that may require your own code to be modified.

For example, a small update to a library function which doesn’t change that function’s interface would be reflected by increasing the patch number. Refactoring one or more functions without changing their interfaces would warrant a new minor version. Removing a function or altering its interface to end compatibility with existing software would require a new major version.

Wildcards are not supported at this time, but you can provide a simple integer value. For example, ‘2‘ is equivalent to ‘2.0’ and ‘2.0.0’.

We suggest you mark as a favorite or follow GitHub repos of the libraries you are using to ensure you are notified when new versions of those libraries are released. The table below lists the most recent version number and will be updated as new versions are added. You can also check a library’s documentation on GitHub (links below) to get the latest version number and examine the library code, which is not displayed in impCentral.

The main list of available libraries indicates whether a given library is suitable for device code, agent code or both: some libraries must be implemented in both agent and device code, others can be used in either; check out the library’s own documentation. The list also provides a link to documentation.

Troubleshooting

If you experience an error using a library, check the following:

• Have you used the correct name in your #require statement?
• Have you included the version number? A version number is mandatory.
• Is the specified version number greater than the latest version available? This will generate an error.
• Have you #require’d the same library multiple times? Each library should be included only once.
• Have you run out of memory on the imp? Build and run a version of your code with only the libraries included — this will tell you how much space you have left for Squirrel of your own.
• Have you placed all your #require statements at the start of your code?
• Have you included wildcards in the version number? Wildcards are not supported at this time.
• If you receive a ‘Could not load code for library‘ error, check the library specifier click Build or Build and Force Restart again. If this error repeats, please post an error report in the Electric Imp Forum.

Error Messages

Error	Cause	Example
Expected space	No space between #require and the library specifier	#require"lib.class.nut:1.0"
Missing library name	No library specifier after #require	#require // Code starts here
Expected double quote	No quote marks at the start of the library specifier	#require lib.class.nut:1.0"
Unterminated library specifier	No quote marks after the library specifier	#require "lib.class.nut:1.0
Unexpected character after library specifier	Semi-colon or other character after the library specifier	#require "lib.class.nut:1.0";
Incomplete library specifier	Incorrectly named library	#require "lib:1.4"
Invalid version number	Incorrectly specified version number	#require "lib.class.nut:1.0.*"
Invalid character in library name	Mis-named library	#require "lib*.class.nut:1.0"
Duplicate require	Requesting the same library more than once	#require "lib.class.nut:1.1" #require "lib.class.nut:1.1" or #require "lib.class.nut:1.0" #require "lib.class.nut:2.0"
Require must precede code	All #require statements must come at the top of the code	myVar <- true #require "lib.class.nut:1.0"
Max requires exceeded	Requested more than 100 libraries
No such library	Non-existent library name in specifier
Could not load code for library	Error loading the library