기술 칼럼

MathWorks 인사이트

Simulink 모델을 문서화하는 5가지 방법


저자:

  • Emmanouil Tzorakoleftherakis, MathWorks

읽는 시간: 6분

이전에 만든 Simulink® 모델이나 동료가 개발한 모델을 열었는데 작동 방식을 이해할 수 없었던 적이 있나요? 이런 상황에서는 적절한 문서화가 큰 도움이 될 수 있습니다. 또한 문서화는 생산성을 높이고 팀 간 협업을 촉진할 수 있습니다.

Simulink 모델을 문서화하는 방법에는 여러 가지가 있습니다. 이 기술 칼럼에서는 개략적인 모델 설명과 간단한 캔버스 메모부터 더 상세한 모델 및 블록 문서화에 이르는 5가지 옵션을 안내합니다. 각 방법을 설명하기 위해 그림 1에 나와 있는 Simulink 차량 모델을 사용하겠습니다.

그림 1. Simulink의 전체 차량 모델.

그림 1. Simulink의 전체 차량 모델. 

모델 정보 지정 및 표시

먼저 모델에 대한 개략적인 설명을 제공할 수 있습니다. 모델의 Description 속성은 속성 인스펙터 뷰(그림 2)에서 확인하고 편집하거나, 캔버스를 마우스 오른쪽 버튼으로 클릭하고 모델 속성을 선택하여 확인하고 편집할 수 있습니다. 모델 설명을 확인하려면 MATLAB® 명령 프롬프트에서 help와 모델 이름을 차례로 입력하십시오.

그림 2. 모델 설명이 표시된 속성 인스펙터 뷰.

그림 2. 모델 설명이 표시된 속성 인스펙터 뷰.

속성 인스펙터의 정보 탭에는 수정 내용, 버전, 마지막 저장 날짜 등 모델 내역도 요약되어 있습니다.

모델에 어노테이션 추가

어노테이션을 추가하는 것도 설계의 가독성과 명확성을 높이는 방법입니다. 어노테이션은 설명 노트와 콜아웃을 빠르게 추가할 수 있는 시각적 요소입니다. 팔레트를 사용하거나 캔버스를 더블클릭하고 어노테이션 만들기를 선택하여 텍스트, 이미지, 수식, 웹사이트나 MATLAB® 함수 링크를 원하는 대로 조합한 어노테이션을 만들 수 있습니다. 어노테이션의 유형과 모양을 수정할 수 있습니다. 예를 들어 LaTeX 또는 MathML로 수학 방정식을 추가할 수 있습니다.

어노테이션 윤곽선 위에 커서를 놓고 커넥터 선을 원하는 블록으로 드래그하면 어노테이션과 블록 사이에 커넥터 선을 추가할 수 있습니다. 팔레트를 사용하거나 관심 영역 주위로 상자를 드래그한 후 작업 표시줄에서 영역 만들기를 선택하여, 모델의 특정 영역을 상자로 묶어 관련 블록을 시각적으로 그룹화하고 모델 가독성을 높일 수 있습니다. 영역에 레이블을 지정하여 블록 간의 관계를 나타낼 수 있습니다.

그림 3은 이러한 어노테이션 기법을 보여 줍니다.

그림 3. 어노테이션이 추가된 모델.

그림 3. 어노테이션이 추가된 모델.

블록 및 신호 문서화

설계가 진행됨에 따라 수백, 수천 개의 블록과 신호를 다루게 되어 모델을 이해하기가 더욱 어려워질 것입니다.

신호와 블록에 이름을 지정하면 설계의 명확성을 즉시 높일 수 있습니다. (그림 4) 신호 이름을 입력하거나 편집하려면 신호를 우클릭하고 속성을 선택하거나, 신호를 더블클릭하면 됩니다. 블록 이름을 지정하려면 블록 바로 아래에 있는 기본 이름을 클릭하십시오.

블록의 서식, 스타일, 모양을 제어하는 방법에 대해 자세히 알아보십시오.

그림 4. 어노테이션이 추가된 블록과 신호.

그림 4. 어노테이션이 추가된 블록과 신호.

블록 또는 신호 속성의 해당 필드를 사용하여 블록 또는 신호에 대한 설명을 입력할 수 있습니다. 그런 다음 블록 아이콘 아래에 또는 블록 위에 마우스를 올렸을 때 설명 및 기타 블록 속성을 표시할 수 있습니다. 어노테이션이 추가된 블록과 신호는 그림 4에 나와 있습니다. 또한 모델에서 생성된 C/C++ 코드에 블록 설명을 주석으로 포함할 수도 있습니다.

마스크를 사용하여 블록에 사용자 지정 인터페이스를 정의하는 경우에도 마스크 편집기의 문서화 창에서 설명을 제공할 수 있습니다. (그림 5) 같은 창의 도움말 필드에는 마스크 처리된 블록 사용자가 마스크 대화 상자에서 도움말 버튼을 클릭할 때 표시할 정보를 입력할 수 있습니다.

그림 5. 마스크 처리된 블록에 대한 문서화.

그림 5. 마스크 처리된 블록에 대한 문서화.

모델 계층에 노트 추가

모델이 커질수록 계층 구조에 더 많은 계층이 추가되어 전체 그림을 파악하기 어려워집니다. 뷰마크, 노트, DocBlock을 사용하여 모델의 개별 계층에 어노테이션을 추가할 수 있습니다.

뷰마크는 모델의 일부분을 북마크하는 기능으로, 이를 사용하여 모델의 특정 부분으로 바로 이동하고 특정 뷰에 대한 세부 정보나 주석을 제공할 수 있습니다. 뷰마크를 만들려면 캡처하려는 모델 부분에서 팔레트의 이 뷰를 뷰마크에 추가 버튼을 선택합니다. 뷰마크 버튼을 클릭하면 뷰마크를 확인하고 설명이나 주석을 추가할 수 있습니다. (그림 6)

그림 6. 모델의 특정 뷰를 자세히 설명하는 뷰마크.

그림 6. 모델의 특정 뷰를 자세히 설명하는 뷰마크.

모델 계층 구조의 계층에 노트를 추가하려면 먼저 노트 파일을 만들어야 합니다. 노트에는 이미지와 링크는 물론 URL도 포함할 수 있습니다. (그림 7) 모델에 이미 연결된 노트가 있는 경우, 계층 구조를 탐색할 때 노트 창에 현재 계층의 내용이 표시됩니다. 

그림 7. 모델 계층 구조의 특정 계층을 자세히 설명하는 노트.

그림 7. 모델 계층 구조의 특정 계층을 자세히 설명하는 노트.

DocBlock을 사용해서도 노트를 추가할 수 있습니다. 이 블록의 인스턴스를 더블클릭하면 블록과 연결된 텍스트가 포함된 임시 파일이 생성되고 편집기에서 해당 파일이 열립니다. (그림 8) 참고로 DocBlock의 주석 텍스트를 전역 주석으로 사용하여 모델에서 생성된 코드에 표시할 수 있습니다.

그림 8. 주석이 추가된 DocBlock.

그림 8. 주석이 추가된 DocBlock.

버스, 신호, 파라미터 문서화

Simulink 모델은 모델 외부에 저장된 변수와 데이터를 사용하는 경우가 많습니다. 예를 들어 버스, 신호, 파라미터 객체는 주로 기본 작업 공간에 저장됩니다. 객체의 Description 속성을 사용하여 객체의 역할과 기능을 자세히 설명할 수 있습니다. 이 작업은 다음과 같이 프로그래밍 방식으로 수행할 수 있습니다.

>> myParam = Simulink.Parameter; myParam.Description = 'This is the parameter description';

또는 모델 탐색기에서 열거나 객체를 더블클릭하여 열 수 있는 해당 대화 상자에서 수행할 수도 있습니다. (그림 9)

그림 9. 버스, 신호, 파라미터 객체의 설명 필드.

그림 9. 버스, 신호, 파라미터 객체의 설명 필드.

Embedded Coder®를 사용하여 모델에서 코드를 생성하는 경우, 버스, 신호, 파라미터 객체의 설명을 생성된 코드의 변수 선언에 대한 주석으로 추가할 수 있습니다. (그림 10)

그림 10. 버스, 파라미터, 신호 객체의 설명 필드를 생성된 코드의 주석으로 사용.

그림 10. 버스, 파라미터, 신호 객체의 설명 필드를 생성된 코드의 주석으로 사용.

Simulink 데이터 객체의 설명을 생성된 코드에 주석으로 삽입하는 방법과 생성된 코드에 사용자 지정 주석을 추가하는 방법에 대해 자세히 알아보십시오.

다음 단계

여기까지 읽으셨다면, 프로젝트에 Simulink 모델이 여러 개 있는 경우에는 어떻게 해야 할지 궁금하실 수도 있습니다. 프로젝트 전체로 확장할 수 있는 방법이 있을까요? 프로젝트와 Simulink Report Generator™, Requirements Toolbox™ 같은 제품을 사용하면 이 기술 칼럼에서 다룬 기법을 자연스럽게 확장할 수 있습니다.

Simulink Report Generator를 사용하면 모델에서 PDF, Microsoft® Word®, Microsoft PowerPoint®, HTML 등 일반적인 형식으로 리포트를 설계하고 자동 생성할 수 있습니다.

Requirements Toolbox를 사용하면 서식 있는 텍스트로 요구사항을 작성하고 이를 설계, 코드, 테스트에 연결할 수 있습니다. 요구사항의 구현 및 검증 상태를 확인하여 프로젝트 완성도를 평가할 수 있습니다.

프로젝트를 사용하면 프로젝트를 체계적으로 관리하고 개인의 생산성은 물론 효율적인 팀워크도 향상할 수 있습니다. 모든 프로젝트 파일을 한곳에서 관리하고, 동료 검토 워크플로를 위해 파일을 확인하고 레이블을 지정하며, Subversion® 또는 Git™ 같은 외부 소스 컨트롤 도구로 프로젝트를 추적하고 공유할 수 있습니다.

2018년 기고


사용된 제품: Embedded Coder, Stateflow

저자 소개

Emmanouil Tzorakoleftherakis

Emmanouil Tzorakoleftherakis는 MathWorks의 수석 제품 관리자로, 강화학습 및 제어 시스템 분야를 중점적으로 담당하고 있습니다. Northwestern University에서 제어 시스템 및 로보틱스를 전공하여 기계공학 석사 및 박사 학위를 취득했으며, 그리스의 University of Patras에서 전기공학 및 컴퓨터공학 학사 학위를 취득했습니다.

심화 주제 탐색