# 使用指南

## 目录

- [快速开始](#快速开始)
- [基础类型创建](#基础类型创建)
- [应用数据类型](#应用数据类型)
- [接口定义](#接口定义)
- [软件组件](#软件组件)
- [内部行为](#内部行为)
- [打包与导出](#打包与导出)
- [完整示例](#完整示例)

---

## 快速开始

### 环境要求

- Python 3.8+

### 安装

将 `src` 目录添加到 Python 路径即可使用：

```python
import sys
sys.path.insert(0, '/path/to/arxml_sdk/src')
```

或直接使用相对导入：

```python
from src import create_arxml_document, write_arxml
```

### 最小示例

```python
from src import (
    create_arxml_document, write_arxml, create_package,
    create_base_type, Category, Encoding
)

doc = create_arxml_document()
base_type = create_base_type("UInt8", size=8, encoding=Encoding.TWO_COMPONENT)
package = create_package("MyPackage", elements=[base_type])
package_element = package.to_arxml(doc)
doc.documentElement.appendChild(package_element)
write_arxml(doc, "minimal.arxml")
```

---

## 基础类型创建

### 创建基本整数类型

```python
from src import create_base_type, Category, Encoding

uint8 = create_base_type("UInt8", size=8, encoding=Encoding.TWO_COMPONENT)
uint16 = create_base_type("UInt16", size=16, encoding=Encoding.TWO_COMPONENT)
sint8 = create_base_type("Sint8", size=8, encoding=Encoding.TWO_COMPONENT)
float32 = create_base_type("Float32", size=32, encoding=Encoding.IEEE754)
```

### 创建带文本表的类型

```python
from src import (
    create_base_type, create_unit, create_data_constraint,
    create_linear, create_text_table, create_compu_method,
    Category, LowerSts, UpperSts
)

unit = create_unit("km/h", display="km/h", factor=1.0, offset=0.0)

constraint = create_data_constraint(
    "SpeedConstraint",
    lower=0, upper=250,
    lower_sts=LowerSts.CLOSED,
    upper_sts=UpperSts.OPEN
)

linear = create_linear(factor=0.01, offset=0)

compu = create_compu_method(
    "SpeedConversion",
    unit=unit,
    linear=linear,
    category=Category.LINEAR
)

value_type = create_value_type(
    "Speed",
    unit=unit,
    compu_method=compu,
    data_constraint=constraint
)
```

---

## 应用数据类型

### 布尔类型

```python
from src import create_boolean_type, create_compu_method, create_linear, Category

bool_compu = create_compu_method(
    "BoolConversion",
    linear=create_linear(factor=1, offset=0),
    category=Category.BOOLEAN
)

bool_type = create_boolean_type("ErrorFlag", compu_method=bool_compu)
```

### 值类型

```python
from src import create_value_type, create_unit, create_linear, create_compu_method, Category

unit = create_unit("deg", display="°C")
linear = create_linear(factor=0.1, offset=-40)
compu = create_compu_method("Temperature", unit=unit, linear=linear, category=Category.LINEAR)

temp_type = create_value_type("Temperature", unit=unit, compu_method=compu)
```

### 结构体类型

```python
from src import (
    ApplicationStructureDataType, create_value_type,
    create_unit, create_linear, create_compu_method
)

unit = create_unit("V")
linear = create_linear(factor=0.001, offset=0)
compu = create_compu_method("Voltage", unit=unit, linear=linear, category=Category.LINEAR)
voltage_type = create_value_type("Voltage", unit=unit, compu_method=compu)

current_type = create_value_type("Current", unit=unit, compu_method=compu)

structure = ApplicationStructureDataType(name="PowerData")
structure.add_element(
    ApplicationStructureDataType.StructureElement(name="voltage", data_type=voltage_type, offset=0)
)
structure.add_element(
    ApplicationStructureDataType.StructureElement(name="current", data_type=current_type, offset=32)
)
```

### 数组类型

```python
from src import ApplicationArrayDataType, create_value_type, create_unit, Semantic

element_type = create_value_type("SensorValue", unit=create_unit("counts"))

array_type = ApplicationArrayDataType(name="SensorData")
array_type.element = ApplicationArrayDataType.ArrayElement(
    length=10,
    data_type=element_type,
    array_size_semantics=Semantic.FIXED
)
```

---

## 实现数据类型

### 值类型

```python
from src import create_impl_value_type, create_base_type, create_value_type, Encoding

base_type = create_base_type("UInt16", size=16, encoding=Encoding.TWO_COMPONENT)
app_type = create_value_type("AppCounter")

impl_type = create_impl_value_type("ImplCounter", base_type=base_type)
```

### 结构体类型

```python
from src import ImplementationStructureDataType, create_impl_value_type, create_base_type, Encoding

base_u8 = create_base_type("UInt8", size=8, encoding=Encoding.TWO_COMPONENT)
base_u16 = create_base_type("UInt16", size=16, encoding=Encoding.TWO_COMPONENT)

impl_u8 = create_impl_value_type("ImplUInt8", base_type=base_u8)
impl_u16 = create_impl_value_type("ImplUInt16", base_type=base_u16)

struct_type = ImplementationStructureDataType(name="ImplStatus")
struct_type.add_element(
    ImplementationStructureDataType.StructureElement(name="status", data_type=impl_u8, offset=0)
)
struct_type.add_element(
    ImplementationStructureDataType.StructureElement(name="value", data_type=impl_u16, offset=8)
)
```

### 数组类型

```python
from src import ImplementationArrayDataType, create_impl_value_type, create_base_type, Semantic, Encoding

base = create_base_type("UInt32", size=32, encoding=Encoding.TWO_COMPONENT)
element_type = create_impl_value_type("ImplUInt32", base_type=base)

impl_array = ImplementationArrayDataType(name="ImplBuffer")
impl_array.element = ImplementationArrayDataType.ArrayElement(
    length=16,
    data_type=element_type,
    array_size_semantics=Semantic.FIXED
)
```

---

## 数据类型映射

```python
from src import (
    DataTypeMapping, DataTypeMappingSet,
    create_value_type, create_impl_value_type, create_base_type, Encoding
)

base = create_base_type("UInt8", size=8, encoding=Encoding.TWO_COMPONENT)
app_type = create_value_type("AppStatus")
impl_type = create_impl_value_type("ImplStatus", base_type=base)

mapping = DataTypeMapping(
    name="StatusMapping",
    application_data_type=app_type,
    implementation_data_type=impl_type
)

mapping_set = DataTypeMappingSet(name="DefaultMappings")
mapping_set.add_mapping(mapping)
```

---

## 接口定义

### 发送-接收接口

```python
from src import (
    SenderReceiverInterface, create_sender_receiver_interface,
    create_value_type, create_unit, Policy, CalibrationAccess
)

unit = create_unit("km/h")
data_element = SenderReceiverInterface.DataElement(
    name="Speed",
    data_type=create_value_type("Speed", unit=unit),
    policy=Policy.STANDARD,
    calibration_access=CalibrationAccess.READ_ONLY
)

interface = create_sender_receiver_interface("SpeedInterface", data_element=data_element)
```

### 客户端-服务端接口

```python
from src import (
    ClientServerInterface, create_value_type, create_unit,
    PortDirection
)

unit = create_unit("counts")

operation = ClientServerInterface.Operation(
    name="Initialize",
    is_server=True,
    arguments=[
        ClientServerInterface.Argument(
            name="config",
            direction=PortDirection.IN,
            data_type=create_value_type("Config", unit=unit)
        )
    ]
)

cs_interface = ClientServerInterface(name="ControlInterface")
cs_interface.add_operation(operation)
```

---

## 软件组件

### 创建组件

```python
from src import (
    ApplicationSwComponentType, PPortPrototype, RPortPrototype,
    SenderReceiverInterface, create_sender_receiver_interface,
    AtomicType, ComponentType
)

interface = create_sender_receiver_interface("DataInterface")
port = PPortPrototype(name="DataPort", interface=interface)

component = ApplicationSwComponentType(
    name="SensorComponent",
    supports_multiple_instantiation=False,
    atomic_type=AtomicType.APPLICATION
)
component.add_port(port)
```

### 创建组合组件

```python
from src import SwComponentType, ComponentType, AtomicComponentType, CompositionSwComponentType

child1 = ApplicationSwComponentType(name="Child1")
child2 = ApplicationSwComponentType(name="Child2")

composition = CompositionSwComponentType(name="Composition")
composition._component_type = ComponentType.COMPOSITION
```

---

## 内部行为

### 创建 Runnable 和事件

```python
from src import (
    SwcInternalBehavior, RunnableEntity, TimingEvent, InitEvent,
    VariableAccess, create_swc_internal_behavior, create_runnable_entity,
    create_timing_event, create_init_event, create_data_received_event
)

runnable = create_runnable_entity(
    name="UpdateMeasurement",
    symbol="UpdateMeasurement",
    minimum_start_interval=0.01
)
runnable.add_variable_access(
    VariableAccess(name="SpeedAccess", port_prototype_ref="SpeedPort")
)

timing_event = create_timing_event(name="Timing_10ms", period=0.01)
init_event = InitEvent(name="Init", runnable_ref="UpdateMeasurement")

data_rx_event = create_data_received_event(
    name="DataReady",
    data_element_ref="ReadyFlag",
    period=0.05
)

behavior = create_swc_internal_behavior(
    name="SensorBehavior",
    runnable_entities=[runnable],
    events=[timing_event, init_event, data_rx_event]
)

component = ApplicationSwComponentType(name="Sensor")
component.internal_behavior = behavior
```

---

## 打包与导出

### 基本导出流程

```python
from src import (
    create_arxml_document, write_arxml, create_package,
    get_ar_packages_element, add_package_to_document,
    create_base_type, create_value_type, create_unit
)

doc = create_arxml_document()
packages_element = get_ar_packages_element(doc)

base_type = create_base_type("UInt8", size=8)
app_type = create_value_type("AppData")
package = create_package("MyPkg", elements=[base_type, app_type])

package_element = package.to_arxml(doc)
add_package_to_document(doc, package_element)

write_arxml(doc, "output.arxml")
```

### 格式化输出

```python
from src import write_arxml_pretty

write_arxml_pretty(doc, "output_formatted.arxml")
```

---

## 完整示例

以下示例创建一个完整的 AUTOSAR 软件组件配置：

```python
from src import (
    create_arxml_document, write_arxml_pretty, create_package,
    get_ar_packages_element, add_package_to_document,
    create_base_type, create_unit, create_linear, create_compu_method,
    create_value_type, create_impl_value_type,
    create_sender_receiver_interface, SenderReceiverInterface,
    ApplicationSwComponentType, PPortPrototype, RPortPrototype,
    SwcInternalBehavior, RunnableEntity, TimingEvent, InitEvent,
    Category, Encoding, AtomicType, Policy, CalibrationAccess,
    create_sw_addr_method, SectionType, DataTypeMappingSet, DataTypeMapping
)

doc = create_arxml_document()

base_uint8 = create_base_type("UInt8", size=8, encoding=Encoding.TWO_COMPONENT)
base_uint16 = create_base_type("UInt16", size=16, encoding=Encoding.TWO_COMPONENT)

kmh_unit = create_unit("kmh", display="km/h", factor=1.0, offset=0.0)
speed_linear = create_linear(factor=0.01, offset=0)
speed_compu = create_compu_method("SpeedCompu", unit=kmh_unit, linear=speed_linear, category=Category.LINEAR)

app_speed = create_value_type("AppSpeed", unit=kmh_unit, compu_method=speed_compu)
impl_speed = create_impl_value_type("ImplSpeed", base_type=base_uint16)

mapping = DataTypeMapping(
    name="SpeedMapping",
    application_data_type=app_speed,
    implementation_data_type=impl_speed
)
mapping_set = DataTypeMappingSet(name="SpeedMappingSet")
mapping_set.add_mapping(mapping)

data_element = SenderReceiverInterface.DataElement(
    name="SpeedData",
    data_type=app_speed,
    policy=Policy.STANDARD,
    calibration_access=CalibrationAccess.READ_WRITE
)
speed_interface = create_sender_receiver_interface("SpeedInterface", data_element=data_element)

code_method = create_sw_addr_method("CODE", section_type=SectionType.CODE)

runnable = RunnableEntity(
    name="UpdateSpeed",
    symbol="UpdateSpeed",
    minimum_start_interval=0.01,
    can_be_invoked_concurrently=False
)
runnable.add_variable_access(
    VariableAccess(name="SpeedAccess", port_prototype_ref="SpeedPort")
)

timing = TimingEvent(name="Timing_10ms", period=0.01)
init = InitEvent(name="Init", runnable_ref="UpdateSpeed")

behavior = SwcInternalBehavior(
    name="SpeedSensorBehavior",
    runnable_entities=[runnable],
    events=[timing, init],
    symbol="SpeedSensor"
)

port = PPortPrototype(name="SpeedPort", interface=speed_interface)

component = ApplicationSwComponentType(
    name="SpeedSensorComponent",
    supports_multiple_instantiation=False,
    atomic_type=AtomicType.APPLICATION,
    internal_behavior=behavior
)
component.add_port(port)

package = create_package("SpeedSensorPkg", elements=[
    base_uint8,
    base_uint16,
    kmh_unit,
    app_speed,
    impl_speed,
    mapping_set,
    speed_interface,
    code_method,
    component
])

package_element = package.to_arxml(doc)
add_package_to_document(doc, package_element)

write_arxml_pretty(doc, "SpeedSensor.arxml")
print("Generated: SpeedSensor.arxml")
```

---

## 常见问题

### Q: 如何创建多个端口？

```python
interface1 = create_sender_receiver_interface("DataInterface")
interface2 = create_sender_receiver_interface("StatusInterface")

component = ApplicationSwComponentType(name="MyComponent")
component.add_port(PPortPrototype(name="DataPort", interface=interface1))
component.add_port(RPortPrototype(name="StatusPort", interface=interface2))
```

### Q: 如何添加多个 Runnable？

```python
behavior = SwcInternalBehavior(name="Behavior")

runnable1 = create_runnable_entity(name="InitRunnable", symbol="Init")
runnable2 = create_runnable_entity(name="MainRunnable", symbol="Main", minimum_start_interval=0.01)

behavior.add_runnable(runnable1)
behavior.add_runnable(runnable2)

component = ApplicationSwComponentType(name="MyComponent")
component.internal_behavior = behavior
```

### Q: 如何创建嵌套结构体？

```python
inner_type = create_value_type("InnerValue")
inner_struct = ApplicationStructureDataType(name="InnerStruct")
inner_struct.add_element(
    ApplicationStructureDataType.StructureElement(name="value", data_type=inner_type)
)

outer_struct = ApplicationStructureDataType(name="OuterStruct")
outer_struct.add_element(
    ApplicationStructureDataType.StructureElement(name="inner", data_type=inner_struct)
)
```