tinkerforge 2.1.22 → 2.1.27

data/lib/tinkerforge/brick_red.rb

@@ -1,14 +1,16 @@
 # -*- ruby encoding: utf-8 -*-
 #############################################################
-# This file was automatically generated on 2019-05-21.      #
+# This file was automatically generated on 2020-11-02.      #
 #                                                           #
-# Ruby Bindings Version 2.1.22                              #
+# Ruby Bindings Version 2.1.27                              #
 #                                                           #
 # If you have a bugfix for this file and want to commit it, #
 # please fix the bug in the generator. You can find a link  #
 # to the generators git repository on tinkerforge.com       #
 #############################################################
 
+require_relative './ip_connection'
+
 module Tinkerforge
   # Executes user programs and controls other Bricks/Bricklets standalone
   class BrickRED < Device
@@ -212,7 +214,7 @@ module Tinkerforge
     # Creates an object with the unique device ID <tt>uid</tt> and adds it to
     # the IP Connection <tt>ipcon</tt>.
     def initialize(uid, ipcon)
-      super uid, ipcon
+      super uid, ipcon, DEVICE_IDENTIFIER, DEVICE_DISPLAY_NAME
 
       @api_version = [2, 0, 0]
 
@@ -278,44 +280,57 @@ module Tinkerforge
       @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] = 'S C C60 C'
-      @callback_formats[CALLBACK_ASYNC_FILE_WRITE] = 'S C C'
-      @callback_formats[CALLBACK_FILE_EVENTS_OCCURRED] = 'S S'
-      @callback_formats[CALLBACK_PROCESS_STATE_CHANGED] = 'S C Q C'
-      @callback_formats[CALLBACK_PROGRAM_SCHEDULER_STATE_CHANGED] = 'S'
-      @callback_formats[CALLBACK_PROGRAM_PROCESS_SPAWNED] = 'S'
+      @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
 
     # 
     def create_session(lifetime)
-      send_request FUNCTION_CREATE_SESSION, [lifetime], 'L', 3, 'C S'
+      check_validity
+
+      send_request FUNCTION_CREATE_SESSION, [lifetime], 'L', 11, 'C S'
     end
 
     # 
     def expire_session(session_id)
-      send_request FUNCTION_EXPIRE_SESSION, [session_id], 'S', 1, 'C'
+      check_validity
+
+      send_request FUNCTION_EXPIRE_SESSION, [session_id], 'S', 9, 'C'
     end
 
     # 
     def expire_session_unchecked(session_id)
-      send_request FUNCTION_EXPIRE_SESSION_UNCHECKED, [session_id], 'S', 0, ''
+      check_validity
+
+      send_request FUNCTION_EXPIRE_SESSION_UNCHECKED, [session_id], 'S', 8, ''
     end
 
     # 
     def keep_session_alive(session_id, lifetime)
-      send_request FUNCTION_KEEP_SESSION_ALIVE, [session_id, lifetime], 'S L', 1, 'C'
+      check_validity
+
+      send_request FUNCTION_KEEP_SESSION_ALIVE, [session_id, lifetime], 'S L', 9, 'C'
     end
 
     # 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.
     def release_object(object_id, session_id)
-      send_request FUNCTION_RELEASE_OBJECT, [object_id, session_id], 'S S', 1, 'C'
+      check_validity
+
+      send_request FUNCTION_RELEASE_OBJECT, [object_id, session_id], 'S S', 9, 'C'
     end
 
     # 
     def release_object_unchecked(object_id, session_id)
-      send_request FUNCTION_RELEASE_OBJECT_UNCHECKED, [object_id, session_id], 'S S', 0, ''
+      check_validity
+
+      send_request FUNCTION_RELEASE_OBJECT_UNCHECKED, [object_id, session_id], 'S S', 8, ''
     end
 
     # Allocates a new string object, reserves ``length_to_reserve`` bytes memory
@@ -324,31 +339,41 @@ module Tinkerforge
     # 
     # Returns the object ID of the new string object and the resulting error code.
     def allocate_string(length_to_reserve, buffer, session_id)
-      send_request FUNCTION_ALLOCATE_STRING, [length_to_reserve, buffer, session_id], 'L Z58 S', 3, 'C S'
+      check_validity
+
+      send_request FUNCTION_ALLOCATE_STRING, [length_to_reserve, buffer, session_id], 'L Z58 S', 11, 'C S'
     end
 
     # Truncates a string object to ``length`` bytes and returns the resulting
     # error code.
     def truncate_string(string_id, length)
-      send_request FUNCTION_TRUNCATE_STRING, [string_id, length], 'S L', 1, 'C'
+      check_validity
+
+      send_request FUNCTION_TRUNCATE_STRING, [string_id, length], 'S L', 9, 'C'
     end
 
-    # Returns the length of a string object in bytes and the resulting error code.
+    # Returns the length of a string object and the resulting error code.
     def get_string_length(string_id)
-      send_request FUNCTION_GET_STRING_LENGTH, [string_id], 'S', 5, 'C L'
+      check_validity
+
+      send_request FUNCTION_GET_STRING_LENGTH, [string_id], 'S', 13, 'C L'
     end
 
     # Sets a chunk of up to 58 bytes in a string object beginning at ``offset``.
     # 
     # Returns the resulting error code.
     def set_string_chunk(string_id, offset, buffer)
-      send_request FUNCTION_SET_STRING_CHUNK, [string_id, offset, buffer], 'S L Z58', 1, 'C'
+      check_validity
+
+      send_request FUNCTION_SET_STRING_CHUNK, [string_id, offset, buffer], 'S L Z58', 9, 'C'
     end
 
     # Returns a chunk up to 63 bytes from a string object beginning at ``offset`` and
     # returns the resulting error code.
     def get_string_chunk(string_id, offset)
-      send_request FUNCTION_GET_STRING_CHUNK, [string_id, offset], 'S L', 64, 'C Z63'
+      check_validity
+
+      send_request FUNCTION_GET_STRING_CHUNK, [string_id, offset], 'S L', 72, 'C Z63'
     end
 
     # Allocates a new list object and reserves memory for ``length_to_reserve``
@@ -360,12 +385,16 @@ module Tinkerforge
     # When a list object gets destroyed then the reference count of each object in
     # the list object is decreased by one.
     def allocate_list(length_to_reserve, session_id)
-      send_request FUNCTION_ALLOCATE_LIST, [length_to_reserve, session_id], 'S S', 3, 'C S'
+      check_validity
+
+      send_request FUNCTION_ALLOCATE_LIST, [length_to_reserve, session_id], 'S S', 11, 'C S'
     end
 
     # Returns the length of a list object in items and the resulting error code.
     def get_list_length(list_id)
-      send_request FUNCTION_GET_LIST_LENGTH, [list_id], 'S', 3, 'C S'
+      check_validity
+
+      send_request FUNCTION_GET_LIST_LENGTH, [list_id], 'S', 11, 'C S'
     end
 
     # Returns the object ID and type of the object stored at ``index`` in a list
@@ -380,7 +409,9 @@ module Tinkerforge
     # * Process = 4
     # * Program = 5
     def get_list_item(list_id, index, session_id)
-      send_request FUNCTION_GET_LIST_ITEM, [list_id, index, session_id], 'S S S', 4, 'C S C'
+      check_validity
+
+      send_request FUNCTION_GET_LIST_ITEM, [list_id, index, session_id], 'S S S', 12, 'C S C'
     end
 
     # Appends an object to a list object and increases the reference count of the
@@ -388,7 +419,9 @@ module Tinkerforge
     # 
     # Returns the resulting error code.
     def append_to_list(list_id, item_object_id)
-      send_request FUNCTION_APPEND_TO_LIST, [list_id, item_object_id], 'S S', 1, 'C'
+      check_validity
+
+      send_request FUNCTION_APPEND_TO_LIST, [list_id, item_object_id], 'S S', 9, 'C'
     end
 
     # Removes the object stored at ``index`` from a list object and decreases the
@@ -396,7 +429,9 @@ module Tinkerforge
     # 
     # Returns the resulting error code.
     def remove_from_list(list_id, index)
-      send_request FUNCTION_REMOVE_FROM_LIST, [list_id, index], 'S S', 1, 'C'
+      check_validity
+
+      send_request FUNCTION_REMOVE_FROM_LIST, [list_id, index], 'S S', 9, 'C'
     end
 
     # Opens an existing file or creates a new file and allocates a new file object
@@ -441,7 +476,9 @@ module Tinkerforge
     # 
     # Returns the object ID of the new file object and the resulting error code.
     def open_file(name_string_id, flags, permissions, uid, gid, session_id)
-      send_request FUNCTION_OPEN_FILE, [name_string_id, flags, permissions, uid, gid, session_id], 'S L S L L S', 3, 'C S'
+      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
 
     # Creates a new pipe and allocates a new file object for it.
@@ -457,7 +494,9 @@ module Tinkerforge
     # 
     # Returns the object ID of the new file object and the resulting error code.
     def create_pipe(flags, length, session_id)
-      send_request FUNCTION_CREATE_PIPE, [flags, length, session_id], 'L Q S', 3, 'C S'
+      check_validity
+
+      send_request FUNCTION_CREATE_PIPE, [flags, length, session_id], 'L Q S', 11, 'C S'
     end
 
     # Returns various information about a file and the resulting error code.
@@ -484,7 +523,9 @@ module Tinkerforge
     # 
     # FIXME: everything except flags and length is invalid if file type is *Pipe*
     def get_file_info(file_id, session_id)
-      send_request FUNCTION_GET_FILE_INFO, [file_id, session_id], 'S S', 50, 'C C S L S L L Q Q Q Q'
+      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
 
     # Reads up to 62 bytes from a file object.
@@ -500,7 +541,9 @@ module Tinkerforge
     # flag or by BrickRED#create_pipe without the *NonBlockingRead* flag then the
     # error code *NotSupported* is returned.
     def read_file(file_id, length_to_read)
-      send_request FUNCTION_READ_FILE, [file_id, length_to_read], 'S C', 64, 'C C62 C'
+      check_validity
+
+      send_request FUNCTION_READ_FILE, [file_id, length_to_read], 'S C', 72, 'C C62 C'
     end
 
     # Reads up to 2\ :sup:`63`\  - 1 bytes from a file object asynchronously.
@@ -516,7 +559,9 @@ module Tinkerforge
     # flag or by BrickRED#create_pipe without the *NonBlockingRead* flag then the error
     # code *NotSupported* is reported via the CALLBACK_ASYNC_FILE_READ callback.
     def read_file_async(file_id, length_to_read)
-      send_request FUNCTION_READ_FILE_ASYNC, [file_id, length_to_read], 'S Q', 0, ''
+      check_validity
+
+      send_request FUNCTION_READ_FILE_ASYNC, [file_id, length_to_read], 'S Q', 8, ''
     end
 
     # Aborts a BrickRED#read_file_async operation in progress.
@@ -525,7 +570,9 @@ module Tinkerforge
     # 
     # On success the CALLBACK_ASYNC_FILE_READ callback will report *OperationAborted*.
     def abort_async_file_read(file_id)
-      send_request FUNCTION_ABORT_ASYNC_FILE_READ, [file_id], 'S', 1, 'C'
+      check_validity
+
+      send_request FUNCTION_ABORT_ASYNC_FILE_READ, [file_id], 'S', 9, 'C'
     end
 
     # Writes up to 61 bytes to a file object.
@@ -536,7 +583,9 @@ module Tinkerforge
     # flag or by BrickRED#create_pipe without the *NonBlockingWrite* flag then the
     # error code *NotSupported* is returned.
     def write_file(file_id, buffer, length_to_write)
-      send_request FUNCTION_WRITE_FILE, [file_id, buffer, length_to_write], 'S C61 C', 2, 'C C'
+      check_validity
+
+      send_request FUNCTION_WRITE_FILE, [file_id, buffer, length_to_write], 'S C61 C', 10, 'C C'
     end
 
     # Writes up to 61 bytes to a file object.
@@ -548,7 +597,9 @@ module Tinkerforge
     # flag or by BrickRED#create_pipe without the *NonBlockingWrite* flag then the
     # write operation will fail silently.
     def write_file_unchecked(file_id, buffer, length_to_write)
-      send_request FUNCTION_WRITE_FILE_UNCHECKED, [file_id, buffer, length_to_write], 'S C61 C', 0, ''
+      check_validity
+
+      send_request FUNCTION_WRITE_FILE_UNCHECKED, [file_id, buffer, length_to_write], 'S C61 C', 8, ''
     end
 
     # Writes up to 61 bytes to a file object.
@@ -560,10 +611,12 @@ module Tinkerforge
     # flag or by BrickRED#create_pipe without the *NonBlockingWrite* flag then the
     # error code *NotSupported* is reported via the CALLBACK_ASYNC_FILE_WRITE callback.
     def write_file_async(file_id, buffer, length_to_write)
-      send_request FUNCTION_WRITE_FILE_ASYNC, [file_id, buffer, length_to_write], 'S C61 C', 0, ''
+      check_validity
+
+      send_request FUNCTION_WRITE_FILE_ASYNC, [file_id, buffer, length_to_write], 'S C61 C', 8, ''
     end
 
-    # Set the current seek position of a file object in bytes relative to ``origin``.
+    # Set the current seek position of a file object relative to ``origin``.
     # 
     # Possible file origins are:
     # 
@@ -576,26 +629,34 @@ module Tinkerforge
     # If the file object was created by BrickRED#create_pipe then it has no seek
     # position and the error code *InvalidSeek* is returned.
     def set_file_position(file_id, offset, origin)
-      send_request FUNCTION_SET_FILE_POSITION, [file_id, offset, origin], 'S q C', 9, 'C Q'
+      check_validity
+
+      send_request FUNCTION_SET_FILE_POSITION, [file_id, offset, origin], 'S q C', 17, 'C Q'
     end
 
-    # Returns the current seek position of a file object in bytes and returns the
+    # 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.
     def get_file_position(file_id)
-      send_request FUNCTION_GET_FILE_POSITION, [file_id], 'S', 9, 'C Q'
+      check_validity
+
+      send_request FUNCTION_GET_FILE_POSITION, [file_id], 'S', 17, 'C Q'
     end
 
     # 
     def set_file_events(file_id, events)
-      send_request FUNCTION_SET_FILE_EVENTS, [file_id, events], 'S S', 1, 'C'
+      check_validity
+
+      send_request FUNCTION_SET_FILE_EVENTS, [file_id, events], 'S S', 9, 'C'
     end
 
     # 
     def get_file_events(file_id)
-      send_request FUNCTION_GET_FILE_EVENTS, [file_id], 'S', 3, 'C S'
+      check_validity
+
+      send_request FUNCTION_GET_FILE_EVENTS, [file_id], 'S', 11, 'C S'
     end
 
     # Opens an existing directory and allocates a new directory object for it.
@@ -609,13 +670,17 @@ module Tinkerforge
     # 
     # Returns the object ID of the new directory object and the resulting error code.
     def open_directory(name_string_id, session_id)
-      send_request FUNCTION_OPEN_DIRECTORY, [name_string_id, session_id], 'S S', 3, 'C S'
+      check_validity
+
+      send_request FUNCTION_OPEN_DIRECTORY, [name_string_id, session_id], 'S S', 11, 'C S'
     end
 
     # Returns the name of a directory object, as passed to BrickRED#open_directory, and
     # the resulting error code.
     def get_directory_name(directory_id, session_id)
-      send_request FUNCTION_GET_DIRECTORY_NAME, [directory_id, session_id], 'S S', 3, 'C S'
+      check_validity
+
+      send_request FUNCTION_GET_DIRECTORY_NAME, [directory_id, session_id], 'S S', 11, 'C S'
     end
 
     # Returns the next entry in a directory object and the resulting error code.
@@ -634,27 +699,37 @@ module Tinkerforge
     # * Symlink = 6
     # * Socket = 7
     def get_next_directory_entry(directory_id, session_id)
-      send_request FUNCTION_GET_NEXT_DIRECTORY_ENTRY, [directory_id, session_id], 'S S', 4, 'C S C'
+      check_validity
+
+      send_request FUNCTION_GET_NEXT_DIRECTORY_ENTRY, [directory_id, session_id], 'S S', 12, 'C S C'
     end
 
     # Rewinds a directory object and returns the resulting error code.
     def rewind_directory(directory_id)
-      send_request FUNCTION_REWIND_DIRECTORY, [directory_id], 'S', 1, 'C'
+      check_validity
+
+      send_request FUNCTION_REWIND_DIRECTORY, [directory_id], 'S', 9, 'C'
     end
 
     # FIXME: name has to be absolute
     def create_directory(name_string_id, flags, permissions, uid, gid)
-      send_request FUNCTION_CREATE_DIRECTORY, [name_string_id, flags, permissions, uid, gid], 'S L S L L', 1, 'C'
+      check_validity
+
+      send_request FUNCTION_CREATE_DIRECTORY, [name_string_id, flags, permissions, uid, gid], 'S L S L L', 9, 'C'
     end
 
     # 
     def get_processes(session_id)
-      send_request FUNCTION_GET_PROCESSES, [session_id], 'S', 3, 'C S'
+      check_validity
+
+      send_request FUNCTION_GET_PROCESSES, [session_id], 'S', 11, 'C S'
     end
 
     # 
     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)
-      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', 3, 'C S'
+      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
 
     # Sends a UNIX signal to a process object and returns the resulting error code.
@@ -671,14 +746,18 @@ module Tinkerforge
     # * Continue =  18
     # * Stop = 19
     def kill_process(process_id, signal)
-      send_request FUNCTION_KILL_PROCESS, [process_id, signal], 'S C', 1, 'C'
+      check_validity
+
+      send_request FUNCTION_KILL_PROCESS, [process_id, signal], 'S C', 9, 'C'
     end
 
     # 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.
     def get_process_command(process_id, session_id)
-      send_request FUNCTION_GET_PROCESS_COMMAND, [process_id, session_id], 'S S', 9, 'C S S S S'
+      check_validity
+
+      send_request FUNCTION_GET_PROCESS_COMMAND, [process_id, session_id], 'S S', 17, 'C S S S S'
     end
 
     # Returns the process ID and the user and group ID used to spawn a process object,
@@ -687,13 +766,17 @@ module Tinkerforge
     # The process ID is only valid if the state is *Running* or *Stopped*, see
     # BrickRED#get_process_state.
     def get_process_identity(process_id)
-      send_request FUNCTION_GET_PROCESS_IDENTITY, [process_id], 'S', 13, 'C L L L'
+      check_validity
+
+      send_request FUNCTION_GET_PROCESS_IDENTITY, [process_id], 'S', 21, 'C L L L'
     end
 
     # Returns the stdin, stdout and stderr files used to spawn a process object, as
     # passed to BrickRED#spawn_process, and the resulting error code.
     def get_process_stdio(process_id, session_id)
-      send_request FUNCTION_GET_PROCESS_STDIO, [process_id, session_id], 'S S', 7, 'C S S S'
+      check_validity
+
+      send_request FUNCTION_GET_PROCESS_STDIO, [process_id, session_id], 'S S', 15, 'C S S S'
     end
 
     # Returns the current state, timestamp and exit code of a process object, and
@@ -728,114 +811,154 @@ module Tinkerforge
     # The *CannotExecute* error can be caused by the executable being opened for
     # writing.
     def get_process_state(process_id)
-      send_request FUNCTION_GET_PROCESS_STATE, [process_id], 'S', 11, 'C C Q C'
+      check_validity
+
+      send_request FUNCTION_GET_PROCESS_STATE, [process_id], 'S', 19, 'C C Q C'
     end
 
     # 
     def get_programs(session_id)
-      send_request FUNCTION_GET_PROGRAMS, [session_id], 'S', 3, 'C S'
+      check_validity
+
+      send_request FUNCTION_GET_PROGRAMS, [session_id], 'S', 11, 'C S'
     end
 
     # 
     def define_program(identifier_string_id, session_id)
-      send_request FUNCTION_DEFINE_PROGRAM, [identifier_string_id, session_id], 'S S', 3, 'C S'
+      check_validity
+
+      send_request FUNCTION_DEFINE_PROGRAM, [identifier_string_id, session_id], 'S S', 11, 'C S'
     end
 
     # 
     def purge_program(program_id, cookie)
-      send_request FUNCTION_PURGE_PROGRAM, [program_id, cookie], 'S L', 1, 'C'
+      check_validity
+
+      send_request FUNCTION_PURGE_PROGRAM, [program_id, cookie], 'S L', 9, 'C'
     end
 
     # 
     def get_program_identifier(program_id, session_id)
-      send_request FUNCTION_GET_PROGRAM_IDENTIFIER, [program_id, session_id], 'S S', 3, 'C S'
+      check_validity
+
+      send_request FUNCTION_GET_PROGRAM_IDENTIFIER, [program_id, session_id], 'S S', 11, 'C S'
     end
 
     # FIXME: root directory is absolute: <home>/programs/<identifier>
     def get_program_root_directory(program_id, session_id)
-      send_request FUNCTION_GET_PROGRAM_ROOT_DIRECTORY, [program_id, session_id], 'S S', 3, 'C S'
+      check_validity
+
+      send_request FUNCTION_GET_PROGRAM_ROOT_DIRECTORY, [program_id, session_id], 'S S', 11, 'C S'
     end
 
     # FIXME: working directory is relative to <home>/programs/<identifier>/bin
     def set_program_command(program_id, executable_string_id, arguments_list_id, environment_list_id, working_directory_string_id)
-      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', 1, 'C'
+      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
 
     # FIXME: working directory is relative to <home>/programs/<identifier>/bin
     def get_program_command(program_id, session_id)
-      send_request FUNCTION_GET_PROGRAM_COMMAND, [program_id, session_id], 'S S', 9, 'C S S S S'
+      check_validity
+
+      send_request FUNCTION_GET_PROGRAM_COMMAND, [program_id, session_id], 'S S', 17, 'C S S S S'
     end
 
     # FIXME: stdio file names are relative to <home>/programs/<identifier>/bin
     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)
-      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', 1, 'C'
+      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
 
     # FIXME: stdio file names are relative to <home>/programs/<identifier>/bin
     def get_program_stdio_redirection(program_id, session_id)
-      send_request FUNCTION_GET_PROGRAM_STDIO_REDIRECTION, [program_id, session_id], 'S S', 10, 'C C S C S C S'
+      check_validity
+
+      send_request FUNCTION_GET_PROGRAM_STDIO_REDIRECTION, [program_id, session_id], 'S S', 18, 'C C S C S C S'
     end
 
     # 
     def set_program_schedule(program_id, start_mode, continue_after_error, start_interval, start_fields_string_id)
-      send_request FUNCTION_SET_PROGRAM_SCHEDULE, [program_id, start_mode, continue_after_error, start_interval, start_fields_string_id], 'S C ? L S', 1, 'C'
+      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
 
     # 
     def get_program_schedule(program_id, session_id)
-      send_request FUNCTION_GET_PROGRAM_SCHEDULE, [program_id, session_id], 'S S', 9, 'C C ? L S'
+      check_validity
+
+      send_request FUNCTION_GET_PROGRAM_SCHEDULE, [program_id, session_id], 'S S', 17, 'C C ? L S'
     end
 
     # FIXME: message is currently valid in error-occurred state only
     def get_program_scheduler_state(program_id, session_id)
-      send_request FUNCTION_GET_PROGRAM_SCHEDULER_STATE, [program_id, session_id], 'S S', 12, 'C C Q S'
+      check_validity
+
+      send_request FUNCTION_GET_PROGRAM_SCHEDULER_STATE, [program_id, session_id], 'S S', 20, 'C C Q S'
     end
 
     # 
     def continue_program_schedule(program_id)
-      send_request FUNCTION_CONTINUE_PROGRAM_SCHEDULE, [program_id], 'S', 1, 'C'
+      check_validity
+
+      send_request FUNCTION_CONTINUE_PROGRAM_SCHEDULE, [program_id], 'S', 9, 'C'
     end
 
     # 
     def start_program(program_id)
-      send_request FUNCTION_START_PROGRAM, [program_id], 'S', 1, 'C'
+      check_validity
+
+      send_request FUNCTION_START_PROGRAM, [program_id], 'S', 9, 'C'
     end
 
     # 
     def get_last_spawned_program_process(program_id, session_id)
-      send_request FUNCTION_GET_LAST_SPAWNED_PROGRAM_PROCESS, [program_id, session_id], 'S S', 11, 'C S Q'
+      check_validity
+
+      send_request FUNCTION_GET_LAST_SPAWNED_PROGRAM_PROCESS, [program_id, session_id], 'S S', 19, 'C S Q'
     end
 
     # 
     def get_custom_program_option_names(program_id, session_id)
-      send_request FUNCTION_GET_CUSTOM_PROGRAM_OPTION_NAMES, [program_id, session_id], 'S S', 3, 'C S'
+      check_validity
+
+      send_request FUNCTION_GET_CUSTOM_PROGRAM_OPTION_NAMES, [program_id, session_id], 'S S', 11, 'C S'
     end
 
     # 
     def set_custom_program_option_value(program_id, name_string_id, value_string_id)
-      send_request FUNCTION_SET_CUSTOM_PROGRAM_OPTION_VALUE, [program_id, name_string_id, value_string_id], 'S S S', 1, 'C'
+      check_validity
+
+      send_request FUNCTION_SET_CUSTOM_PROGRAM_OPTION_VALUE, [program_id, name_string_id, value_string_id], 'S S S', 9, 'C'
     end
 
     # 
     def get_custom_program_option_value(program_id, name_string_id, session_id)
-      send_request FUNCTION_GET_CUSTOM_PROGRAM_OPTION_VALUE, [program_id, name_string_id, session_id], 'S S S', 3, 'C S'
+      check_validity
+
+      send_request FUNCTION_GET_CUSTOM_PROGRAM_OPTION_VALUE, [program_id, name_string_id, session_id], 'S S S', 11, 'C S'
     end
 
     # 
     def remove_custom_program_option(program_id, name_string_id)
-      send_request FUNCTION_REMOVE_CUSTOM_PROGRAM_OPTION, [program_id, name_string_id], 'S S', 1, 'C'
+      check_validity
+
+      send_request FUNCTION_REMOVE_CUSTOM_PROGRAM_OPTION, [program_id, name_string_id], 'S S', 9, 'C'
     end
 
     # 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 can be '0'-'8' (stack position).
+    # 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|
     def get_identity
-      send_request FUNCTION_GET_IDENTITY, [], '', 25, 'Z8 Z8 k C3 C3 S'
+      send_request FUNCTION_GET_IDENTITY, [], '', 33, 'Z8 Z8 k C3 C3 S'
     end
 
     # Registers a callback with ID <tt>id</tt> to the block <tt>block</tt>.