Skip to content

How to write module driver for Wio Link?

Jump to bottom
Jack Shao edited this page Dec 4, 2015 · 11 revisions

The Scene

A compatible module driver can be scanned by the server and be integrated into the online compilation service. The driver contributed by seeedstudio is written on top of suli - which is the HAL for various hardwares, here it's for esp8266 wifi soc. The bottom level of HAL is based on the esp8266 Arduino project, thank you igrr and the contributors for that project.

Suli is currently in beta version and for internal usage, thus lack of documentations. It's easy to understand but if you feel not, you can definitely use the official SDK provided by espresso. The version of espresso SDK used by Wio Link is 1.4.1.

The only difference between writing a Wio Link compatible driver and writing an Arduino compatible driver is that, you need to follow some rules to write the header file. It is for the scanning script to process it correctly. If you want to know more about the scanning process, please have a look at the "scan_drivers.py" source file.

Convention

  • Detailed file header with author email and license declaration
  • MIT License
  • Detailed function comment
  • Functions that serve for Constructor should start with the captial letter with Camel convention, e.g. MyClass
  • Functions and variables would be small cases concated with underscore, e.g. my_funtion, my_var
  • Indent with 4 spaces, no TAB
  • The best to use the standard data type with explicit length, e.g. int16_t, uint32_t

Rules for Writing Compatible Module Driver

  • File and directory naming

    • Small cases concated with underscore, if the driver is for grove modules, start with "grove_", e.g. grove_3axis_acc.h / grove_light_sensor.h / grove_nfc.h / grove_nfc (dir)
    • Recommend only one .h file, if more than one, the .h file end with "_class.h" will be searched first

  • Rules for .h file (see grove_example/grove_example.h for an example)

    • Must include a comment line that starts with "//GROVE_NAME" to specify the module name (even not a grove module), e.g. "//GROVE_NAME the-module-name"
    • Must include a comment line that starts with "//IF_TYPE" to specify the interface type, the value can be one of {GPIO, PWM, ANALOG, I2C, UART}, e.g. "//IF_TYPE GPIO"
    • Must include a comment line that starts with "//SKU" to specify a unique id of this module. For grove modules, this should be the sou number, while for other modules this can be a UUID string.
    • Must include a comment line that start with "//IMAGE_URL" to specify the URL of an image for this module.
    • Must declare a class for this module
    • The only parameter(s) of the construct function should be hardware related, e.g. PIN number
    • The parameters' name of the construct function should follow the rule, refer to the next section "Parameters name of constructor"
    • All exposed output functions must be public and starts with "read_"
    • All exposed input/config functions must be public and starts with "write_"
    • All exposed input/output functions must return bool type
    • Private or internal functions MUST NOT start with "read_" or "write_"
    • All outputs of read_ functions must be returned with pointer data type, no limit to numbers.
    • read_ functions can be called with parameters too, the discrimination of input and output parameters is whether or not it's a pointer data type. Pointer type is for output parameters.
    • The number of parameters for write/config functions MUST NOT exceed 4
    • The number of input parameters for read_ functions MUST NOT exceed 4
    • The data type of the parameters of expose functions should be one of {int, float, int8_t, uint8_t, int16_t, uint16_t, int32_t, uint32_t} and their pointer type. The pointer type is for outputting while the non-pointer type is for inputing (e.g. parameters for write_ functions and input parameters for read_ functions)
    • write_ functions support "char *" input parameters, but the limit is, only one "char *" parameter and MUST BE THE LAST PARAMETER and max length is 256
    • The format of event binding functions must be "EVENT_T * attach_event_reporter_for_[event_name](CALLBACK_T)", so that the functions can be scanned by the script
    • If an exposed function returned false, the error message can be collected. The error collection is done by the framework calling "char *get_last_error()" to get the string pointer. To describe the error message, you can declare a class member "char *error_desc" and assign a string to error_desc. And simply implement get_last_error like this: char *get_last_error() { return error_desc; };

  • Parameters name of constructor

    • GPIO module: the constructor parameter signature is (int pin)
    • ANALOG module: the constructor parameter signature is (int pin)
    • I2C module: the constructor parameter signature is (int pinsda, int pinscl)
    • UART module: the constructor parameter signature is (int pintx, int pinrx)

  • Comment for read_/write_ function

    • The function comment can be scanned into documentation which will be displayed in an API reference page
    • The function comment include two section, 1st is general description for this function, 2nd part is the description for parameters
    • The format of comment should be as following:
      • comment starts with "/**" and end up with "*/"
      • general description can be multiple lines
      • @para description should finished in one line
/**
 * general description here
 * multiline description is allowed
 * 
 * @param total_led_cnt - the total count of this strip, max: 60
 * @param rgb_hex_string - a rgb value in hex format, e.g. AA55CC (without # or 0x)
 * 
 * @return bool 
 */

Example

https://github.com/Seeed-Studio/Wio_Link/tree/master/grove_drivers/grove_example

How to self test?

###Step 1. Scan all the drivers into a database file.

Steps:

  • python envirenment is needed
  • cd project root dir (where the script scan_drivers.py lies)
  • run "python ./scan_drivers.py" in your shell or cmd line

###2. Test building

  • python envirenment needed
  • gnu make tools needed
  • gnu arm gcc cross-compile tools needed, and modify the path in Makefile if they're not in your PATH env
  • edit the yaml file in users_build/local_user_000000000, examples here
  • run "python ./build_firmware.py" in your shell or cmd line - Check if error happens, the errors from compiling will be printed.
Clone this wiki locally