## page was copied from smach/Tutorials/Wrapping a SMACH Container With actionlib
## For instruction on writing tutorials
## http://www.ros.org/wiki/WritingTutorials
####################################
##FILL ME IN
####################################
## for a custom note with links:
## note =
## for the canned note of "This tutorial assumes that you have completed the previous tutorials:" just add the links 
## note.0= 
## descriptive title for the tutorial
## title = Wrapping a Container With actionlib
## multi-line description to be displayed in search 
## description = This tutorial explains how to serve out a SMACH plan as an action over [[actionlib]].
## the next tutorial description (optional)
## next =
## links to next tutorial (optional)
## next.0.link=
## next.1.link=
## what level user is this tutorial for 
## level= IntermediateCategory
## keywords =
####################################

<<IncludeCSTemplate(TutorialCSHeaderTemplate)>>

<<TableOfContents(4)>>

=== Wrapping a SMACH State ===

SMACH provides the top-level container called !ActionServerWrapper. This class advertises an [[actionlib]] action server. Instead of being executed by a parent, it's contained state goes active when the action server receives a goal. Accordingly, this container does not inherit from the smach.State base class and cannot be put inside of another container.

The action server wrapper can inject the goal message received by the action server into the contained state, as well as extract the result message from that state when it terminates. When constructing the action server wrapper, the user specifies which state machine outcomes correspond to a succeeded, aborted, or preempted result.

Consider this example, which wraps a SMACH state machine as an action:

{{{#!python
import rospy

from smach import StateMachine
from smach_ros import ActionServerWrapper

# Construct state machine
sm = StateMachine(outcomes=['did_something',
                            'did_something_else',
                            'aborted',
                            'preempted'])
with sm:
    ### Add states in here...

# Construct action server wrapper
asw = ActionServerWrapper(
    'my_action_server_name', MyAction,
    wrapped_container = sm,
    succeeded_outcomes = ['did_something','did_something_else'],
    aborted_outcomes = ['aborted'],
    preempted_outcomes = ['preempted'] )

# Run the server in a background thread
asw.run_server()

# Wait for control-c
rospy.spin()
}}}

=== Getting The Goal/Result Messages Into/Out Of The Contained State ===

The above code will call sm.execute(), but it will not load the goal into the contained state machine, nor will it extract a result. In order to do these things, you need to tell the action server wrapper what it should call the goal and result messages in the context of SMACH. You can replace the action server wrapper construction call with the following:

{{{#!python start_line=9
# Construct action server wrapper
asw = ActionServerWrapper(
    'my_action_server_name', MyAction, sm,
    ['did_something','did_something_else'], ['aborted'], ['preempted'],
    goal_key = 'my_awesome_goal',
    result_key = 'egad_its_a_result' )
}}}

The keyword arguments ''goal_key'' and ''result_key'' are the SMACH userdata keys in the context of the ActionServerWrapper. Like any other container, this means that the wrapper's contained state (in this case the state machine ''sm'') will receive a reference to this userdata structure when its execute() method is called. Similarly to how userdata is passed between scopes in nested state machines, in this case, you need to set these key identifiers in the state machine ''sm'' as well.

In order to copy in the keys form the parent, you can replace the construction call for the state machine ''sm'' with this: 

{{{#!python
# Construct state machine
sm = StateMachine(
        outcomes=['did_something','did_something_else','aborted','preempted'],
        input_keys = ['my_awesome_goal'],
        output_keys = ['egad_its_a_result'])
}}}

Once you have done this, you can access these keys from any state added to ''sm''. For more goal/result policies, see the [[http://www.ros.org/doc/api/smach/html/python/smach.action_server_wrapper.ActionServerWrapper-class.html#__init__|ActionServerWrapper API documentation]].

## AUTOGENERATED DO NOT DELETE 
## TutorialCategory
## FILL IN THE STACK TUTORIAL CATEGORY HERE
## SMACHContainerCategory