Custom Commands

This contains all functionality needed to add/override commands to the Gecko OS Command API. More...

Modules

Types
Command types.
Macros
Command specific macros.

Functions

gos_result_t gos_cmd_start_response ( gos_cmd_result_t cmd_result, size_t size)
Begin printing a command response. More...
gos_result_t gos_cmd_write_continued_response (const void *data, size_t data_size)
Write the command response body. More...
gos_result_t gos_cmd_write_response ( gos_cmd_result_t cmd_result, const void *data, size_t data_size)
Write a complete command response. More...
gos_result_t gos_cmd_format_response ( gos_cmd_result_t cmd_result, const char *fmt,...)
Write formatted command response. More...
gos_result_t gos_cmd_format_vresponse ( gos_cmd_result_t cmd_result, const char *fmt, va_list args)
Write formatted command response. More...
gos_result_t gos_cmd_read_data (void *data, uint32_t size, uint32_t *bytes_read_ptr, uint32_t timeout_ms)
Read data from the command data bus. More...
gos_result_t gos_cmd_write_data (const void *data, uint32_t size, uint32_t *bytes_written_ptr, uint32_t timeout_ms)
Write data to command data bus. More...
gos_result_t gos_cmd_update_system_monitor (void)
Update the command thread's system monitor. More...
void gos_cmd_set_console_enabled (bool enabled)
Enable/disable the command serial console. More...
gos_result_t gos_cmd_convert_cmd_result ( gos_cmd_result_t cmd_result)
gos_cmd_result_t gos_cmd_set_bool (int argc, char **argv, bool *bool_val)
gos_cmd_result_t gos_cmd_set_flag (int argc, char **argv, uint32_t flag_mask, void *flag_ptr, uint8_t flag_width)
Utility to parse flag argument and store to given pointer. More...
gos_cmd_result_t gos_cmd_set_int (int argc, char **argv, intmax_t *int_val, intmax_t min, intmax_t max)
Utility to parse integer argument and store to given pointer. More...
gos_cmd_result_t gos_cmd_set_hex (int argc, char **argv, intmax_t *int_val, intmax_t min, intmax_t max)
Utility to parse hex string and store to given pointer. More...
gos_cmd_result_t gos_cmd_set_encoded_str (int argc, char **argv, void *buffer, size_t max_len, size_t *saved_len)
Utility to parse encoded string and save to given buffer. More...
gos_cmd_result_t gos_cmd_set_str (int argc, char **argv, char *buffer, size_t max_len)
Utility to parse string and save to given buffer. More...
gos_cmd_result_t gos_cmd_set_ip_address (int argc, char **argv, gos_ip_address_t *ip_addr)
Utility to parse string into IP address. More...
gos_result_t gos_cmd_read_write_data (size_t size, uint32_t read_timeout_ms, void *user, gos_cmd_writer_t writer, gos_cmd_write_poller_t poller)
Utility to read command bus and write data to writer argument. If system.cmd.echo = 1 then characters are echoed to the command bus. More...
gos_cmd_result_t gos_cmd_print_gpio_response ( gos_gpio_t gpio)
Print gos_gpio_t command response. More...
gos_cmd_result_t gos_cmd_print_int32_response (int32_t value)
Print 32bit signed integer command response. More...
gos_cmd_result_t gos_cmd_print_uint32_response (uint32_t value)
Print 32bit unsigned integer command response. More...
gos_cmd_result_t gos_cmd_print_str_response (const char *str)
Print string string command response. More...
gos_cmd_result_t gos_cmd_print_hex_uint32_response (uint32_t value, uint8_t padding)
Print 32bit unsigned integer as hex string command response. More...
gos_cmd_result_t gos_cmd_print_ipv4_address_response (uint32_t ip)
Print IPv4 address string as command response. More...
gos_cmd_result_t gos_cmd_print_ip_address_response (const gos_ip_address_t *ip)
Print IP address as string command response. More...

Detailed Description

This contains all functionality needed to add/override commands to the Gecko OS Command API.

Function Documentation

◆ gos_cmd_convert_cmd_result()

gos_result_t gos_cmd_convert_cmd_result ( gos_cmd_result_t cmd_result )

Converts a gos_cmd_result_t to gos_result_t

Parameters
cmd_result The result of a command, see gos_cmd_result_t
Returns
The corresponding gos_result_t of the gos_cmd_result_t

◆ gos_cmd_format_response()

gos_result_t gos_cmd_format_response ( gos_cmd_result_t cmd_result,
const char * fmt,
...
)

Write formatted command response.

This will print the command header and supplied format string

Parameters
[in] cmd_result The result of the command
[in] fmt Response formatting string
Returns
gos_result_t result of api call
Examples:
cloud/coap_demo/commands.c , cloud/dps_demo/dps_demo_cli_commands.c , cloud/dps_demo/dps_demo_cli_variables.c , cloud/mqtt_demo/mqtt_cli_variables.c , hurricane/gps/main.c , hurricane/security_camera/settings.c , system/custom_commands/main.c , system/settings_file/main.c , and test/throughput/main.c .

◆ gos_cmd_format_vresponse()

gos_result_t gos_cmd_format_vresponse ( gos_cmd_result_t cmd_result,
const char * fmt,
va_list args
)

Write formatted command response.

This will print the command header and supplied format string

Parameters
[in] cmd_result The result of the command
[in] fmt Response formatting string
[in] args Formatting string arguments
Returns
gos_result_t result of api call

◆ gos_cmd_print_gpio_response()

gos_cmd_result_t gos_cmd_print_gpio_response ( gos_gpio_t gpio )

Print gos_gpio_t command response.

Parameters
gpio gos_gpio_t value to print
Returns
GOS_CMD_SUCCESS if successfully printed, else corresponding error code, see gos_cmd_result_t

◆ gos_cmd_print_hex_uint32_response()

gos_cmd_result_t gos_cmd_print_hex_uint32_response ( uint32_t value,
uint8_t padding
)

Print 32bit unsigned integer as hex string command response.

Parameters
value 32bit unsigned integer value
padding Padding of printed hex value
Returns
GOS_CMD_SUCCESS if successfully printed, else corresponding error code, see gos_cmd_result_t

◆ gos_cmd_print_int32_response()

gos_cmd_result_t gos_cmd_print_int32_response ( int32_t value )

Print 32bit signed integer command response.

Parameters
value 32bit signed integer
Returns
GOS_CMD_SUCCESS if successfully printed, else corresponding error code, see gos_cmd_result_t

◆ gos_cmd_print_ip_address_response()

gos_cmd_result_t gos_cmd_print_ip_address_response ( const gos_ip_address_t * ip )

Print IP address as string command response.

Parameters
ip Ip address, see gos_ip_address_t
Returns
GOS_CMD_SUCCESS if successfully printed, else corresponding error code, see gos_cmd_result_t

◆ gos_cmd_print_ipv4_address_response()

gos_cmd_result_t gos_cmd_print_ipv4_address_response ( uint32_t ip )

Print IPv4 address string as command response.

Parameters
ip IPv4 as integer
Returns
GOS_CMD_SUCCESS if successfully printed, else corresponding error code, see gos_cmd_result_t

◆ gos_cmd_print_str_response()

gos_cmd_result_t gos_cmd_print_str_response ( const char * str )

Print string string command response.

Parameters
str String value
Returns
GOS_CMD_SUCCESS if successfully printed, else corresponding error code, see gos_cmd_result_t
Examples:
cloud/mqtt_demo/mqtt_cli_commands.c , network/uart_tcp_client/variables.c , and test/ethernet/main.c .

◆ gos_cmd_print_uint32_response()

gos_cmd_result_t gos_cmd_print_uint32_response ( uint32_t value )

Print 32bit unsigned integer command response.

Parameters
value 32bit unsigned integer
Returns
GOS_CMD_SUCCESS if successfully printed, else corresponding error code, see gos_cmd_result_t
Examples:
demo/uart_blaster/commands.c , and network/uart_tcp_client/variables.c .

◆ gos_cmd_read_data()

gos_result_t gos_cmd_read_data ( void * data,
uint32_t size,
uint32_t * bytes_read_ptr,
uint32_t timeout_ms
)

Read data from the command data bus.

This reads data from the data bus while a command is active.

Note
This should only be called during a custom command callback.
Parameters
data Buffer to hold read data
size Number of bytes to read
bytes_read_ptr Pointer to hold amount of data actually read
timeout_ms Time in milliseconds to wait for size bytes of data
Returns
gos_result_t result of api call
Examples:
demo/secure_element/commands.c .

◆ gos_cmd_read_write_data()

gos_result_t gos_cmd_read_write_data ( size_t size,
uint32_t read_timeout_ms,
void * user,
gos_cmd_writer_t writer,
gos_cmd_write_poller_t poller
)

Utility to read command bus and write data to writer argument. If system.cmd.echo = 1 then characters are echoed to the command bus.

There is also an optional argument to poll the available write TX buffer before writing the data.

Parameters
size Number of bytes to read
read_timeout_ms Time in milliseconds to wait for more data to be read
user User argument to pass to writer and poller callbacks
writer Data writer callback, see gos_cmd_writer_t
poller Data polling callback, see gos_cmd_write_poller_t
Returns
result of API, see gos_result_t

◆ gos_cmd_set_bool()

gos_cmd_result_t gos_cmd_set_bool ( int argc,
char ** argv,
bool * bool_val
)

Utility to parse a boolean argument and store to given pointer

Note
The second argument in argv is parsed. e.g. argv[1] is parsed.
Parameters
[in] argc Number of arguments supplied to custom command callback
[in] argv Command arguments supplied to custom command callback
[out] bool_val Pointer to hold parsed argument
Returns
GOS_CMD_SET_OK if successful, else corresponding error code, see gos_cmd_result_t
Examples:
cloud/mqtt_demo/mqtt_cli_variables.c , demo/uart_blaster/commands.c , network/uart_tcp_client/variables.c , and system/custom_commands/main.c .

◆ gos_cmd_set_console_enabled()

void gos_cmd_set_console_enabled ( bool enabled )

Enable/disable the command serial console.

When the command serial console is disabled, Gecko OS will not listen on the command bus for commands.

Parameters
[in] enabled Enable/disable serial command processing
Examples:
network/http_methods/main.c , network/tcp_multiclient/main.c , network/uart_tcp_client/main.c , system/uart/main.c , and test/uart_flow_control/main.c .

◆ gos_cmd_set_encoded_str()

gos_cmd_result_t gos_cmd_set_encoded_str ( int argc,
char ** argv,
void * buffer,
size_t max_len,
size_t * saved_len
)

Utility to parse encoded string and save to given buffer.

Note
The second argument in argv is parsed. e.g. argv[1] is parsed.
Parameters
[in] argc Number of arguments supplied to custom command callback
[in] argv Command arguments supplied to custom command callback
[out] buffer Buffer to hold decoded string argument
[in] max_len Maximum length of the decoded string
[out] saved_len Pointer to hold actual length of decoded string
Returns
GOS_CMD_SET_OK if successful, else corresponding error code, see gos_cmd_result_t

◆ gos_cmd_set_flag()

gos_cmd_result_t gos_cmd_set_flag ( int argc,
char ** argv,
uint32_t flag_mask,
void * flag_ptr,
uint8_t flag_width
)

Utility to parse flag argument and store to given pointer.

Note
The second argument in argv is parsed. e.g. argv[1] is parsed.
Parameters
[in] argc Number of arguments supplied to custom command callback
[in] argv Command arguments supplied to custom command callback
[in] flag_mask The mask of the flag to set or clear based on the boolean value of argv[1]
[in,out] flag_ptr Pointer to existing flag value
[in] flag_width The size in bytes of the flag buffer
Returns
GOS_CMD_SET_OK if successful, else corresponding error code, see gos_cmd_result_t
Examples:
demo/uart_blaster/commands.c .

◆ gos_cmd_set_hex()

gos_cmd_result_t gos_cmd_set_hex ( int argc,
char ** argv,
intmax_t * int_val,
intmax_t min,
intmax_t max
)

Utility to parse hex string and store to given pointer.

Note
The second argument in argv is parsed. e.g. argv[1] is parsed.
Parameters
[in] argc Number of arguments supplied to custom command callback
[in] argv Command arguments supplied to custom command callback
[out] int_val Pointer to hold parsed argument
[in] min Minimum value the parsed argument can be
[in] max Maximum value the parsed argument can be
Returns
GOS_CMD_SET_OK if successful, else corresponding error code, see gos_cmd_result_t

◆ gos_cmd_set_int()

gos_cmd_result_t gos_cmd_set_int ( int argc,
char ** argv,
intmax_t * int_val,
intmax_t min,
intmax_t max
)

Utility to parse integer argument and store to given pointer.

Note
The second argument in argv is parsed. e.g. argv[1] is parsed.
If the argument starts with 0x then it is parsed as a hex number.
Parameters
[in] argc Number of arguments supplied to custom command callback
[in] argv Command arguments supplied to custom command callback
[out] int_val Pointer to hold parsed argument
[in] min Minimum value of the argument
[in] max Maximum value of the argument
Returns
GOS_CMD_SET_OK if successful, else corresponding error code, see gos_cmd_result_t

◆ gos_cmd_set_ip_address()

gos_cmd_result_t gos_cmd_set_ip_address ( int argc,
char ** argv,
gos_ip_address_t * ip_addr
)

Utility to parse string into IP address.

Note
The second argument in argv is parsed. e.g. argv[1] is parsed.
Parameters
[in] argc Number of arguments supplied to custom command callback
[in] argv Command arguments supplied to custom command callback
[out] ip_addr Pointer to gos_ip_address_t to hold parsed IP address
Returns
GOS_CMD_SET_OK if successful, else corresponding error code, see gos_cmd_result_t

◆ gos_cmd_set_str()

gos_cmd_result_t gos_cmd_set_str ( int argc,
char ** argv,
char * buffer,
size_t max_len
)

Utility to parse string and save to given buffer.

Note
The second argument in argv is parsed. e.g. argv[1] is parsed.
Parameters
[in] argc Number of arguments supplied to custom command callback
[in] argv Command arguments supplied to custom command callback
[out] buffer Buffer to hold string argument
[in] max_len Maximum length of the string
Returns
GOS_CMD_SET_OK if successful, else corresponding error code, see gos_cmd_result_t
Examples:
network/uart_tcp_client/variables.c , system/custom_commands/main.c , and system/settings_file/main.c .

◆ gos_cmd_start_response()

gos_result_t gos_cmd_start_response ( gos_cmd_result_t cmd_result,
size_t size
)

Begin printing a command response.

This will print a serial command response header.

Parameters
[in] cmd_result The result of the command
[in] size The total size in bytes of the command response
Returns
gos_result_t result of api call

◆ gos_cmd_update_system_monitor()

gos_result_t gos_cmd_update_system_monitor ( void )

Update the command thread's system monitor.

For long running commands, this should be periodically invoked so the system thread's system monitor does not trigger.

Note
The command thread's system monitor has a timeout of 30s so this should be invoke ~every 15s.
Returns
gos_result_t result of api call

◆ gos_cmd_write_continued_response()

gos_result_t gos_cmd_write_continued_response ( const void * data,
size_t data_size
)

Write the command response body.

This will print the supplied response data. This should be called until the specified number of bytes from gos_cmd_start_response() have been written. e.g.:

gos_cmd_start_response (CMD_SUCCESS, 20);
gos_cmd_write_continued_response (data1, 10);
gos_cmd_write_continued_response (data2, 10);
Parameters
[in] data Response data
[in] data_size The size of command data to be written
Returns
gos_result_t result of api call

◆ gos_cmd_write_data()

gos_result_t gos_cmd_write_data ( const void * data,
uint32_t size,
uint32_t * bytes_written_ptr,
uint32_t timeout_ms
)

Write data to command data bus.

This writes data to the data bus while a command is active.

Note
This should only be called during a custom command callback.
Parameters
data Pointer to data to write
size Number of bytes to write
bytes_written_ptr Pointer to hold amount of data actually written
timeout_ms Time in milliseconds to wait for size bytes to be written
Returns
gos_result_t result of api call

◆ gos_cmd_write_response()

gos_result_t gos_cmd_write_response ( gos_cmd_result_t cmd_result,
const void * data,
size_t data_size
)

Write a complete command response.

This will print the command header and supplied response data

Parameters
[in] cmd_result The result of the command
[in] data Response data
[in] data_size The size in bytes of the command response
Returns
gos_result_t result of api call
Examples:
cloud/mqtt_demo/mqtt_cli_variables.c , demo/secure_element/commands.c , and utility/buffer_dump/main.c .