17 * GNU Lesser General Public License for more details. |
17 * GNU Lesser General Public License for more details. |
18 * |
18 * |
19 * You should have received a copy of the GNU Lesser General Public License |
19 * You should have received a copy of the GNU Lesser General Public License |
20 * along with the IgH EtherCAT master userspace library. If not, see |
20 * along with the IgH EtherCAT master userspace library. If not, see |
21 * <http://www.gnu.org/licenses/>. |
21 * <http://www.gnu.org/licenses/>. |
22 * |
22 * |
23 * --- |
23 * --- |
24 * |
24 * |
25 * The license mentioned above concerns the source code only. Using the |
25 * The license mentioned above concerns the source code only. Using the |
26 * EtherCAT technology and brand is only permitted in compliance with the |
26 * EtherCAT technology and brand is only permitted in compliance with the |
27 * industrial property and similar rights of Beckhoff Automation GmbH. |
27 * industrial property and similar rights of Beckhoff Automation GmbH. |
28 * |
28 * |
29 *****************************************************************************/ |
29 *****************************************************************************/ |
45 * ecrt_slave_config_dc() to configure a slave for cyclic operation, and |
45 * ecrt_slave_config_dc() to configure a slave for cyclic operation, and |
46 * ecrt_master_application_time(), ecrt_master_sync_reference_clock() and |
46 * ecrt_master_application_time(), ecrt_master_sync_reference_clock() and |
47 * ecrt_master_sync_slave_clocks() for offset and drift compensation. The |
47 * ecrt_master_sync_slave_clocks() for offset and drift compensation. The |
48 * EC_TIMEVAL2NANO() macro can be used for epoch time conversion, while the |
48 * EC_TIMEVAL2NANO() macro can be used for epoch time conversion, while the |
49 * ecrt_master_sync_monitor_queue() and ecrt_master_sync_monitor_process() |
49 * ecrt_master_sync_monitor_queue() and ecrt_master_sync_monitor_process() |
50 * methods can be used to monitor the synchrony. |
50 * methods can be used to monitor the synchrony. |
51 * - Improved the callback mechanism. ecrt_master_callbacks() now takes two |
51 * - Improved the callback mechanism. ecrt_master_callbacks() now takes two |
52 * callback functions for sending and receiving datagrams. |
52 * callback functions for sending and receiving datagrams. |
53 * ecrt_master_send_ext() is used to execute the sending of non-application |
53 * ecrt_master_send_ext() is used to execute the sending of non-application |
54 * datagrams. |
54 * datagrams. |
55 * - Added watchdog configuration (method ecrt_slave_config_watchdog(), |
55 * - Added watchdog configuration (method ecrt_slave_config_watchdog(), |
221 * \see ecrt_master(). |
224 * \see ecrt_master(). |
222 */ |
225 */ |
223 typedef struct { |
226 typedef struct { |
224 unsigned int slave_count; /**< Number of slaves in the bus. */ |
227 unsigned int slave_count; /**< Number of slaves in the bus. */ |
225 unsigned int link_up : 1; /**< \a true, if the network link is up. */ |
228 unsigned int link_up : 1; /**< \a true, if the network link is up. */ |
226 uint8_t scan_busy; /**< \a true, while the master is scanning the bus */ |
229 uint8_t scan_busy; /**< \a true, while the master is scanning the bus */ |
227 uint64_t app_time; /**< Application time. */ |
230 uint64_t app_time; /**< Application time. */ |
228 } ec_master_info_t; |
231 } ec_master_info_t; |
|
232 |
|
233 /*****************************************************************************/ |
|
234 |
|
235 /** EtherCAT slave port descriptor. |
|
236 */ |
|
237 typedef enum { |
|
238 EC_PORT_NOT_IMPLEMENTED, /**< Port is not implemented. */ |
|
239 EC_PORT_NOT_CONFIGURED, /**< Port is not configured. */ |
|
240 EC_PORT_EBUS, /**< Port is an e-bus. */ |
|
241 EC_PORT_MII /**< Port is a mii. */ |
|
242 } ec_slave_port_desc_t; |
|
243 |
|
244 /*****************************************************************************/ |
|
245 |
|
246 /** EtherCAT slave port information. |
|
247 */ |
|
248 typedef struct { |
|
249 uint8_t link_up; /**< Link detected. */ |
|
250 uint8_t loop_closed; /**< Loop closed. */ |
|
251 uint8_t signal_detected; /**< Detected signal on RX port. */ |
|
252 } ec_slave_port_link_t; |
229 |
253 |
230 /*****************************************************************************/ |
254 /*****************************************************************************/ |
231 |
255 |
232 /** Slave information. |
256 /** Slave information. |
233 * |
257 * |
241 uint32_t product_code; /**< Product-Code stored on the slave. */ |
265 uint32_t product_code; /**< Product-Code stored on the slave. */ |
242 uint32_t revision_number; /**< Revision-Number stored on the slave. */ |
266 uint32_t revision_number; /**< Revision-Number stored on the slave. */ |
243 uint32_t serial_number; /**< Serial-Number stored on the slave. */ |
267 uint32_t serial_number; /**< Serial-Number stored on the slave. */ |
244 uint16_t alias; /**< The slaves alias if not equal to 0. */ |
268 uint16_t alias; /**< The slaves alias if not equal to 0. */ |
245 int16_t current_on_ebus; /**< Used current in mA. */ |
269 int16_t current_on_ebus; /**< Used current in mA. */ |
|
270 struct { |
|
271 ec_slave_port_desc_t desc; |
|
272 ec_slave_port_link_t link; |
|
273 uint32_t receive_time; |
|
274 uint16_t next_slave; |
|
275 uint32_t delay_to_next_dc; |
|
276 } ports[EC_MAX_PORTS]; |
246 uint8_t al_state; /**< Current state of the slave. */ |
277 uint8_t al_state; /**< Current state of the slave. */ |
247 uint8_t error_flag; /**< Error flag for that slave. */ |
278 uint8_t error_flag; /**< Error flag for that slave. */ |
248 uint8_t sync_count; /**< Number of sync managers. */ |
279 uint8_t sync_count; /**< Number of sync managers. */ |
249 uint16_t sdo_count; /**< Number of SDOs. */ |
280 uint16_t sdo_count; /**< Number of SDOs. */ |
250 char name[EC_MAX_STRING_LENGTH]; /**< Name of the slave. */ |
281 char name[EC_MAX_STRING_LENGTH]; /**< Name of the slave. */ |
312 } ec_pdo_entry_info_t; |
343 } ec_pdo_entry_info_t; |
313 |
344 |
314 /*****************************************************************************/ |
345 /*****************************************************************************/ |
315 |
346 |
316 /** PDO configuration information. |
347 /** PDO configuration information. |
317 * |
348 * |
318 * This is the data type of the \a pdos field in ec_sync_info_t. |
349 * This is the data type of the \a pdos field in ec_sync_info_t. |
319 * |
350 * |
320 * \see ecrt_slave_config_pdos(). |
351 * \see ecrt_slave_config_pdos(). |
321 */ |
352 */ |
322 typedef struct { |
353 typedef struct { |
323 uint16_t index; /**< PDO index. */ |
354 uint16_t index; /**< PDO index. */ |
324 unsigned int n_entries; /**< Number of PDO entries in \a entries to map. |
355 unsigned int n_entries; /**< Number of PDO entries in \a entries to map. |
363 uint32_t product_code; /**< Slave product code. */ |
394 uint32_t product_code; /**< Slave product code. */ |
364 uint16_t index; /**< PDO entry index. */ |
395 uint16_t index; /**< PDO entry index. */ |
365 uint8_t subindex; /**< PDO entry subindex. */ |
396 uint8_t subindex; /**< PDO entry subindex. */ |
366 unsigned int *offset; /**< Pointer to a variable to store the PDO entry's |
397 unsigned int *offset; /**< Pointer to a variable to store the PDO entry's |
367 (byte-)offset in the process data. */ |
398 (byte-)offset in the process data. */ |
368 unsigned int *bit_position; /**< Pointer to a variable to store a bit |
399 unsigned int *bit_position; /**< Pointer to a variable to store a bit |
369 position (0-7) within the \a offset. Can be |
400 position (0-7) within the \a offset. Can be |
370 NULL, in which case an error is raised if the |
401 NULL, in which case an error is raised if the |
371 PDO entry does not byte-align. */ |
402 PDO entry does not byte-align. */ |
372 } ec_pdo_entry_reg_t; |
403 } ec_pdo_entry_reg_t; |
373 |
404 |
398 * \return Value of ECRT_VERSION_MAGIC() at EtherCAT master compile time. |
429 * \return Value of ECRT_VERSION_MAGIC() at EtherCAT master compile time. |
399 */ |
430 */ |
400 unsigned int ecrt_version_magic(void); |
431 unsigned int ecrt_version_magic(void); |
401 |
432 |
402 /** Requests an EtherCAT master for realtime operation. |
433 /** Requests an EtherCAT master for realtime operation. |
403 * |
434 * |
404 * Before an application can access an EtherCAT master, it has to reserve one |
435 * Before an application can access an EtherCAT master, it has to reserve one |
405 * for exclusive use. |
436 * for exclusive use. |
406 * |
437 * |
407 * In userspace, this is a convenience function for ecrt_open_master() and |
438 * In userspace, this is a convenience function for ecrt_open_master() and |
408 * ecrt_master_reserve(). |
439 * ecrt_master_reserve(). |
806 /** Sets the application time. |
837 /** Sets the application time. |
807 * |
838 * |
808 * The master has to know the application's time when operating slaves with |
839 * The master has to know the application's time when operating slaves with |
809 * distributed clocks. The time is not incremented by the master itself, so |
840 * distributed clocks. The time is not incremented by the master itself, so |
810 * this method has to be called cyclically. |
841 * this method has to be called cyclically. |
811 * |
842 * |
812 * The time is used when setting the slaves' <tt>System Time Offset</tt> and |
843 * The time is used when setting the slaves' <tt>System Time Offset</tt> and |
813 * <tt>Cyclic Operation Start Time</tt> registers and when synchronizing the |
844 * <tt>Cyclic Operation Start Time</tt> registers and when synchronizing the |
814 * DC reference clock to the application time via |
845 * DC reference clock to the application time via |
815 * ecrt_master_sync_reference_clock(). |
846 * ecrt_master_sync_reference_clock(). |
816 * |
847 * |
817 * The time is defined as nanoseconds from 2000-01-01 00:00. Converting an |
848 * The time is defined as nanoseconds from 2000-01-01 00:00. Converting an |
818 * epoch time can be done with the EC_TIMEVAL2NANO() macro. |
849 * epoch time can be done with the EC_TIMEVAL2NANO() macro. |
819 */ |
850 */ |
820 void ecrt_master_application_time( |
851 void ecrt_master_application_time( |
821 ec_master_t *master, /**< EtherCAT master. */ |
852 ec_master_t *master, /**< EtherCAT master. */ |
920 /** Clear a sync manager's PDO assignment. |
951 /** Clear a sync manager's PDO assignment. |
921 * |
952 * |
922 * This can be called before assigning PDOs via |
953 * This can be called before assigning PDOs via |
923 * ecrt_slave_config_pdo_assign_add(), to clear the default assignment of a |
954 * ecrt_slave_config_pdo_assign_add(), to clear the default assignment of a |
924 * sync manager. |
955 * sync manager. |
925 * |
956 * |
926 * \see ecrt_slave_config_pdos() |
957 * \see ecrt_slave_config_pdos() |
927 */ |
958 */ |
928 void ecrt_slave_config_pdo_assign_clear( |
959 void ecrt_slave_config_pdo_assign_clear( |
929 ec_slave_config_t *sc, /**< Slave configuration. */ |
960 ec_slave_config_t *sc, /**< Slave configuration. */ |
930 uint8_t sync_index /**< Sync manager index. Must be less |
961 uint8_t sync_index /**< Sync manager index. Must be less |
974 * \code |
1005 * \code |
975 * ec_pdo_entry_info_t el3162_channel1[] = { |
1006 * ec_pdo_entry_info_t el3162_channel1[] = { |
976 * {0x3101, 1, 8}, // status |
1007 * {0x3101, 1, 8}, // status |
977 * {0x3101, 2, 16} // value |
1008 * {0x3101, 2, 16} // value |
978 * }; |
1009 * }; |
979 * |
1010 * |
980 * ec_pdo_entry_info_t el3162_channel2[] = { |
1011 * ec_pdo_entry_info_t el3162_channel2[] = { |
981 * {0x3102, 1, 8}, // status |
1012 * {0x3102, 1, 8}, // status |
982 * {0x3102, 2, 16} // value |
1013 * {0x3102, 2, 16} // value |
983 * }; |
1014 * }; |
984 * |
1015 * |
985 * ec_pdo_info_t el3162_pdos[] = { |
1016 * ec_pdo_info_t el3162_pdos[] = { |
986 * {0x1A00, 2, el3162_channel1}, |
1017 * {0x1A00, 2, el3162_channel1}, |
987 * {0x1A01, 2, el3162_channel2} |
1018 * {0x1A01, 2, el3162_channel2} |
988 * }; |
1019 * }; |
989 * |
1020 * |
990 * ec_sync_info_t el3162_syncs[] = { |
1021 * ec_sync_info_t el3162_syncs[] = { |
991 * {2, EC_DIR_OUTPUT}, |
1022 * {2, EC_DIR_OUTPUT}, |
992 * {3, EC_DIR_INPUT, 2, el3162_pdos}, |
1023 * {3, EC_DIR_INPUT, 2, el3162_pdos}, |
993 * {0xff} |
1024 * {0xff} |
994 * }; |
1025 * }; |
995 * |
1026 * |
996 * if (ecrt_slave_config_pdos(sc_ana_in, EC_END, el3162_syncs)) { |
1027 * if (ecrt_slave_config_pdos(sc_ana_in, EC_END, el3162_syncs)) { |
997 * // handle error |
1028 * // handle error |
998 * } |
1029 * } |
999 * \endcode |
1030 * \endcode |
1000 * |
1031 * |
1001 * The next example shows, how to configure the PDO assignment only. The |
1032 * The next example shows, how to configure the PDO assignment only. The |
1002 * entries for each assigned PDO are taken from the PDO's default mapping. |
1033 * entries for each assigned PDO are taken from the PDO's default mapping. |
1003 * Please note, that PDO entry registration will fail, if the PDO |
1034 * Please note, that PDO entry registration will fail, if the PDO |
1004 * configuration is left empty and the slave is offline. |
1035 * configuration is left empty and the slave is offline. |
1005 * |
1036 * |
1006 * \code |
1037 * \code |
1007 * ec_pdo_info_t pdos[] = { |
1038 * ec_pdo_info_t pdos[] = { |
1008 * {0x1600}, // Channel 1 |
1039 * {0x1600}, // Channel 1 |
1009 * {0x1601} // Channel 2 |
1040 * {0x1601} // Channel 2 |
1010 * }; |
1041 * }; |
1011 * |
1042 * |
1012 * ec_sync_info_t syncs[] = { |
1043 * ec_sync_info_t syncs[] = { |
1013 * {3, EC_DIR_INPUT, 2, pdos}, |
1044 * {3, EC_DIR_INPUT, 2, pdos}, |
1014 * }; |
1045 * }; |
1015 * |
1046 * |
1016 * if (ecrt_slave_config_pdos(slave_config_ana_in, 1, syncs)) { |
1047 * if (ecrt_slave_config_pdos(slave_config_ana_in, 1, syncs)) { |
1017 * // handle error |
1048 * // handle error |
1018 * } |
1049 * } |
1019 * \endcode |
1050 * \endcode |
1020 * |
1051 * |
1052 int ecrt_slave_config_reg_pdo_entry( |
1083 int ecrt_slave_config_reg_pdo_entry( |
1053 ec_slave_config_t *sc, /**< Slave configuration. */ |
1084 ec_slave_config_t *sc, /**< Slave configuration. */ |
1054 uint16_t entry_index, /**< Index of the PDO entry to register. */ |
1085 uint16_t entry_index, /**< Index of the PDO entry to register. */ |
1055 uint8_t entry_subindex, /**< Subindex of the PDO entry to register. */ |
1086 uint8_t entry_subindex, /**< Subindex of the PDO entry to register. */ |
1056 ec_domain_t *domain, /**< Domain. */ |
1087 ec_domain_t *domain, /**< Domain. */ |
1057 unsigned int *bit_position /**< Optional address if bit addressing |
1088 unsigned int *bit_position /**< Optional address if bit addressing |
1058 is desired */ |
1089 is desired */ |
1059 ); |
1090 ); |
1060 |
1091 |
1061 /** Configure distributed clocks. |
1092 /** Configure distributed clocks. |
1062 * |
1093 * |