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_resultThe 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_resultThe result of the command
[in]fmtResponse 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_resultThe result of the command
[in]fmtResponse formatting string
[in]argsFormatting 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
gpiogos_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
value32bit unsigned integer value
paddingPadding 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
value32bit 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
ipIp 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
ipIPv4 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
strString 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
value32bit 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
dataBuffer to hold read data
sizeNumber of bytes to read
bytes_read_ptrPointer to hold amount of data actually read
timeout_msTime 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
sizeNumber of bytes to read
read_timeout_msTime in milliseconds to wait for more data to be read
userUser argument to pass to writer and poller callbacks
writerData writer callback, see gos_cmd_writer_t
pollerData 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]argcNumber of arguments supplied to custom command callback
[in]argvCommand arguments supplied to custom command callback
[out]bool_valPointer 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]enabledEnable/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]argcNumber of arguments supplied to custom command callback
[in]argvCommand arguments supplied to custom command callback
[out]bufferBuffer to hold decoded string argument
[in]max_lenMaximum length of the decoded string
[out]saved_lenPointer 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]argcNumber of arguments supplied to custom command callback
[in]argvCommand arguments supplied to custom command callback
[in]flag_maskThe mask of the flag to set or clear based on the boolean value of argv[1]
[in,out]flag_ptrPointer to existing flag value
[in]flag_widthThe 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]argcNumber of arguments supplied to custom command callback
[in]argvCommand arguments supplied to custom command callback
[out]int_valPointer to hold parsed argument
[in]minMinimum value the parsed argument can be
[in]maxMaximum 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]argcNumber of arguments supplied to custom command callback
[in]argvCommand arguments supplied to custom command callback
[out]int_valPointer to hold parsed argument
[in]minMinimum value of the argument
[in]maxMaximum 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]argcNumber of arguments supplied to custom command callback
[in]argvCommand arguments supplied to custom command callback
[out]ip_addrPointer 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]argcNumber of arguments supplied to custom command callback
[in]argvCommand arguments supplied to custom command callback
[out]bufferBuffer to hold string argument
[in]max_lenMaximum 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_resultThe result of the command
[in]sizeThe 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.:

Parameters
[in]dataResponse data
[in]data_sizeThe 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
dataPointer to data to write
sizeNumber of bytes to write
bytes_written_ptrPointer to hold amount of data actually written
timeout_msTime 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_resultThe result of the command
[in]dataResponse data
[in]data_sizeThe 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.