Creating Instruction Help
Custom instruction help is generated automatically as you are creating your Add-On Instructions. The Logix Designer application automatically builds help for your Add-On Instructions by using the instruction’s description, revision note, and parameter descriptions. By creating meaningful descriptions, you can help the users of your instruction.
In addition, you can add your own custom text to the help by using the extended description field. You can provide additional help documentation by entering it on the Help tab of the Add-On Instruction Definition Editor. The instruction help is available in the instruction browser and from any call to the instruction in a language editor by pressing F1.
Writing Clear Descriptions
When writing your descriptions keep the following in mind:
· Use short sentences and simple language.
· Be brief and direct when you write.
· Include simple examples.
· Proofread your entries.
This is an example of the Extended Description Text field in the Help tab of the Add-On Instruction Definition Editor. This area lets you create directions on how to use and troubleshoot your instruction. The Instruction Help Preview window shows how your text will look as generated instruction help.
Documenting an Add-On Instruction
Follow these steps to create custom help for an instruction.
1. Right-click an Add-On Instruction and choose Open Definition.
2. On the General tab, enter a description and a revision note for the Add-On Instruction to explain the purpose of the instruction.
3. Click the Parameters tab and enter a meaningful description for each Parameter.
4. Right-click each routine located below the Add-On Instruction in the Controller Organizer and choose Properties.
5. Enter a description for execution of each routine.
a. For the logic routine, describe execution of the instruction when EnableIn is true.
b. For the EnableInFalse routine (if one exists), describe actions that will take place when EnableIn is false, such as any outputs that get cleared.
c. For the Prescan routine (if one exists), briefly describe actions that will take place during the Prescan routine, such as initialization of any parameters.
d. For the Postscan routine (if one exists), briefly describe actions that will take place during the Postscan routine, such as initialization of any parameters resetting any internal state of the instruction.
6. Click the Help tab of the Add-On Instruction Definition Editor and enter additional information in the Extended Description field.
The extended description can include the following information:
· Additional parameter information
· Description of how the instruction executes
· Change history notes
7. Review the Help format in the preview window
This is an example of the Logix Designer application generated help for the instruction. This information is gathered from the definition descriptions that you complete when defining an instruction.
Project Documentation
With RSLogix 5000 software, version 17 and later, you have the option to display project documentation, such as tag descriptions and rung comments in any supported localized language. You can store project documentation for multiple languages in a single project file rather than in language-specific project files. You define all the localized languages that the project will support and set the current, default, and optional custom localized language. The software uses the default language if the current language's content is blank for a particular component of the project. However, you can use a custom language to tailor documentation to a specific type of project file user.
Enter the localized descriptions in your project, either when programming in that language or by using the import/export utility to translate the documentation offline and then import it back into the project. Once you enable project documentation in application, you can dynamically switch between languages as you use the software.
Project documentation that supports multiple translations includes these variables:
• Component descriptions in tags, routines, programs, equipment phases, user-defined data types, and Add-On Instructions
• Engineering units and state identifiers added to tags, user-defined data types, or Add-On Instructions
• Trends
• Controllers
• Alarm Messages (in configuration of ALARM_ANALOG and ALARM_DIGITAL tags)
• Tasks
• Property descriptions for module in the Controller Organizer
• Rung comments, SFC text boxes, and FBD text boxes
If you want to allow project documentation on an Add-On Instruction that is sealed with an instruction signature, you must enter the localized documentation into your Add-On Instruction before generating the signature. Because the signature history is created after the instruction signature is generated, the signature history is not translatable. If the translated information already exists when you generate the Add-On Instruction signature, you can switch the language while keeping the signature intact because the switch does not alter the instruction definition, it only changes the language that is displayed.
For more information on enabling a project to support multiple translations of project documentation, refer to the online help.
In addition, you can add your own custom text to the help by using the extended description field. You can provide additional help documentation by entering it on the Help tab of the Add-On Instruction Definition Editor. The instruction help is available in the instruction browser and from any call to the instruction in a language editor by pressing F1.
Writing Clear Descriptions
When writing your descriptions keep the following in mind:
· Use short sentences and simple language.
· Be brief and direct when you write.
· Include simple examples.
· Proofread your entries.
This is an example of the Extended Description Text field in the Help tab of the Add-On Instruction Definition Editor. This area lets you create directions on how to use and troubleshoot your instruction. The Instruction Help Preview window shows how your text will look as generated instruction help.
Documenting an Add-On Instruction
Follow these steps to create custom help for an instruction.
1. Right-click an Add-On Instruction and choose Open Definition.
2. On the General tab, enter a description and a revision note for the Add-On Instruction to explain the purpose of the instruction.
3. Click the Parameters tab and enter a meaningful description for each Parameter.
4. Right-click each routine located below the Add-On Instruction in the Controller Organizer and choose Properties.
5. Enter a description for execution of each routine.
a. For the logic routine, describe execution of the instruction when EnableIn is true.
b. For the EnableInFalse routine (if one exists), describe actions that will take place when EnableIn is false, such as any outputs that get cleared.
c. For the Prescan routine (if one exists), briefly describe actions that will take place during the Prescan routine, such as initialization of any parameters.
d. For the Postscan routine (if one exists), briefly describe actions that will take place during the Postscan routine, such as initialization of any parameters resetting any internal state of the instruction.
6. Click the Help tab of the Add-On Instruction Definition Editor and enter additional information in the Extended Description field.
The extended description can include the following information:
· Additional parameter information
· Description of how the instruction executes
· Change history notes
7. Review the Help format in the preview window
This is an example of the Logix Designer application generated help for the instruction. This information is gathered from the definition descriptions that you complete when defining an instruction.
Project Documentation
With RSLogix 5000 software, version 17 and later, you have the option to display project documentation, such as tag descriptions and rung comments in any supported localized language. You can store project documentation for multiple languages in a single project file rather than in language-specific project files. You define all the localized languages that the project will support and set the current, default, and optional custom localized language. The software uses the default language if the current language's content is blank for a particular component of the project. However, you can use a custom language to tailor documentation to a specific type of project file user.
Enter the localized descriptions in your project, either when programming in that language or by using the import/export utility to translate the documentation offline and then import it back into the project. Once you enable project documentation in application, you can dynamically switch between languages as you use the software.
Project documentation that supports multiple translations includes these variables:
• Component descriptions in tags, routines, programs, equipment phases, user-defined data types, and Add-On Instructions
• Engineering units and state identifiers added to tags, user-defined data types, or Add-On Instructions
• Trends
• Controllers
• Alarm Messages (in configuration of ALARM_ANALOG and ALARM_DIGITAL tags)
• Tasks
• Property descriptions for module in the Controller Organizer
• Rung comments, SFC text boxes, and FBD text boxes
If you want to allow project documentation on an Add-On Instruction that is sealed with an instruction signature, you must enter the localized documentation into your Add-On Instruction before generating the signature. Because the signature history is created after the instruction signature is generated, the signature history is not translatable. If the translated information already exists when you generate the Add-On Instruction signature, you can switch the language while keeping the signature intact because the switch does not alter the instruction definition, it only changes the language that is displayed.
For more information on enabling a project to support multiple translations of project documentation, refer to the online help.
0 comments :