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(), |
220 * \see ecrt_master(). |
223 * \see ecrt_master(). |
221 */ |
224 */ |
222 typedef struct { |
225 typedef struct { |
223 unsigned int slave_count; /**< Number of slaves in the bus. */ |
226 unsigned int slave_count; /**< Number of slaves in the bus. */ |
224 unsigned int link_up : 1; /**< \a true, if the network link is up. */ |
227 unsigned int link_up : 1; /**< \a true, if the network link is up. */ |
225 uint8_t scan_busy; /**< \a true, while the master is scanning the bus */ |
228 uint8_t scan_busy; /**< \a true, while the master is scanning the bus */ |
226 uint64_t app_time; /**< Application time. */ |
229 uint64_t app_time; /**< Application time. */ |
227 } ec_master_info_t; |
230 } ec_master_info_t; |
|
231 |
|
232 /*****************************************************************************/ |
|
233 |
|
234 /** EtherCAT slave port descriptor. |
|
235 */ |
|
236 typedef enum { |
|
237 EC_PORT_NOT_IMPLEMENTED, /**< Port is not implemented. */ |
|
238 EC_PORT_NOT_CONFIGURED, /**< Port is not configured. */ |
|
239 EC_PORT_EBUS, /**< Port is an e-bus. */ |
|
240 EC_PORT_MII /**< Port is a mii. */ |
|
241 } ec_slave_port_desc_t; |
|
242 |
|
243 /*****************************************************************************/ |
|
244 |
|
245 /** EtherCAT slave port information. |
|
246 */ |
|
247 typedef struct { |
|
248 uint8_t link_up; /**< Link detected. */ |
|
249 uint8_t loop_closed; /**< Loop closed. */ |
|
250 uint8_t signal_detected; /**< Detected signal on RX port. */ |
|
251 } ec_slave_port_link_t; |
228 |
252 |
229 /*****************************************************************************/ |
253 /*****************************************************************************/ |
230 |
254 |
231 /** Slave information. |
255 /** Slave information. |
232 * |
256 * |
240 uint32_t product_code; /**< Product-Code stored on the slave. */ |
264 uint32_t product_code; /**< Product-Code stored on the slave. */ |
241 uint32_t revision_number; /**< Revision-Number stored on the slave. */ |
265 uint32_t revision_number; /**< Revision-Number stored on the slave. */ |
242 uint32_t serial_number; /**< Serial-Number stored on the slave. */ |
266 uint32_t serial_number; /**< Serial-Number stored on the slave. */ |
243 uint16_t alias; /**< The slaves alias if not equal to 0. */ |
267 uint16_t alias; /**< The slaves alias if not equal to 0. */ |
244 int16_t current_on_ebus; /**< Used current in mA. */ |
268 int16_t current_on_ebus; /**< Used current in mA. */ |
|
269 struct { |
|
270 ec_slave_port_desc_t desc; |
|
271 ec_slave_port_link_t link; |
|
272 uint32_t receive_time; |
|
273 uint16_t next_slave; |
|
274 uint32_t delay_to_next_dc; |
|
275 } ports[EC_MAX_PORTS]; |
245 uint8_t al_state; /**< Current state of the slave. */ |
276 uint8_t al_state; /**< Current state of the slave. */ |
246 uint8_t error_flag; /**< Error flag for that slave. */ |
277 uint8_t error_flag; /**< Error flag for that slave. */ |
247 uint8_t sync_count; /**< Number of sync managers. */ |
278 uint8_t sync_count; /**< Number of sync managers. */ |
248 uint16_t sdo_count; /**< Number of SDOs. */ |
279 uint16_t sdo_count; /**< Number of SDOs. */ |
249 char name[EC_MAX_STRING_LENGTH]; /**< Name of the slave. */ |
280 char name[EC_MAX_STRING_LENGTH]; /**< Name of the slave. */ |
311 } ec_pdo_entry_info_t; |
342 } ec_pdo_entry_info_t; |
312 |
343 |
313 /*****************************************************************************/ |
344 /*****************************************************************************/ |
314 |
345 |
315 /** PDO configuration information. |
346 /** PDO configuration information. |
316 * |
347 * |
317 * This is the data type of the \a pdos field in ec_sync_info_t. |
348 * This is the data type of the \a pdos field in ec_sync_info_t. |
318 * |
349 * |
319 * \see ecrt_slave_config_pdos(). |
350 * \see ecrt_slave_config_pdos(). |
320 */ |
351 */ |
321 typedef struct { |
352 typedef struct { |
322 uint16_t index; /**< PDO index. */ |
353 uint16_t index; /**< PDO index. */ |
323 unsigned int n_entries; /**< Number of PDO entries in \a entries to map. |
354 unsigned int n_entries; /**< Number of PDO entries in \a entries to map. |
362 uint32_t product_code; /**< Slave product code. */ |
393 uint32_t product_code; /**< Slave product code. */ |
363 uint16_t index; /**< PDO entry index. */ |
394 uint16_t index; /**< PDO entry index. */ |
364 uint8_t subindex; /**< PDO entry subindex. */ |
395 uint8_t subindex; /**< PDO entry subindex. */ |
365 unsigned int *offset; /**< Pointer to a variable to store the PDO entry's |
396 unsigned int *offset; /**< Pointer to a variable to store the PDO entry's |
366 (byte-)offset in the process data. */ |
397 (byte-)offset in the process data. */ |
367 unsigned int *bit_position; /**< Pointer to a variable to store a bit |
398 unsigned int *bit_position; /**< Pointer to a variable to store a bit |
368 position (0-7) within the \a offset. Can be |
399 position (0-7) within the \a offset. Can be |
369 NULL, in which case an error is raised if the |
400 NULL, in which case an error is raised if the |
370 PDO entry does not byte-align. */ |
401 PDO entry does not byte-align. */ |
371 } ec_pdo_entry_reg_t; |
402 } ec_pdo_entry_reg_t; |
372 |
403 |
408 * \return Value of ECRT_VERSION_MAGIC() at EtherCAT master compile time. |
439 * \return Value of ECRT_VERSION_MAGIC() at EtherCAT master compile time. |
409 */ |
440 */ |
410 unsigned int ecrt_version_magic(void); |
441 unsigned int ecrt_version_magic(void); |
411 |
442 |
412 /** Requests an EtherCAT master for realtime operation. |
443 /** Requests an EtherCAT master for realtime operation. |
413 * |
444 * |
414 * Before an application can access an EtherCAT master, it has to reserve one |
445 * Before an application can access an EtherCAT master, it has to reserve one |
415 * for exclusive use. |
446 * for exclusive use. |
416 * |
447 * |
417 * In userspace, this is a convenience function for ecrt_open_master() and |
448 * In userspace, this is a convenience function for ecrt_open_master() and |
418 * ecrt_master_reserve(). |
449 * ecrt_master_reserve(). |
824 /** Sets the application time. |
855 /** Sets the application time. |
825 * |
856 * |
826 * The master has to know the application's time when operating slaves with |
857 * The master has to know the application's time when operating slaves with |
827 * distributed clocks. The time is not incremented by the master itself, so |
858 * distributed clocks. The time is not incremented by the master itself, so |
828 * this method has to be called cyclically. |
859 * this method has to be called cyclically. |
829 * |
860 * |
830 * The time is used when setting the slaves' <tt>System Time Offset</tt> and |
861 * The time is used when setting the slaves' <tt>System Time Offset</tt> and |
831 * <tt>Cyclic Operation Start Time</tt> registers and when synchronizing the |
862 * <tt>Cyclic Operation Start Time</tt> registers and when synchronizing the |
832 * DC reference clock to the application time via |
863 * DC reference clock to the application time via |
833 * ecrt_master_sync_reference_clock(). |
864 * ecrt_master_sync_reference_clock(). |
834 * |
865 * |
835 * The time is defined as nanoseconds from 2000-01-01 00:00. Converting an |
866 * The time is defined as nanoseconds from 2000-01-01 00:00. Converting an |
836 * epoch time can be done with the EC_TIMEVAL2NANO() macro. |
867 * epoch time can be done with the EC_TIMEVAL2NANO() macro. |
837 */ |
868 */ |
838 void ecrt_master_application_time( |
869 void ecrt_master_application_time( |
839 ec_master_t *master, /**< EtherCAT master. */ |
870 ec_master_t *master, /**< EtherCAT master. */ |
938 /** Clear a sync manager's PDO assignment. |
969 /** Clear a sync manager's PDO assignment. |
939 * |
970 * |
940 * This can be called before assigning PDOs via |
971 * This can be called before assigning PDOs via |
941 * ecrt_slave_config_pdo_assign_add(), to clear the default assignment of a |
972 * ecrt_slave_config_pdo_assign_add(), to clear the default assignment of a |
942 * sync manager. |
973 * sync manager. |
943 * |
974 * |
944 * \see ecrt_slave_config_pdos() |
975 * \see ecrt_slave_config_pdos() |
945 */ |
976 */ |
946 void ecrt_slave_config_pdo_assign_clear( |
977 void ecrt_slave_config_pdo_assign_clear( |
947 ec_slave_config_t *sc, /**< Slave configuration. */ |
978 ec_slave_config_t *sc, /**< Slave configuration. */ |
948 uint8_t sync_index /**< Sync manager index. Must be less |
979 uint8_t sync_index /**< Sync manager index. Must be less |
992 * \code |
1023 * \code |
993 * ec_pdo_entry_info_t el3162_channel1[] = { |
1024 * ec_pdo_entry_info_t el3162_channel1[] = { |
994 * {0x3101, 1, 8}, // status |
1025 * {0x3101, 1, 8}, // status |
995 * {0x3101, 2, 16} // value |
1026 * {0x3101, 2, 16} // value |
996 * }; |
1027 * }; |
997 * |
1028 * |
998 * ec_pdo_entry_info_t el3162_channel2[] = { |
1029 * ec_pdo_entry_info_t el3162_channel2[] = { |
999 * {0x3102, 1, 8}, // status |
1030 * {0x3102, 1, 8}, // status |
1000 * {0x3102, 2, 16} // value |
1031 * {0x3102, 2, 16} // value |
1001 * }; |
1032 * }; |
1002 * |
1033 * |
1003 * ec_pdo_info_t el3162_pdos[] = { |
1034 * ec_pdo_info_t el3162_pdos[] = { |
1004 * {0x1A00, 2, el3162_channel1}, |
1035 * {0x1A00, 2, el3162_channel1}, |
1005 * {0x1A01, 2, el3162_channel2} |
1036 * {0x1A01, 2, el3162_channel2} |
1006 * }; |
1037 * }; |
1007 * |
1038 * |
1008 * ec_sync_info_t el3162_syncs[] = { |
1039 * ec_sync_info_t el3162_syncs[] = { |
1009 * {2, EC_DIR_OUTPUT}, |
1040 * {2, EC_DIR_OUTPUT}, |
1010 * {3, EC_DIR_INPUT, 2, el3162_pdos}, |
1041 * {3, EC_DIR_INPUT, 2, el3162_pdos}, |
1011 * {0xff} |
1042 * {0xff} |
1012 * }; |
1043 * }; |
1013 * |
1044 * |
1014 * if (ecrt_slave_config_pdos(sc_ana_in, EC_END, el3162_syncs)) { |
1045 * if (ecrt_slave_config_pdos(sc_ana_in, EC_END, el3162_syncs)) { |
1015 * // handle error |
1046 * // handle error |
1016 * } |
1047 * } |
1017 * \endcode |
1048 * \endcode |
1018 * |
1049 * |
1019 * The next example shows, how to configure the PDO assignment only. The |
1050 * The next example shows, how to configure the PDO assignment only. The |
1020 * entries for each assigned PDO are taken from the PDO's default mapping. |
1051 * entries for each assigned PDO are taken from the PDO's default mapping. |
1021 * Please note, that PDO entry registration will fail, if the PDO |
1052 * Please note, that PDO entry registration will fail, if the PDO |
1022 * configuration is left empty and the slave is offline. |
1053 * configuration is left empty and the slave is offline. |
1023 * |
1054 * |
1024 * \code |
1055 * \code |
1025 * ec_pdo_info_t pdos[] = { |
1056 * ec_pdo_info_t pdos[] = { |
1026 * {0x1600}, // Channel 1 |
1057 * {0x1600}, // Channel 1 |
1027 * {0x1601} // Channel 2 |
1058 * {0x1601} // Channel 2 |
1028 * }; |
1059 * }; |
1029 * |
1060 * |
1030 * ec_sync_info_t syncs[] = { |
1061 * ec_sync_info_t syncs[] = { |
1031 * {3, EC_DIR_INPUT, 2, pdos}, |
1062 * {3, EC_DIR_INPUT, 2, pdos}, |
1032 * }; |
1063 * }; |
1033 * |
1064 * |
1034 * if (ecrt_slave_config_pdos(slave_config_ana_in, 1, syncs)) { |
1065 * if (ecrt_slave_config_pdos(slave_config_ana_in, 1, syncs)) { |
1035 * // handle error |
1066 * // handle error |
1036 * } |
1067 * } |
1037 * \endcode |
1068 * \endcode |
1038 * |
1069 * |
1070 int ecrt_slave_config_reg_pdo_entry( |
1101 int ecrt_slave_config_reg_pdo_entry( |
1071 ec_slave_config_t *sc, /**< Slave configuration. */ |
1102 ec_slave_config_t *sc, /**< Slave configuration. */ |
1072 uint16_t entry_index, /**< Index of the PDO entry to register. */ |
1103 uint16_t entry_index, /**< Index of the PDO entry to register. */ |
1073 uint8_t entry_subindex, /**< Subindex of the PDO entry to register. */ |
1104 uint8_t entry_subindex, /**< Subindex of the PDO entry to register. */ |
1074 ec_domain_t *domain, /**< Domain. */ |
1105 ec_domain_t *domain, /**< Domain. */ |
1075 unsigned int *bit_position /**< Optional address if bit addressing |
1106 unsigned int *bit_position /**< Optional address if bit addressing |
1076 is desired */ |
1107 is desired */ |
1077 ); |
1108 ); |
1078 |
1109 |
1079 /** Configure distributed clocks. |
1110 /** Configure distributed clocks. |
1080 * |
1111 * |