Snapex7 v0.1.1 Snapex7.Client 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
area: :PA
word_len: :byte
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
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
area: :CT
word_len: :timer
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
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
area: :DB
word_len: :byte
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
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
area: :PE
word_len: :byte
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
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
Invoked when the server is started. start_link/3
or start/3
will
block until it returns
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
area: :MK
word_len: :byte
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
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
area: :TM
word_len: :timer
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
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
Link to this section Functions
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.
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
.
clear_session_password(GenServer.server()) :: :ok | {:error, map()} | {:error, :einval}
Clears the password set for the current session (logout).
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
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).
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
.
connect_to(GenServer.server(), [connect_opt()]) :: :ok | {:error, map()} | {:error, :einval}
Connect to a S7 server. The following options are available:
:active
- (true
orfalse
) 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.
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)
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.
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.
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.
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.
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.
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.
delete(GenServer.server(), atom(), integer()) :: :ok | {:error, map()} | {:error, :einval}
Deletes a block from AG. (There is an undo function available).
disconnect(GenServer.server()) :: :ok | {:error, map()} | {:error, :einval}
Disconnects “gracefully” the Client from the PLC.
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.
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.
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.
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).
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).
get_connected(GenServer.server()) :: {:ok, boolean()} | {:error, map()} | {:error, :einval}
Returns the connection status.
get_cp_info(GenServer.server()) :: {:ok, list()} | {:error, map()} | {:error, :einval}
Gets CP (communication processor) info.
get_cpu_info(GenServer.server()) :: {:ok, list()} | {:error, map()} | {:error, :einval}
Gets CPU module name, serial number and other info.
get_exec_time(GenServer.server()) :: {:ok, integer()} | {:error, map()} | {:error, :einval}
Returns the last job execution time in miliseconds.
get_last_error(GenServer.server()) :: {:ok, map()} | {:error, map()} | {:error, :einval}
Returns the last job result.
get_order_code(GenServer.server()) :: {:ok, list()} | {:error, map()} | {:error, :einval}
Gets CPU order code and version info.
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.
get_pdu_length(GenServer.server()) :: {:ok, list()} | {:error, map()} | {:error, :einval}
Returns info about the PDU length.
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.
get_plc_date_time(GenServer.server()) :: {:ok, term(), term()} | {:error, map()} | {:error, :einval}
Reads PLC date and time, if successful, returns {:ok, date, time}
get_plc_status(GenServer.server()) :: :ok | {:error, map()} | {:error, :einval}
Returns the CPU status (running/stoppped).
get_protection(GenServer.server()) :: :ok | {:error, map()} | {:error, :einval}
Gets the CPU protection level info.
Invoked when the server is started. start_link/3
or start/3
will
block until it returns.
args
is the argument term (second argument) passed to start_link/3
.
Returning {:ok, state}
will cause start_link/3
to return
{:ok, pid}
and the process to enter its loop.
Returning {:ok, state, timeout}
is similar to {:ok, state}
except handle_info(:timeout, state)
will be called after timeout
milliseconds if no messages are received within the timeout.
Returning {:ok, state, :hibernate}
is similar to {:ok, state}
except the process is hibernated before entering the loop. See
c:handle_call/3
for more information on hibernation.
Returning {:ok, state, {:continue, continue}}
is similar to
{:ok, state}
except that immediately after entering the loop
the c:handle_continue/2
callback will be invoked with the value
continue
as first argument.
Returning :ignore
will cause start_link/3
to return :ignore
and
the process will exit normally without entering the loop or calling
c:terminate/2
. If used when part of a supervision tree the parent
supervisor will not fail to start nor immediately try to restart the
GenServer
. The remainder of the supervision tree will be started
and so the GenServer
should not be required by other processes.
It can be started later with Supervisor.restart_child/2
as the child
specification is saved in the parent supervisor. The main use cases for
this are:
- The
GenServer
is disabled by configuration but might be enabled later. - An error occurred and it will be handled by a different mechanism than the
Supervisor
. Likely this approach involves callingSupervisor.restart_child/2
after a delay to attempt a restart.
Returning {:stop, reason}
will cause start_link/3
to return
{:error, reason}
and the process to exit with reason reason
without
entering the loop or calling c:terminate/2
.
Callback implementation for GenServer.init/1
.
iso_exchange_buffer(GenServer.server(), bitstring()) :: :ok | {:error, map()} | {:error, :einval}
Exchanges a given S7 PDU (protocol data unit) with the CPU.
list_blocks(GenServer.server()) :: {:ok, list()} | {:error, map()} | {:error, :einval}
This function returns the AG blocks amount divided by type.
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.
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.
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.
plc_cold_start(GenServer.server()) :: :ok | {:error, map()} | {:error, :einval}
Puts the CPU in RUN mode performing an COLD START.
plc_hot_start(GenServer.server()) :: :ok | {:error, map()} | {:error, :einval}
Puts the CPU in RUN mode performing an HOT START.
plc_stop(GenServer.server()) :: :ok | {:error, map()} | {:error, :einval}
Puts the CPU in STOP mode.
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, ifarea: :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.
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.
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.
read_szl_list(GenServer.server()) :: {:ok, list()} | {:error, map()} | {:error, :einval}
Reads the directory of the partial list
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.
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.
set_params(GenServer.server(), integer(), integer()) :: :ok | {:error, map()} | {:error, :einval}
Sets an internal Client object parameter.
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.
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.
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.
Start up a Snap7 Client GenServer.
Stop the Snap7 Client GenServer.
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.
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.
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_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, ifarea: :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.
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.