Snapex7.Client (Snapex7 v0.1.3) View Source

Link to this section Summary

Functions

This is a lean function of read_area/2 to read PLC process outputs. It simply internally calls read_area/2 with

This is a lean function of write_area/2 to write PLC process outputs. It simply internally calls read_area/2 with

Returns a specification to start this module under a supervisor.

Clears the password set for the current session (logout).

This function can execute any desired function as a request. The request can be a tuple (the first element is an atom according to the desired function to be executed, and the following elements are the args of the desired function) or an atom (when the desired function has no arguments), for example: request = {:connect_to , [ip: "192.168.1.100", rack: 0, slot: 0]}, request = :get_connected

Performas the Memory compress action (not all CPU's supports this function and the CPU must be in STOP mode).

Connects the client to the PLC with the parameters specified in the previous call of connect_to/2 or set_connection_params/2.

Connect to a S7 server. The following options are available

Performs the copy ram to rom action. (CPU must be in STOP mode)

This is a lean function of read_area/2 to read PLC Counters. It simply internally calls read_area/2 with

This is a lean function of write_area/2 to write PLC Counters. It simply internally calls read_area/2 with

Fills a DB in AG qirh a given byte without the need of specifying its size.

Uploads a DB from AG. This function is equivalent to upload/4 with block_type = :DB but it uses a different approach so it's not subject to the security level set. Only data is uploaded.

This is a lean function of read_area/2 to read PLC DB. It simply internally calls read_area/2 with

This is a lean function of write_area/2 to write PLC DB. It simply internally calls read_area/2 with

Deletes a block from AG. (There is an undo function available).

Disconnects “gracefully” the Client from the PLC.

Downloads a block from AG. (gets a block from PLC) The whole block (including header and footer) must be available into the user buffer.

This is a lean function of read_area/2 to read PLC process inputs. It simply internally calls read_area/2 with

This is a lean function of write_area/2 to write PLC process inputs. It simply internally calls read_area/2 with

Uploads a block from AG. (gets a block from PLC) The whole block (including header and footer) is copied into the user buffer (as bytes).

Return detail information about an AG given block. This function is very useful if you nead to read or write data in a DB which you do not know the size in advance (see pg 127).

Returns the connection status.

Gets CP (communication processor) info.

Gets CPU module name, serial number and other info.

Returns the last job execution time in miliseconds.

Returns the last job result.

Gets CPU order code and version info.

Reads an internal Client object parameter. For more info see pg. 89 form Snap7 docs.

Returns info about the PDU length.

Return detailed information about a block present in a user buffer. This function is usually used in conjunction with full_upload/2. An uploaded a block saved to disk, could be loaded in a user buffer and checked with this function.

Reads PLC date and time, if successful, returns {:ok, date, time}

Returns the CPU status (running/stoppped).

Gets the CPU protection level info.

Callback implementation for GenServer.init/1.

Exchanges a given S7 PDU (protocol data unit) with the CPU.

This function returns the AG blocks amount divided by type.

This function returns the AG list of a specified block type.

This is a lean function of read_area/2 to read PLC merkers. It simply internally calls read_area/2 with

This is a lean function of write_area/2 to write PLC merkers. It simply internally calls read_area/2 with

Puts the CPU in RUN mode performing an COLD START.

Puts the CPU in RUN mode performing an HOT START.

Puts the CPU in STOP mode.

Reads a data area from a PLC. The following options are available

This function allows to read different kind of variables from a PLC in a single call. With it can read DB, inputs, outputs, Merkers, Timers and Counters.

Reads a partial list of given ID and INDEX See System Software for S7-300/400 System and Standard Functions Volume 1 and Volume 2 for ID and INDEX info (chapter 13.3), look for TIA Portal Information Systems for DR data type.

Reads the directory of the partial list

Sets internally (IP, LocalTSAP, RemoteTSAP) Coordinates The following options are available

Sets the connection resource type, i.e the way in which the Clients connects to a PLC.

Sets an internal Client object parameter.

Sets PLC date and time. The following options are available

Sets the PLC date and time in accord to the PC system Date/Time.

Send the password (an 8 chars string) to the PLC to meet its security level.

Start up a Snap7 Client GenServer.

Stop the Snap7 Client GenServer.

This is a lean function of read_area/2 to read PLC Timers. It simply internally calls read_area/2 with

This is a lean function of write_area/2 to write PLC Timers. It simply internally calls read_area/2 with

Uploads a block from AG. (gets a block from PLC) Only the block body (but header and footer) is copied into the user buffer (as bytes).

Write a data area from a PLC. The following options are available

This function allows to write different kind of variables from a PLC in a single call. With it can read DB, inputs, outputs, Merkers, Timers and Counters.

Link to this section Types

Specs

connect_opt() ::
  {:ip, bitstring()}
  | {:rack, 0..7}
  | {:slot, 1..31}
  | {:local_tsap, integer()}
  | {:remote_tsap, integer()}

Specs

data_io_opt() ::
  {:area, atom()}
  | {:db_number, integer()}
  | {:start, integer()}
  | {:amount, integer()}
  | {:word_len, atom()}
  | {:data, bitstring()}

Specs

plc_time_opt() ::
  {:sec, 0..59}
  | {:min, 0..7}
  | {:hour, 0..23}
  | {:mday, 1..31}
  | {:mon, 1..12}
  | {:year, integer()}
  | {:wday, 0..6}
  | {:yday, 0..365}
  | {:isdst, integer()}

Link to this section Functions

Specs

ab_read(GenServer.server(), [data_io_opt()]) ::
  {:ok, bitstring()} | {:error, map()} | {:error, :einval}

This is a lean function of read_area/2 to read PLC process outputs. It simply internally calls read_area/2 with

  • area: :PA
  • word_len: :byte

The following options are available:

  • :start - (int) An offset to start.

  • :amount - (int) Amount of words (bytes) to read/write .

For more info see pg. 104 form Snap7 docs.

Specs

ab_write(GenServer.server(), [data_io_opt()]) ::
  :ok | {:error, map()} | {:error, :einval}

This is a lean function of write_area/2 to write PLC process outputs. It simply internally calls read_area/2 with

  • area: :PA
  • word_len: :byte

The following options are available:

  • :start - (int) An offset to start.

  • :amount - (int) Amount of words (bytes) to read/write.

  • :data - (bitstring) buffer to write.

For more info see pg. 104 form Snap7 docs.

Returns a specification to start this module under a supervisor.

See Supervisor.

Link to this function

clear_session_password(pid)

View Source

Specs

clear_session_password(GenServer.server()) ::
  :ok | {:error, map()} | {:error, :einval}

Clears the password set for the current session (logout).

Specs

command(GenServer.server(), term()) ::
  :ok | {:ok, term()} | {:error, map()} | {:error, :einval}

This function can execute any desired function as a request. The request can be a tuple (the first element is an atom according to the desired function to be executed, and the following elements are the args of the desired function) or an atom (when the desired function has no arguments), for example: request = {:connect_to , [ip: "192.168.1.100", rack: 0, slot: 0]}, request = :get_connected

Link to this function

compress(pid, timeout \\ 1000)

View Source

Specs

compress(GenServer.server(), integer()) ::
  :ok | {:error, map()} | {:error, :einval}

Performas the Memory compress action (not all CPU's supports this function and the CPU must be in STOP mode).

Specs

connect(GenServer.server()) :: :ok | {:error, map()} | {:error, :einval}

Connects the client to the PLC with the parameters specified in the previous call of connect_to/2 or set_connection_params/2.

Link to this function

connect_to(pid, opts \\ [])

View Source

Specs

connect_to(GenServer.server(), [connect_opt()]) ::
  :ok | {:error, map()} | {:error, :einval}

Connect to a S7 server. The following options are available:

  • :active - (true or false) specifies whether data is received as messages or by calling "Data I/O functions".

  • :ip - (string) PLC/Equipment IPV4 Address (e.g., "192.168.0.1")

  • :rack - (int) PLC Rack number (0..7).

  • :slot - (int) PLC Slot number (1..31).

For more info see pg. 96 form Snap7 docs.

Link to this function

copy_ram_to_rom(pid, timeout \\ 1000)

View Source

Specs

copy_ram_to_rom(GenServer.server(), integer()) ::
  :ok | {:error, map()} | {:error, :einval}

Performs the copy ram to rom action. (CPU must be in STOP mode)

Specs

ct_read(GenServer.server(), [data_io_opt()]) ::
  {:ok, bitstring()} | {:error, map()} | {:error, :einval}

This is a lean function of read_area/2 to read PLC Counters. It simply internally calls read_area/2 with

  • area: :CT
  • word_len: :timer

The following options are available:

  • :start - (int) An offset to start.

  • :amount - (int) Amount of words (bytes) to read/write .

For more info see pg. 104 form Snap7 docs.

Specs

ct_write(GenServer.server(), [data_io_opt()]) ::
  :ok | {:error, map()} | {:error, :einval}

This is a lean function of write_area/2 to write PLC Counters. It simply internally calls read_area/2 with

  • area: :CT
  • word_len: :timer

The following options are available:

  • :start - (int) An offset to start.

  • :amount - (int) Amount of words (bytes) to read/write.

  • :data - (bitstring) buffer to write.

For more info see pg. 104 form Snap7 docs.

Link to this function

db_fill(pid, db_number, fill_char)

View Source

Specs

db_fill(GenServer.server(), integer(), integer()) ::
  {:ok, list()} | {:error, map()} | {:error, :einval}

Fills a DB in AG qirh a given byte without the need of specifying its size.

Link to this function

db_get(pid, db_number, size \\ 65536)

View Source

Specs

db_get(GenServer.server(), integer(), integer()) ::
  {:ok, list()} | {:error, map()} | {:error, :einval}

Uploads a DB from AG. This function is equivalent to upload/4 with block_type = :DB but it uses a different approach so it's not subject to the security level set. Only data is uploaded.

Specs

db_read(GenServer.server(), [data_io_opt()]) ::
  {:ok, bitstring()} | {:error, map()} | {:error, :einval}

This is a lean function of read_area/2 to read PLC DB. It simply internally calls read_area/2 with

  • area: :DB
  • word_len: :byte

The following options are available:

  • :db_number - (int) DB number (0..0xFFFF).

  • :start - (int) An offset to start.

  • :amount - (int) Amount of words (bytes) to read/write.

For more info see pg. 104 form Snap7 docs.

Specs

db_write(GenServer.server(), [data_io_opt()]) ::
  :ok | {:error, map()} | {:error, :einval}

This is a lean function of write_area/2 to write PLC DB. It simply internally calls read_area/2 with

  • area: :DB
  • word_len: :byte

The following options are available:

  • :db_number - (int) DB number (0..0xFFFF).

  • :start - (int) An offset to start.

  • :amount - (int) Amount of words (bytes) to read/write.

  • :data - (bitstring) buffer to write.

For more info see pg. 104 form Snap7 docs.

Link to this function

delete(pid, block_type, block_num)

View Source

Specs

delete(GenServer.server(), atom(), integer()) ::
  :ok | {:error, map()} | {:error, :einval}

Deletes a block from AG. (There is an undo function available).

Specs

disconnect(GenServer.server()) :: :ok | {:error, map()} | {:error, :einval}

Disconnects “gracefully” the Client from the PLC.

Link to this function

download(pid, block_num, buffer)

View Source

Specs

download(GenServer.server(), integer(), bitstring()) ::
  :ok | {:error, map()} | {:error, :einval}

Downloads a block from AG. (gets a block from PLC) The whole block (including header and footer) must be available into the user buffer.

Specs

eb_read(GenServer.server(), [data_io_opt()]) ::
  {:ok, bitstring()} | {:error, map()} | {:error, :einval}

This is a lean function of read_area/2 to read PLC process inputs. It simply internally calls read_area/2 with

  • area: :PE
  • word_len: :byte

The following options are available:

  • :start - (int) An offset to start.

  • :amount - (int) Amount of words (bytes) to read/write .

For more info see pg. 104 form Snap7 docs.

Specs

eb_write(GenServer.server(), [data_io_opt()]) ::
  :ok | {:error, map()} | {:error, :einval}

This is a lean function of write_area/2 to write PLC process inputs. It simply internally calls read_area/2 with

  • area: :PE
  • word_len: :byte

The following options are available:

  • :start - (int) An offset to start.

  • :amount - (int) Amount of words (bytes) to read/write.

  • :data - (bitstring) buffer to write.

For more info see pg. 104 form Snap7 docs.

Link to this function

full_upload(pid, block_type, block_num, bytes2read)

View Source

Specs

full_upload(GenServer.server(), atom(), integer(), integer()) ::
  {:ok, bitstring()} | {:error, map()} | {:error, :einval}

Uploads a block from AG. (gets a block from PLC) The whole block (including header and footer) is copied into the user buffer (as bytes).

Link to this function

get_ag_block_info(pid, block_type, block_num)

View Source

Specs

get_ag_block_info(GenServer.server(), atom(), integer()) ::
  {:ok, list()} | {:error, map()} | {:error, :einval}

Return detail information about an AG given block. This function is very useful if you nead to read or write data in a DB which you do not know the size in advance (see pg 127).

Specs

get_connected(GenServer.server()) ::
  {:ok, boolean()} | {:error, map()} | {:error, :einval}

Returns the connection status.

Specs

get_cp_info(GenServer.server()) ::
  {:ok, list()} | {:error, map()} | {:error, :einval}

Gets CP (communication processor) info.

Specs

get_cpu_info(GenServer.server()) ::
  {:ok, list()} | {:error, map()} | {:error, :einval}

Gets CPU module name, serial number and other info.

Specs

get_exec_time(GenServer.server()) ::
  {:ok, integer()} | {:error, map()} | {:error, :einval}

Returns the last job execution time in miliseconds.

Specs

get_last_error(GenServer.server()) ::
  {:ok, map()} | {:error, map()} | {:error, :einval}

Returns the last job result.

Specs

get_order_code(GenServer.server()) ::
  {:ok, list()} | {:error, map()} | {:error, :einval}

Gets CPU order code and version info.

Link to this function

get_params(pid, param_number)

View Source

Specs

get_params(GenServer.server(), integer()) ::
  :ok | {:error, map()} | {:error, :einval}

Reads an internal Client object parameter. For more info see pg. 89 form Snap7 docs.

Specs

get_pdu_length(GenServer.server()) ::
  {:ok, list()} | {:error, map()} | {:error, :einval}

Returns info about the PDU length.

Link to this function

get_pg_block_info(pid, buffer)

View Source

Specs

get_pg_block_info(GenServer.server(), bitstring()) ::
  {:ok, list()} | {:error, map()} | {:error, :einval}

Return detailed information about a block present in a user buffer. This function is usually used in conjunction with full_upload/2. An uploaded a block saved to disk, could be loaded in a user buffer and checked with this function.

Specs

get_plc_date_time(GenServer.server()) ::
  {:ok, term(), term()} | {:error, map()} | {:error, :einval}

Reads PLC date and time, if successful, returns {:ok, date, time}

Specs

get_plc_status(GenServer.server()) :: :ok | {:error, map()} | {:error, :einval}

Returns the CPU status (running/stoppped).

Specs

get_protection(GenServer.server()) :: :ok | {:error, map()} | {:error, :einval}

Gets the CPU protection level info.

Specs

init([]) :: {:ok, Snapex7.Client.State.t()}

Callback implementation for GenServer.init/1.

Link to this function

iso_exchange_buffer(pid, buffer)

View Source

Specs

iso_exchange_buffer(GenServer.server(), bitstring()) ::
  :ok | {:error, map()} | {:error, :einval}

Exchanges a given S7 PDU (protocol data unit) with the CPU.

Specs

list_blocks(GenServer.server()) ::
  {:ok, list()} | {:error, map()} | {:error, :einval}

This function returns the AG blocks amount divided by type.

Link to this function

list_blocks_of_type(pid, block_type, n_items)

View Source

Specs

list_blocks_of_type(GenServer.server(), atom(), integer()) ::
  {:ok, list()} | {:error, map()} | {:error, :einval}

This function returns the AG list of a specified block type.

Specs

mb_read(GenServer.server(), [data_io_opt()]) ::
  {:ok, bitstring()} | {:error, map()} | {:error, :einval}

This is a lean function of read_area/2 to read PLC merkers. It simply internally calls read_area/2 with

  • area: :MK
  • word_len: :byte

The following options are available:

  • :start - (int) An offset to start.

  • :amount - (int) Amount of words (bytes) to read/write .

For more info see pg. 104 form Snap7 docs.

Specs

mb_write(GenServer.server(), [data_io_opt()]) ::
  :ok | {:error, map()} | {:error, :einval}

This is a lean function of write_area/2 to write PLC merkers. It simply internally calls read_area/2 with

  • area: :MK
  • word_len: :byte

The following options are available:

  • :start - (int) An offset to start.

  • :amount - (int) Amount of words (bytes) to read/write.

  • :data - (bitstring) buffer to write.

For more info see pg. 104 form Snap7 docs.

Specs

plc_cold_start(GenServer.server()) :: :ok | {:error, map()} | {:error, :einval}

Puts the CPU in RUN mode performing an COLD START.

Specs

plc_hot_start(GenServer.server()) :: :ok | {:error, map()} | {:error, :einval}

Puts the CPU in RUN mode performing an HOT START.

Specs

plc_stop(GenServer.server()) :: :ok | {:error, map()} | {:error, :einval}

Puts the CPU in STOP mode.

Specs

read_area(GenServer.server(), [data_io_opt()]) ::
  {:ok, bitstring()} | {:error, map()} | {:error, :einval}

Reads a data area from a PLC. The following options are available:

  • :area - (atom) Area Identifier (see @area_types).

  • :db_number - (int) DB number, if area: :DB otherwise is ignored.

  • :start - (int) An offset to start.

  • :amount - (int) Amount of words to read/write.

  • :word_len - (atom) Word size (see @word_types).

For more info see pg. 104 form Snap7 docs.

Link to this function

read_multi_vars(pid, opt)

View Source

Specs

read_multi_vars(GenServer.server(), list()) ::
  {:ok, bitstring()} | {:error, map()} | {:error, :einval}

This function allows to read different kind of variables from a PLC in a single call. With it can read DB, inputs, outputs, Merkers, Timers and Counters.

The following options are available:

  • :data - (list of maps) a list of requests (maps with @data_io_opt options as keys) to read from PLC.

For more info see pg. 119 form Snap7 docs.

Link to this function

read_szl(pid, id, index)

View Source

Specs

read_szl(GenServer.server(), integer(), integer()) ::
  {:ok, bitstring()} | {:error, map()} | {:error, :einval}

Reads a partial list of given ID and INDEX See System Software for S7-300/400 System and Standard Functions Volume 1 and Volume 2 for ID and INDEX info (chapter 13.3), look for TIA Portal Information Systems for DR data type.

Specs

read_szl_list(GenServer.server()) ::
  {:ok, list()} | {:error, map()} | {:error, :einval}

Reads the directory of the partial list

Link to this function

set_connection_params(pid, opts \\ [])

View Source

Specs

set_connection_params(GenServer.server(), [connect_opt()]) ::
  :ok | {:error, map()} | {:error, :einval}

Sets internally (IP, LocalTSAP, RemoteTSAP) Coordinates The following options are available:

  • :ip - (string) PLC/Equipment IPV4 Address (e.g., "192.168.0.1")

  • :local_tsap - (int) Local TSAP (PC TSAP) // 0.

  • :remote_tsap - (int) Remote TSAP (PLC TSAP) // 0.

Link to this function

set_connection_type(pid, connection_type)

View Source

Specs

set_connection_type(GenServer.server(), atom()) ::
  :ok | {:error, map()} | {:error, :einval}

Sets the connection resource type, i.e the way in which the Clients connects to a PLC.

Link to this function

set_params(pid, param_number, value)

View Source

Specs

set_params(GenServer.server(), integer(), integer()) ::
  :ok | {:error, map()} | {:error, :einval}

Sets an internal Client object parameter.

Link to this function

set_plc_date_time(pid, opts \\ [])

View Source

Specs

set_plc_date_time(GenServer.server(), [plc_time_opt()]) ::
  :ok | {:error, map()} | {:error, :einval}

Sets PLC date and time. The following options are available:

  • :sec - (int) seconds afer the minute (0..59).

  • :min - (int) minutes after the hour (0..59).

  • :hour - (int) hour since midnight (0..23).

  • :mday - (int) day of the month (1..31).

  • :mon - (int) month since January (1..12).

  • :year - (int) year (1900...).

  • :wday - (int) days since Sunday (0..6).

  • :yday - (int) days since January 1 (0..365).

  • :isdst - (int) Daylight Saving Time flag.

The default is of all functions are the minimum value.

Link to this function

set_plc_system_date_time(pid)

View Source

Specs

set_plc_system_date_time(GenServer.server()) ::
  :ok | {:error, map()} | {:error, :einval}

Sets the PLC date and time in accord to the PC system Date/Time.

Link to this function

set_session_password(pid, password)

View Source

Specs

set_session_password(GenServer.server(), bitstring()) ::
  :ok | {:error, map()} | {:error, :einval}

Send the password (an 8 chars string) to the PLC to meet its security level.

Specs

start_link([term()]) :: {:ok, pid()} | {:error, term()} | {:error, :einval}

Start up a Snap7 Client GenServer.

Specs

stop(GenServer.server()) :: :ok

Stop the Snap7 Client GenServer.

Specs

tm_read(GenServer.server(), [data_io_opt()]) ::
  {:ok, bitstring()} | {:error, map()} | {:error, :einval}

This is a lean function of read_area/2 to read PLC Timers. It simply internally calls read_area/2 with

  • area: :TM
  • word_len: :timer

The following options are available:

  • :start - (int) An offset to start.

  • :amount - (int) Amount of words (bytes) to read/write .

For more info see pg. 104 form Snap7 docs.

Specs

tm_write(GenServer.server(), [data_io_opt()]) ::
  :ok | {:error, map()} | {:error, :einval}

This is a lean function of write_area/2 to write PLC Timers. It simply internally calls read_area/2 with

  • area: :TM
  • word_len: :timer

The following options are available:

  • :start - (int) An offset to start.

  • :amount - (int) Amount of words (bytes) to read/write.

  • :data - (bitstring) buffer to write.

For more info see pg. 104 form Snap7 docs.

Link to this function

upload(pid, block_type, block_num, bytes2read)

View Source

Specs

upload(GenServer.server(), atom(), integer(), integer()) ::
  {:ok, bitstring()} | {:error, map()} | {:error, :einval}

Uploads a block from AG. (gets a block from PLC) Only the block body (but header and footer) is copied into the user buffer (as bytes).

Specs

write_area(GenServer.server(), [data_io_opt()]) ::
  :ok | {:error, map()} | {:error, :einval}

Write a data area from a PLC. The following options are available:

  • :area - (atom) Area Identifier (see @area_types).

  • :db_number - (int) DB number, if area: :DB otherwise is ignored.

  • :start - (int) An offset to start.

  • :amount - (int) Amount of words to read/write.

  • :word_len - (atom) Word size (see @word_types).

  • :data - (atom) buffer to write.

For more info see pg. 104 form Snap7 docs.

Link to this function

write_multi_vars(pid, opts)

View Source

Specs

write_multi_vars(GenServer.server(), [data_io_opt()]) ::
  :ok | {:error, map()} | {:error, :einval}

This function allows to write different kind of variables from a PLC in a single call. With it can read DB, inputs, outputs, Merkers, Timers and Counters.

The following options are available:

  • :data - (list of maps) a list of requests (maps with @data_io_opt options as keys) to read from PLC.

For more info see pg. 119 form Snap7 docs.