class Tinkerforge::BrickRED

Executes user programs and controls other Bricks/Bricklets standalone

Constants

CALLBACK_ASYNC_FILE_READ

This callback reports the result of a call to the BrickRED#read_file_async function.

CALLBACK_ASYNC_FILE_WRITE

This callback reports the result of a call to the BrickRED#write_file_async function.

CALLBACK_FILE_EVENTS_OCCURRED
CALLBACK_PROCESS_STATE_CHANGED
CALLBACK_PROGRAM_PROCESS_SPAWNED
CALLBACK_PROGRAM_SCHEDULER_STATE_CHANGED

Public Class Methods

new(uid, ipcon) click to toggle source

Creates an object with the unique device ID uid and adds it to the IP Connection ipcon.

Calls superclass method
# File lib/tinkerforge/brick_red.rb, line 215
def initialize(uid, ipcon)
  super uid, ipcon, DEVICE_IDENTIFIER, DEVICE_DISPLAY_NAME

  @api_version = [2, 0, 0]

  @response_expected[FUNCTION_CREATE_SESSION] = RESPONSE_EXPECTED_ALWAYS_TRUE
  @response_expected[FUNCTION_EXPIRE_SESSION] = RESPONSE_EXPECTED_ALWAYS_TRUE
  @response_expected[FUNCTION_EXPIRE_SESSION_UNCHECKED] = RESPONSE_EXPECTED_FALSE
  @response_expected[FUNCTION_KEEP_SESSION_ALIVE] = RESPONSE_EXPECTED_ALWAYS_TRUE
  @response_expected[FUNCTION_RELEASE_OBJECT] = RESPONSE_EXPECTED_ALWAYS_TRUE
  @response_expected[FUNCTION_RELEASE_OBJECT_UNCHECKED] = RESPONSE_EXPECTED_FALSE
  @response_expected[FUNCTION_ALLOCATE_STRING] = RESPONSE_EXPECTED_ALWAYS_TRUE
  @response_expected[FUNCTION_TRUNCATE_STRING] = RESPONSE_EXPECTED_ALWAYS_TRUE
  @response_expected[FUNCTION_GET_STRING_LENGTH] = RESPONSE_EXPECTED_ALWAYS_TRUE
  @response_expected[FUNCTION_SET_STRING_CHUNK] = RESPONSE_EXPECTED_ALWAYS_TRUE
  @response_expected[FUNCTION_GET_STRING_CHUNK] = RESPONSE_EXPECTED_ALWAYS_TRUE
  @response_expected[FUNCTION_ALLOCATE_LIST] = RESPONSE_EXPECTED_ALWAYS_TRUE
  @response_expected[FUNCTION_GET_LIST_LENGTH] = RESPONSE_EXPECTED_ALWAYS_TRUE
  @response_expected[FUNCTION_GET_LIST_ITEM] = RESPONSE_EXPECTED_ALWAYS_TRUE
  @response_expected[FUNCTION_APPEND_TO_LIST] = RESPONSE_EXPECTED_ALWAYS_TRUE
  @response_expected[FUNCTION_REMOVE_FROM_LIST] = RESPONSE_EXPECTED_ALWAYS_TRUE
  @response_expected[FUNCTION_OPEN_FILE] = RESPONSE_EXPECTED_ALWAYS_TRUE
  @response_expected[FUNCTION_CREATE_PIPE] = RESPONSE_EXPECTED_ALWAYS_TRUE
  @response_expected[FUNCTION_GET_FILE_INFO] = RESPONSE_EXPECTED_ALWAYS_TRUE
  @response_expected[FUNCTION_READ_FILE] = RESPONSE_EXPECTED_ALWAYS_TRUE
  @response_expected[FUNCTION_READ_FILE_ASYNC] = RESPONSE_EXPECTED_FALSE
  @response_expected[FUNCTION_ABORT_ASYNC_FILE_READ] = RESPONSE_EXPECTED_ALWAYS_TRUE
  @response_expected[FUNCTION_WRITE_FILE] = RESPONSE_EXPECTED_ALWAYS_TRUE
  @response_expected[FUNCTION_WRITE_FILE_UNCHECKED] = RESPONSE_EXPECTED_FALSE
  @response_expected[FUNCTION_WRITE_FILE_ASYNC] = RESPONSE_EXPECTED_FALSE
  @response_expected[FUNCTION_SET_FILE_POSITION] = RESPONSE_EXPECTED_ALWAYS_TRUE
  @response_expected[FUNCTION_GET_FILE_POSITION] = RESPONSE_EXPECTED_ALWAYS_TRUE
  @response_expected[FUNCTION_SET_FILE_EVENTS] = RESPONSE_EXPECTED_ALWAYS_TRUE
  @response_expected[FUNCTION_GET_FILE_EVENTS] = RESPONSE_EXPECTED_ALWAYS_TRUE
  @response_expected[FUNCTION_OPEN_DIRECTORY] = RESPONSE_EXPECTED_ALWAYS_TRUE
  @response_expected[FUNCTION_GET_DIRECTORY_NAME] = RESPONSE_EXPECTED_ALWAYS_TRUE
  @response_expected[FUNCTION_GET_NEXT_DIRECTORY_ENTRY] = RESPONSE_EXPECTED_ALWAYS_TRUE
  @response_expected[FUNCTION_REWIND_DIRECTORY] = RESPONSE_EXPECTED_ALWAYS_TRUE
  @response_expected[FUNCTION_CREATE_DIRECTORY] = RESPONSE_EXPECTED_ALWAYS_TRUE
  @response_expected[FUNCTION_GET_PROCESSES] = RESPONSE_EXPECTED_ALWAYS_TRUE
  @response_expected[FUNCTION_SPAWN_PROCESS] = RESPONSE_EXPECTED_ALWAYS_TRUE
  @response_expected[FUNCTION_KILL_PROCESS] = RESPONSE_EXPECTED_ALWAYS_TRUE
  @response_expected[FUNCTION_GET_PROCESS_COMMAND] = RESPONSE_EXPECTED_ALWAYS_TRUE
  @response_expected[FUNCTION_GET_PROCESS_IDENTITY] = RESPONSE_EXPECTED_ALWAYS_TRUE
  @response_expected[FUNCTION_GET_PROCESS_STDIO] = RESPONSE_EXPECTED_ALWAYS_TRUE
  @response_expected[FUNCTION_GET_PROCESS_STATE] = RESPONSE_EXPECTED_ALWAYS_TRUE
  @response_expected[FUNCTION_GET_PROGRAMS] = RESPONSE_EXPECTED_ALWAYS_TRUE
  @response_expected[FUNCTION_DEFINE_PROGRAM] = RESPONSE_EXPECTED_ALWAYS_TRUE
  @response_expected[FUNCTION_PURGE_PROGRAM] = RESPONSE_EXPECTED_ALWAYS_TRUE
  @response_expected[FUNCTION_GET_PROGRAM_IDENTIFIER] = RESPONSE_EXPECTED_ALWAYS_TRUE
  @response_expected[FUNCTION_GET_PROGRAM_ROOT_DIRECTORY] = RESPONSE_EXPECTED_ALWAYS_TRUE
  @response_expected[FUNCTION_SET_PROGRAM_COMMAND] = RESPONSE_EXPECTED_ALWAYS_TRUE
  @response_expected[FUNCTION_GET_PROGRAM_COMMAND] = RESPONSE_EXPECTED_ALWAYS_TRUE
  @response_expected[FUNCTION_SET_PROGRAM_STDIO_REDIRECTION] = RESPONSE_EXPECTED_ALWAYS_TRUE
  @response_expected[FUNCTION_GET_PROGRAM_STDIO_REDIRECTION] = RESPONSE_EXPECTED_ALWAYS_TRUE
  @response_expected[FUNCTION_SET_PROGRAM_SCHEDULE] = RESPONSE_EXPECTED_ALWAYS_TRUE
  @response_expected[FUNCTION_GET_PROGRAM_SCHEDULE] = RESPONSE_EXPECTED_ALWAYS_TRUE
  @response_expected[FUNCTION_GET_PROGRAM_SCHEDULER_STATE] = RESPONSE_EXPECTED_ALWAYS_TRUE
  @response_expected[FUNCTION_CONTINUE_PROGRAM_SCHEDULE] = RESPONSE_EXPECTED_ALWAYS_TRUE
  @response_expected[FUNCTION_START_PROGRAM] = RESPONSE_EXPECTED_ALWAYS_TRUE
  @response_expected[FUNCTION_GET_LAST_SPAWNED_PROGRAM_PROCESS] = RESPONSE_EXPECTED_ALWAYS_TRUE
  @response_expected[FUNCTION_GET_CUSTOM_PROGRAM_OPTION_NAMES] = RESPONSE_EXPECTED_ALWAYS_TRUE
  @response_expected[FUNCTION_SET_CUSTOM_PROGRAM_OPTION_VALUE] = RESPONSE_EXPECTED_ALWAYS_TRUE
  @response_expected[FUNCTION_GET_CUSTOM_PROGRAM_OPTION_VALUE] = RESPONSE_EXPECTED_ALWAYS_TRUE
  @response_expected[FUNCTION_REMOVE_CUSTOM_PROGRAM_OPTION] = RESPONSE_EXPECTED_ALWAYS_TRUE
  @response_expected[FUNCTION_GET_IDENTITY] = RESPONSE_EXPECTED_ALWAYS_TRUE

  @callback_formats[CALLBACK_ASYNC_FILE_READ] = [72, 'S C C60 C']
  @callback_formats[CALLBACK_ASYNC_FILE_WRITE] = [12, 'S C C']
  @callback_formats[CALLBACK_FILE_EVENTS_OCCURRED] = [12, 'S S']
  @callback_formats[CALLBACK_PROCESS_STATE_CHANGED] = [20, 'S C Q C']
  @callback_formats[CALLBACK_PROGRAM_SCHEDULER_STATE_CHANGED] = [10, 'S']
  @callback_formats[CALLBACK_PROGRAM_PROCESS_SPAWNED] = [10, 'S']

  @ipcon.add_device self
end

Public Instance Methods

abort_async_file_read(file_id) click to toggle source

Aborts a BrickRED#read_file_async operation in progress.

Returns the resulting error code.

On success the CALLBACK_ASYNC_FILE_READ callback will report OperationAborted.

# File lib/tinkerforge/brick_red.rb, line 571
def abort_async_file_read(file_id)
  check_validity

  send_request FUNCTION_ABORT_ASYNC_FILE_READ, [file_id], 'S', 9, 'C'
end
allocate_list(length_to_reserve, session_id) click to toggle source

Allocates a new list object and reserves memory for “length_to_reserve“ items. Set “length_to_reserve“ to the number of items that should be stored in the list object.

Returns the object ID of the new list object and the resulting error code.

When a list object gets destroyed then the reference count of each object in the list object is decreased by one.

# File lib/tinkerforge/brick_red.rb, line 386
def allocate_list(length_to_reserve, session_id)
  check_validity

  send_request FUNCTION_ALLOCATE_LIST, [length_to_reserve, session_id], 'S S', 11, 'C S'
end
allocate_string(length_to_reserve, buffer, session_id) click to toggle source

Allocates a new string object, reserves “length_to_reserve“ bytes memory for it and sets up to the first 60 bytes. Set “length_to_reserve“ to the length of the string that should be stored in the string object.

Returns the object ID of the new string object and the resulting error code.

# File lib/tinkerforge/brick_red.rb, line 340
def allocate_string(length_to_reserve, buffer, session_id)
  check_validity

  send_request FUNCTION_ALLOCATE_STRING, [length_to_reserve, buffer, session_id], 'L Z58 S', 11, 'C S'
end
append_to_list(list_id, item_object_id) click to toggle source

Appends an object to a list object and increases the reference count of the appended object by one.

Returns the resulting error code.

# File lib/tinkerforge/brick_red.rb, line 420
def append_to_list(list_id, item_object_id)
  check_validity

  send_request FUNCTION_APPEND_TO_LIST, [list_id, item_object_id], 'S S', 9, 'C'
end
continue_program_schedule(program_id) click to toggle source
# File lib/tinkerforge/brick_red.rb, line 903
def continue_program_schedule(program_id)
  check_validity

  send_request FUNCTION_CONTINUE_PROGRAM_SCHEDULE, [program_id], 'S', 9, 'C'
end
create_directory(name_string_id, flags, permissions, uid, gid) click to toggle source

FIXME: name has to be absolute

# File lib/tinkerforge/brick_red.rb, line 714
def create_directory(name_string_id, flags, permissions, uid, gid)
  check_validity

  send_request FUNCTION_CREATE_DIRECTORY, [name_string_id, flags, permissions, uid, gid], 'S L S L L', 9, 'C'
end
create_pipe(flags, length, session_id) click to toggle source

Creates a new pipe and allocates a new file object for it.

The “flags“ parameter takes a ORed combination of the following possible pipe flags (in hexadecimal notation):

  • NonBlockingRead = 0x0001

  • NonBlockingWrite = 0x0002

The length of the pipe buffer can be specified with the “length“ parameter in bytes. If length is set to zero, then the default pipe buffer length is used.

Returns the object ID of the new file object and the resulting error code.

# File lib/tinkerforge/brick_red.rb, line 495
def create_pipe(flags, length, session_id)
  check_validity

  send_request FUNCTION_CREATE_PIPE, [flags, length, session_id], 'L Q S', 11, 'C S'
end
create_session(lifetime) click to toggle source
# File lib/tinkerforge/brick_red.rb, line 293
def create_session(lifetime)
  check_validity

  send_request FUNCTION_CREATE_SESSION, [lifetime], 'L', 11, 'C S'
end
define_program(identifier_string_id, session_id) click to toggle source
# File lib/tinkerforge/brick_red.rb, line 826
def define_program(identifier_string_id, session_id)
  check_validity

  send_request FUNCTION_DEFINE_PROGRAM, [identifier_string_id, session_id], 'S S', 11, 'C S'
end
expire_session(session_id) click to toggle source
# File lib/tinkerforge/brick_red.rb, line 300
def expire_session(session_id)
  check_validity

  send_request FUNCTION_EXPIRE_SESSION, [session_id], 'S', 9, 'C'
end
expire_session_unchecked(session_id) click to toggle source
# File lib/tinkerforge/brick_red.rb, line 307
def expire_session_unchecked(session_id)
  check_validity

  send_request FUNCTION_EXPIRE_SESSION_UNCHECKED, [session_id], 'S', 8, ''
end
get_custom_program_option_names(program_id, session_id) click to toggle source
# File lib/tinkerforge/brick_red.rb, line 924
def get_custom_program_option_names(program_id, session_id)
  check_validity

  send_request FUNCTION_GET_CUSTOM_PROGRAM_OPTION_NAMES, [program_id, session_id], 'S S', 11, 'C S'
end
get_custom_program_option_value(program_id, name_string_id, session_id) click to toggle source
# File lib/tinkerforge/brick_red.rb, line 938
def get_custom_program_option_value(program_id, name_string_id, session_id)
  check_validity

  send_request FUNCTION_GET_CUSTOM_PROGRAM_OPTION_VALUE, [program_id, name_string_id, session_id], 'S S S', 11, 'C S'
end
get_directory_name(directory_id, session_id) click to toggle source

Returns the name of a directory object, as passed to BrickRED#open_directory, and the resulting error code.

# File lib/tinkerforge/brick_red.rb, line 679
def get_directory_name(directory_id, session_id)
  check_validity

  send_request FUNCTION_GET_DIRECTORY_NAME, [directory_id, session_id], 'S S', 11, 'C S'
end
get_file_events(file_id) click to toggle source
# File lib/tinkerforge/brick_red.rb, line 655
def get_file_events(file_id)
  check_validity

  send_request FUNCTION_GET_FILE_EVENTS, [file_id], 'S', 11, 'C S'
end
get_file_info(file_id, session_id) click to toggle source

Returns various information about a file and the resulting error code.

Possible file types are:

  • Unknown = 0

  • Regular = 1

  • Directory = 2

  • Character = 3

  • Block = 4

  • FIFO = 5

  • Symlink = 6

  • Socket = 7

  • Pipe = 8

If the file type is Pipe then the returned name string object is invalid, because a pipe has no name. Otherwise the returned name string object was used to open or create the file object, as passed to BrickRED#open_file.

The returned flags were used to open or create the file object, as passed to BrickRED#open_file or BrickRED#create_pipe. See the respective function for a list of possible file and pipe flags.

FIXME: everything except flags and length is invalid if file type is Pipe

# File lib/tinkerforge/brick_red.rb, line 524
def get_file_info(file_id, session_id)
  check_validity

  send_request FUNCTION_GET_FILE_INFO, [file_id, session_id], 'S S', 58, 'C C S L S L L Q Q Q Q'
end
get_file_position(file_id) click to toggle source

Returns the current seek position of a file object and returns the resulting error code.

If the file object was created by BrickRED#create_pipe then it has no seek position and the error code InvalidSeek is returned.

# File lib/tinkerforge/brick_red.rb, line 641
def get_file_position(file_id)
  check_validity

  send_request FUNCTION_GET_FILE_POSITION, [file_id], 'S', 17, 'C Q'
end
get_identity() click to toggle source

Returns the UID, the UID where the Brick is connected to, the position, the hardware and firmware version as well as the device identifier.

The position is the position in the stack from '0' (bottom) to '8' (top).

The device identifier numbers can be found :ref:`here <device_identifier>`. |device_identifier_constant|

# File lib/tinkerforge/brick_red.rb, line 959
def get_identity
  send_request FUNCTION_GET_IDENTITY, [], '', 33, 'Z8 Z8 k C3 C3 S'
end
get_last_spawned_program_process(program_id, session_id) click to toggle source
# File lib/tinkerforge/brick_red.rb, line 917
def get_last_spawned_program_process(program_id, session_id)
  check_validity

  send_request FUNCTION_GET_LAST_SPAWNED_PROGRAM_PROCESS, [program_id, session_id], 'S S', 19, 'C S Q'
end
get_list_item(list_id, index, session_id) click to toggle source

Returns the object ID and type of the object stored at “index“ in a list object and returns the resulting error code.

Possible object types are:

  • String = 0

  • List = 1

  • File = 2

  • Directory = 3

  • Process = 4

  • Program = 5

# File lib/tinkerforge/brick_red.rb, line 410
def get_list_item(list_id, index, session_id)
  check_validity

  send_request FUNCTION_GET_LIST_ITEM, [list_id, index, session_id], 'S S S', 12, 'C S C'
end
get_list_length(list_id) click to toggle source

Returns the length of a list object in items and the resulting error code.

# File lib/tinkerforge/brick_red.rb, line 393
def get_list_length(list_id)
  check_validity

  send_request FUNCTION_GET_LIST_LENGTH, [list_id], 'S', 11, 'C S'
end
get_next_directory_entry(directory_id, session_id) click to toggle source

Returns the next entry in a directory object and the resulting error code.

If there is not next entry then error code NoMoreData is returned. To rewind a directory object call BrickRED#rewind_directory.

Possible directory entry types are:

  • Unknown = 0

  • Regular = 1

  • Directory = 2

  • Character = 3

  • Block = 4

  • FIFO = 5

  • Symlink = 6

  • Socket = 7

# File lib/tinkerforge/brick_red.rb, line 700
def get_next_directory_entry(directory_id, session_id)
  check_validity

  send_request FUNCTION_GET_NEXT_DIRECTORY_ENTRY, [directory_id, session_id], 'S S', 12, 'C S C'
end
get_process_command(process_id, session_id) click to toggle source

Returns the executable, arguments, environment and working directory used to spawn a process object, as passed to BrickRED#spawn_process, and the resulting error code.

# File lib/tinkerforge/brick_red.rb, line 756
def get_process_command(process_id, session_id)
  check_validity

  send_request FUNCTION_GET_PROCESS_COMMAND, [process_id, session_id], 'S S', 17, 'C S S S S'
end
get_process_identity(process_id) click to toggle source

Returns the process ID and the user and group ID used to spawn a process object, as passed to BrickRED#spawn_process, and the resulting error code.

The process ID is only valid if the state is Running or Stopped, see BrickRED#get_process_state.

# File lib/tinkerforge/brick_red.rb, line 767
def get_process_identity(process_id)
  check_validity

  send_request FUNCTION_GET_PROCESS_IDENTITY, [process_id], 'S', 21, 'C L L L'
end
get_process_state(process_id) click to toggle source

Returns the current state, timestamp and exit code of a process object, and the resulting error code.

Possible process states are:

  • Unknown = 0

  • Running = 1

  • Error = 2

  • Exited = 3

  • Killed = 4

  • Stopped = 5

The timestamp represents the UNIX time since when the process is in its current state.

The exit code is only valid if the state is Error, Exited, Killed or Stopped and has different meanings depending on the state:

  • Error: error code for error occurred while spawning the process (see below)

  • Exited: exit status of the process

  • Killed: UNIX signal number used to kill the process

  • Stopped: UNIX signal number used to stop the process

Possible exit/error codes in Error state are:

  • InternalError = 125

  • CannotExecute = 126

  • DoesNotExist = 127

The CannotExecute error can be caused by the executable being opened for writing.

# File lib/tinkerforge/brick_red.rb, line 812
def get_process_state(process_id)
  check_validity

  send_request FUNCTION_GET_PROCESS_STATE, [process_id], 'S', 19, 'C C Q C'
end
get_process_stdio(process_id, session_id) click to toggle source

Returns the stdin, stdout and stderr files used to spawn a process object, as passed to BrickRED#spawn_process, and the resulting error code.

# File lib/tinkerforge/brick_red.rb, line 775
def get_process_stdio(process_id, session_id)
  check_validity

  send_request FUNCTION_GET_PROCESS_STDIO, [process_id, session_id], 'S S', 15, 'C S S S'
end
get_processes(session_id) click to toggle source
# File lib/tinkerforge/brick_red.rb, line 721
def get_processes(session_id)
  check_validity

  send_request FUNCTION_GET_PROCESSES, [session_id], 'S', 11, 'C S'
end
get_program_command(program_id, session_id) click to toggle source

FIXME: working directory is relative to <home>/programs/<identifier>/bin

# File lib/tinkerforge/brick_red.rb, line 861
def get_program_command(program_id, session_id)
  check_validity

  send_request FUNCTION_GET_PROGRAM_COMMAND, [program_id, session_id], 'S S', 17, 'C S S S S'
end
get_program_identifier(program_id, session_id) click to toggle source
# File lib/tinkerforge/brick_red.rb, line 840
def get_program_identifier(program_id, session_id)
  check_validity

  send_request FUNCTION_GET_PROGRAM_IDENTIFIER, [program_id, session_id], 'S S', 11, 'C S'
end
get_program_root_directory(program_id, session_id) click to toggle source

FIXME: root directory is absolute: <home>/programs/<identifier>

# File lib/tinkerforge/brick_red.rb, line 847
def get_program_root_directory(program_id, session_id)
  check_validity

  send_request FUNCTION_GET_PROGRAM_ROOT_DIRECTORY, [program_id, session_id], 'S S', 11, 'C S'
end
get_program_schedule(program_id, session_id) click to toggle source
# File lib/tinkerforge/brick_red.rb, line 889
def get_program_schedule(program_id, session_id)
  check_validity

  send_request FUNCTION_GET_PROGRAM_SCHEDULE, [program_id, session_id], 'S S', 17, 'C C ? L S'
end
get_program_scheduler_state(program_id, session_id) click to toggle source

FIXME: message is currently valid in error-occurred state only

# File lib/tinkerforge/brick_red.rb, line 896
def get_program_scheduler_state(program_id, session_id)
  check_validity

  send_request FUNCTION_GET_PROGRAM_SCHEDULER_STATE, [program_id, session_id], 'S S', 20, 'C C Q S'
end
get_program_stdio_redirection(program_id, session_id) click to toggle source

FIXME: stdio file names are relative to <home>/programs/<identifier>/bin

# File lib/tinkerforge/brick_red.rb, line 875
def get_program_stdio_redirection(program_id, session_id)
  check_validity

  send_request FUNCTION_GET_PROGRAM_STDIO_REDIRECTION, [program_id, session_id], 'S S', 18, 'C C S C S C S'
end
get_programs(session_id) click to toggle source
# File lib/tinkerforge/brick_red.rb, line 819
def get_programs(session_id)
  check_validity

  send_request FUNCTION_GET_PROGRAMS, [session_id], 'S', 11, 'C S'
end
get_string_chunk(string_id, offset) click to toggle source

Returns a chunk up to 63 bytes from a string object beginning at “offset“ and returns the resulting error code.

# File lib/tinkerforge/brick_red.rb, line 372
def get_string_chunk(string_id, offset)
  check_validity

  send_request FUNCTION_GET_STRING_CHUNK, [string_id, offset], 'S L', 72, 'C Z63'
end
get_string_length(string_id) click to toggle source

Returns the length of a string object and the resulting error code.

# File lib/tinkerforge/brick_red.rb, line 355
def get_string_length(string_id)
  check_validity

  send_request FUNCTION_GET_STRING_LENGTH, [string_id], 'S', 13, 'C L'
end
keep_session_alive(session_id, lifetime) click to toggle source
# File lib/tinkerforge/brick_red.rb, line 314
def keep_session_alive(session_id, lifetime)
  check_validity

  send_request FUNCTION_KEEP_SESSION_ALIVE, [session_id, lifetime], 'S L', 9, 'C'
end
kill_process(process_id, signal) click to toggle source

Sends a UNIX signal to a process object and returns the resulting error code.

Possible UNIX signals are:

  • Interrupt = 2

  • Quit = 3

  • Abort = 6

  • Kill = 9

  • User1 = 10

  • User2 = 12

  • Terminate = 15

  • Continue = 18

  • Stop = 19

# File lib/tinkerforge/brick_red.rb, line 747
def kill_process(process_id, signal)
  check_validity

  send_request FUNCTION_KILL_PROCESS, [process_id, signal], 'S C', 9, 'C'
end
open_directory(name_string_id, session_id) click to toggle source

Opens an existing directory and allocates a new directory object for it.

FIXME: name has to be absolute

The reference count of the name string object is increased by one. When the directory object is destroyed then the reference count of the name string object is decreased by one. Also the name string object is locked and cannot be modified while the directory object holds a reference to it.

Returns the object ID of the new directory object and the resulting error code.

# File lib/tinkerforge/brick_red.rb, line 671
def open_directory(name_string_id, session_id)
  check_validity

  send_request FUNCTION_OPEN_DIRECTORY, [name_string_id, session_id], 'S S', 11, 'C S'
end
open_file(name_string_id, flags, permissions, uid, gid, session_id) click to toggle source

Opens an existing file or creates a new file and allocates a new file object for it.

FIXME: name has to be absolute

The reference count of the name string object is increased by one. When the file object gets destroyed then the reference count of the name string object is decreased by one. Also the name string object is locked and cannot be modified while the file object holds a reference to it.

The “flags“ parameter takes a ORed combination of the following possible file flags (in hexadecimal notation):

  • ReadOnly = 0x0001 (O_RDONLY)

  • WriteOnly = 0x0002 (O_WRONLY)

  • ReadWrite = 0x0004 (O_RDWR)

  • Append = 0x0008 (O_APPEND)

  • Create = 0x0010 (O_CREAT)

  • Exclusive = 0x0020 (O_EXCL)

  • NonBlocking = 0x0040 (O_NONBLOCK)

  • Truncate = 0x0080 (O_TRUNC)

  • Temporary = 0x0100

  • Replace = 0x0200

FIXME: explain Temporary and Replace flag

The “permissions“ parameter takes a ORed combination of the following possible file permissions (in octal notation) that match the common UNIX permission bits:

  • UserRead = 00400

  • UserWrite = 00200

  • UserExecute = 00100

  • GroupRead = 00040

  • GroupWrite = 00020

  • GroupExecute = 00010

  • OthersRead = 00004

  • OthersWrite = 00002

  • OthersExecute = 00001

Returns the object ID of the new file object and the resulting error code.

# File lib/tinkerforge/brick_red.rb, line 477
def open_file(name_string_id, flags, permissions, uid, gid, session_id)
  check_validity

  send_request FUNCTION_OPEN_FILE, [name_string_id, flags, permissions, uid, gid, session_id], 'S L S L L S', 11, 'C S'
end
purge_program(program_id, cookie) click to toggle source
# File lib/tinkerforge/brick_red.rb, line 833
def purge_program(program_id, cookie)
  check_validity

  send_request FUNCTION_PURGE_PROGRAM, [program_id, cookie], 'S L', 9, 'C'
end
read_file(file_id, length_to_read) click to toggle source

Reads up to 62 bytes from a file object.

Returns the bytes read, the actual number of bytes read and the resulting error code.

If there is not data to be read, either because the file position reached end-of-file or because there is not data in the pipe, then zero bytes are returned.

If the file object was created by BrickRED#open_file without the NonBlocking flag or by BrickRED#create_pipe without the NonBlockingRead flag then the error code NotSupported is returned.

# File lib/tinkerforge/brick_red.rb, line 542
def read_file(file_id, length_to_read)
  check_validity

  send_request FUNCTION_READ_FILE, [file_id, length_to_read], 'S C', 72, 'C C62 C'
end
read_file_async(file_id, length_to_read) click to toggle source

Reads up to 2\ :sup:`63`\ - 1 bytes from a file object asynchronously.

Reports the bytes read (in 60 byte chunks), the actual number of bytes read and the resulting error code via the CALLBACK_ASYNC_FILE_READ callback.

If there is not data to be read, either because the file position reached end-of-file or because there is not data in the pipe, then zero bytes are reported.

If the file object was created by BrickRED#open_file without the NonBlocking flag or by BrickRED#create_pipe without the NonBlockingRead flag then the error code NotSupported is reported via the CALLBACK_ASYNC_FILE_READ callback.

# File lib/tinkerforge/brick_red.rb, line 560
def read_file_async(file_id, length_to_read)
  check_validity

  send_request FUNCTION_READ_FILE_ASYNC, [file_id, length_to_read], 'S Q', 8, ''
end
register_callback(id, &block) click to toggle source

Registers a callback with ID id to the block block.

# File lib/tinkerforge/brick_red.rb, line 964
def register_callback(id, &block)
  callback = block
  @registered_callbacks[id] = callback
end
release_object(object_id, session_id) click to toggle source

Decreases the reference count of an object by one and returns the resulting error code. If the reference count reaches zero the object gets destroyed.

# File lib/tinkerforge/brick_red.rb, line 322
def release_object(object_id, session_id)
  check_validity

  send_request FUNCTION_RELEASE_OBJECT, [object_id, session_id], 'S S', 9, 'C'
end
release_object_unchecked(object_id, session_id) click to toggle source
# File lib/tinkerforge/brick_red.rb, line 329
def release_object_unchecked(object_id, session_id)
  check_validity

  send_request FUNCTION_RELEASE_OBJECT_UNCHECKED, [object_id, session_id], 'S S', 8, ''
end
remove_custom_program_option(program_id, name_string_id) click to toggle source
# File lib/tinkerforge/brick_red.rb, line 945
def remove_custom_program_option(program_id, name_string_id)
  check_validity

  send_request FUNCTION_REMOVE_CUSTOM_PROGRAM_OPTION, [program_id, name_string_id], 'S S', 9, 'C'
end
remove_from_list(list_id, index) click to toggle source

Removes the object stored at “index“ from a list object and decreases the reference count of the removed object by one.

Returns the resulting error code.

# File lib/tinkerforge/brick_red.rb, line 430
def remove_from_list(list_id, index)
  check_validity

  send_request FUNCTION_REMOVE_FROM_LIST, [list_id, index], 'S S', 9, 'C'
end
rewind_directory(directory_id) click to toggle source

Rewinds a directory object and returns the resulting error code.

# File lib/tinkerforge/brick_red.rb, line 707
def rewind_directory(directory_id)
  check_validity

  send_request FUNCTION_REWIND_DIRECTORY, [directory_id], 'S', 9, 'C'
end
set_custom_program_option_value(program_id, name_string_id, value_string_id) click to toggle source
# File lib/tinkerforge/brick_red.rb, line 931
def set_custom_program_option_value(program_id, name_string_id, value_string_id)
  check_validity

  send_request FUNCTION_SET_CUSTOM_PROGRAM_OPTION_VALUE, [program_id, name_string_id, value_string_id], 'S S S', 9, 'C'
end
set_file_events(file_id, events) click to toggle source
# File lib/tinkerforge/brick_red.rb, line 648
def set_file_events(file_id, events)
  check_validity

  send_request FUNCTION_SET_FILE_EVENTS, [file_id, events], 'S S', 9, 'C'
end
set_file_position(file_id, offset, origin) click to toggle source

Set the current seek position of a file object relative to “origin“.

Possible file origins are:

  • Beginning = 0

  • Current = 1

  • End = 2

Returns the resulting absolute seek position and error code.

If the file object was created by BrickRED#create_pipe then it has no seek position and the error code InvalidSeek is returned.

# File lib/tinkerforge/brick_red.rb, line 630
def set_file_position(file_id, offset, origin)
  check_validity

  send_request FUNCTION_SET_FILE_POSITION, [file_id, offset, origin], 'S q C', 17, 'C Q'
end
set_program_command(program_id, executable_string_id, arguments_list_id, environment_list_id, working_directory_string_id) click to toggle source

FIXME: working directory is relative to <home>/programs/<identifier>/bin

# File lib/tinkerforge/brick_red.rb, line 854
def set_program_command(program_id, executable_string_id, arguments_list_id, environment_list_id, working_directory_string_id)
  check_validity

  send_request FUNCTION_SET_PROGRAM_COMMAND, [program_id, executable_string_id, arguments_list_id, environment_list_id, working_directory_string_id], 'S S S S S', 9, 'C'
end
set_program_schedule(program_id, start_mode, continue_after_error, start_interval, start_fields_string_id) click to toggle source
# File lib/tinkerforge/brick_red.rb, line 882
def set_program_schedule(program_id, start_mode, continue_after_error, start_interval, start_fields_string_id)
  check_validity

  send_request FUNCTION_SET_PROGRAM_SCHEDULE, [program_id, start_mode, continue_after_error, start_interval, start_fields_string_id], 'S C ? L S', 9, 'C'
end
set_program_stdio_redirection(program_id, stdin_redirection, stdin_file_name_string_id, stdout_redirection, stdout_file_name_string_id, stderr_redirection, stderr_file_name_string_id) click to toggle source

FIXME: stdio file names are relative to <home>/programs/<identifier>/bin

# File lib/tinkerforge/brick_red.rb, line 868
def set_program_stdio_redirection(program_id, stdin_redirection, stdin_file_name_string_id, stdout_redirection, stdout_file_name_string_id, stderr_redirection, stderr_file_name_string_id)
  check_validity

  send_request FUNCTION_SET_PROGRAM_STDIO_REDIRECTION, [program_id, stdin_redirection, stdin_file_name_string_id, stdout_redirection, stdout_file_name_string_id, stderr_redirection, stderr_file_name_string_id], 'S C S C S C S', 9, 'C'
end
set_string_chunk(string_id, offset, buffer) click to toggle source

Sets a chunk of up to 58 bytes in a string object beginning at “offset“.

Returns the resulting error code.

# File lib/tinkerforge/brick_red.rb, line 364
def set_string_chunk(string_id, offset, buffer)
  check_validity

  send_request FUNCTION_SET_STRING_CHUNK, [string_id, offset, buffer], 'S L Z58', 9, 'C'
end
spawn_process(executable_string_id, arguments_list_id, environment_list_id, working_directory_string_id, uid, gid, stdin_file_id, stdout_file_id, stderr_file_id, session_id) click to toggle source
# File lib/tinkerforge/brick_red.rb, line 728
def spawn_process(executable_string_id, arguments_list_id, environment_list_id, working_directory_string_id, uid, gid, stdin_file_id, stdout_file_id, stderr_file_id, session_id)
  check_validity

  send_request FUNCTION_SPAWN_PROCESS, [executable_string_id, arguments_list_id, environment_list_id, working_directory_string_id, uid, gid, stdin_file_id, stdout_file_id, stderr_file_id, session_id], 'S S S S L L S S S S', 11, 'C S'
end
start_program(program_id) click to toggle source
# File lib/tinkerforge/brick_red.rb, line 910
def start_program(program_id)
  check_validity

  send_request FUNCTION_START_PROGRAM, [program_id], 'S', 9, 'C'
end
truncate_string(string_id, length) click to toggle source

Truncates a string object to “length“ bytes and returns the resulting error code.

# File lib/tinkerforge/brick_red.rb, line 348
def truncate_string(string_id, length)
  check_validity

  send_request FUNCTION_TRUNCATE_STRING, [string_id, length], 'S L', 9, 'C'
end
write_file(file_id, buffer, length_to_write) click to toggle source

Writes up to 61 bytes to a file object.

Returns the actual number of bytes written and the resulting error code.

If the file object was created by BrickRED#open_file without the NonBlocking flag or by BrickRED#create_pipe without the NonBlockingWrite flag then the error code NotSupported is returned.

# File lib/tinkerforge/brick_red.rb, line 584
def write_file(file_id, buffer, length_to_write)
  check_validity

  send_request FUNCTION_WRITE_FILE, [file_id, buffer, length_to_write], 'S C61 C', 10, 'C C'
end
write_file_async(file_id, buffer, length_to_write) click to toggle source

Writes up to 61 bytes to a file object.

Reports the actual number of bytes written and the resulting error code via the CALLBACK_ASYNC_FILE_WRITE callback.

If the file object was created by BrickRED#open_file without the NonBlocking flag or by BrickRED#create_pipe without the NonBlockingWrite flag then the error code NotSupported is reported via the CALLBACK_ASYNC_FILE_WRITE callback.

# File lib/tinkerforge/brick_red.rb, line 612
def write_file_async(file_id, buffer, length_to_write)
  check_validity

  send_request FUNCTION_WRITE_FILE_ASYNC, [file_id, buffer, length_to_write], 'S C61 C', 8, ''
end
write_file_unchecked(file_id, buffer, length_to_write) click to toggle source

Writes up to 61 bytes to a file object.

Does neither report the actual number of bytes written nor the resulting error code.

If the file object was created by BrickRED#open_file without the NonBlocking flag or by BrickRED#create_pipe without the NonBlockingWrite flag then the write operation will fail silently.

# File lib/tinkerforge/brick_red.rb, line 598
def write_file_unchecked(file_id, buffer, length_to_write)
  check_validity

  send_request FUNCTION_WRITE_FILE_UNCHECKED, [file_id, buffer, length_to_write], 'S C61 C', 8, ''
end