====== Web API (CHC 시리즈 & 펌웨어 v3.49 이상 지원)====== Web API 기능은 HTTP 프로토콜을 사용하여 원격으로 HMI(서버 역할)와 통신하면서 여러가지 처리를 할 수 있는 기능입니다. (HMI 제어하기, //내부 변수//나 //내부 메모리// 값 등을 읽어오기, HMI에 있는 파일을 웹브라우저로 다운로드, 실행하기, 웹브라우저에 실시간 동작 UI 구성하기 등) 기존의 웹브라우저(예: 크롬)를 사용할 수도 있고 다른 HMI가 클라이언트가 되어 사용할 수도 있습니다('액션>HTTP 요청') ===== 1. URL 작성하는 방법 ===== HMI의 'HTTP 요청' 액션이나 웹브라우저 주소창에서 URL을 입력할 경우 다음과 같은 형식으로 해야 원격지 HMI(서버)가 인식할 수 있습니다. **IP주소 : 포트번호 / 커맨드명 / 원격제어 비밀번호 / 커맨드 내용** 예1) 192.168.0.30:9138/script/1234/a=a+1;vars_to_json("a") \\ 예2) 192.168.0.30/download//storage card/logs/log1.txt 서버가 ComfileHMI가 아닌 경우는 위와 같은 형식이 아닌 일반적인 자유로운 HTTP URL 형식으로 'HTTP 요청' 액션에서 전송 가능합니다. ==== 1) IP 주소 ==== IP주소는 내부 네트워크 주소(예: 192.168.0.20) 또는 도메인(예: myserver.com)을 쓸 수 있습니다. ==== 2) 포트번호 ==== 포트번호는 서버 쪽에서 설정한 포트 번호를 쓰면 되고, 생략 가능합니다.(생략시 80으로 간주) ==== 3) 커맨드명 ==== 커맨드는 어떤 동작을 수행할지 결정하는 것이고 다음과 같은 종류가 있습니다. (1) 'script' HMI의 [액션>스크립트]에서 사용하는 스크립트를 사용합니다. //내부 변수//, //내부 문자열 변수//, 함수 등을 사용할 수 있으며 세미콜론(';')으로 연결하여 스크립트를 길게 작성할 수 있습니다. (2) 'open' HMI 액션에서는 지원하지 않고 웹브라우저에서만 지원되는 커맨드입니다. \\ HTML이나 이미지 파일, mp3, wav 파일 등 웹브라우저에서 인식 가능한 포맷을 웹브라우저로 불러 들여 표시/재생할 수 있습니다. (3) 'download' HMI 액션에서는 지원하지 않고 웹브라우저에서만 지원되는 커맨드입니다. \\ 파일 종류를 가리지 않고 어떤 파일이든 웹브라우저를 통해 파일 자체를 그대로 다운로드 받을 수 있습니다. ==== 4) 원격제어 비밀번호 ==== 서버의 '런타임 설정>서버>비밀번호 설정'에서 설정된 비밀번호를 입력합니다. 서버 측에 비밀번호가 설정되지 않았다면 이 값은 생략할 수 있습니다. ==== 5) 커맨드 내용 ==== (1) 'script'의 경우 스크립트 내용을 입력합니다. 특별히, 서버 측에서 가져오고 싶은 변수값이나 메모리 내용등이 있다면 vars_to_json , mem_to_json 함수를 함께 사용합니다. (자세한 내용은 함수 설명 참조) 예) a=a+1;vars_to_json("a") \\ HMI 액션과 웹브라우저에서 모두 사용할 수 있습니다. (2) 'open'이나 'download'의 경우 웹브라우저 전용 커맨드의 커맨드 내용으로서 서버 HMI 상의 파일 경로를 지정해줍니다. \\ 파일 경로는 SD카드에 있는 파일만 지정할 수 있으며 storage card/로 시작합니다. 폴더 구분자로 '\'가 아닌 '/'을 사용합니다. 예1) 192.168.0.30:9138/open//storage card/MyWebHmi/index.htm \\ 예2) 192.168.0.30:9138/download//storage card/logs.txt ==== 6) 웹브라우저 주소창에서 사용시 제약 사항 ==== 웹브라우저 주소창에서는 '#' , '%' , '\' 문자들을 직접적으로 표현하지 못하므로 다음과 같이 치환하여 사용합니다. '#' -> '%23' \\ '%' -> '%25' \\ '\' -> '%5C' (파일 경로일 경우 간단하게 '/'로도 치환 가능) 예1) 192.168.0.20:9138/script//$a="3 나누기 5는 백분율로 60%25입니다.";vars_to_json("$a") \\ 예2) 192.168.0.20:9138/open//storage card/web_hmi.html \\ 예3) 192.168.0.20:9138/download//storage card/sub/data.bin \\ 예4) 192.168.0.20:9138/script//filenames_to_json("storage card/dir") ===== 2. 응답 처리하는 방법 ===== ComfileHMI는 적절한 포맷을 갖춘 'script' 커맨드 요청이 왔을 때 혹은 URL에 오류가 있을 경우 'JSON' 형식으로 응답합니다. \\ 웹브라우저 전용 'open'이나 'download' 커맨드의 경우는 실패한 경우에만 JSON 형식으로 응답합니다. ==== 1) HMI 클라이언트에서 응답 처리하는 방법 ==== HMI 클라이언트는 들어오는 JSON 응답을 자체적으로 해석할 수 있는 능력이 있으므로 별도로 JSON에 관한 처리를 안하더라도 자동으로 처리됩니다. 원격지 //내부 변수//값이나 //내부 메모리//값이 JSON 형식으로 수신되면 HMI 클라이언트는 그 내용을 그대로 자신에게 복사합니다.(같은 변수명, 같은 메모리 번지로) \\ 도착한 JSON 응답이 자동 처리된 후 실행할 사용자 액션을 지정할 수 있습니다. \\ JSON 응답에는 변수값이나 메모리값 등의 정보 이외에도 성공했는지 여부, 에러일 경우 에러코드와 에러메시지 정보도 담길 수 있습니다. 가장 최근에 응답 온 JSON 관련해서, 성공여부는 last_json_result() 함수, 에러 코드는 last_json_error_code() 함수, 에러메시지는 last_json_error_message() 함수를 사용하여 알아낼 수 있습니다. 이 함수들에 대한 자세한 설명은 다음 링크를 참고하세요 : [[http://www.comfilewiki.co.kr/ko/doku.php?id=comfilehmi:hmieditor_function:index#web_api_%EA%B4%80%EB%A0%A8_%ED%95%A8%EC%88%98_%EA%B3%A0%EA%B8%89_%EA%B8%B0%EB%8A%A5_chc_hdm-c070rl_%EB%98%90%EB%8A%94_%EA%B7%B8_%EC%83%81%EC%9C%84_%EB%AA%A8%EB%8D%B8%EC%97%90%EC%84%9C%EB%A7%8C_%EC%A7%80%EC%9B%90|WebAPI 관련 함수]] ==== 2) 웹브라우저에서 응답 처리하는 방법 (HTML / javascript / JSON에 대한 이해 필요) ==== download나 open 커맨드의 경우 성공할 경우 웹브라우저에 결과 동작이 반영되므로 JSON을 처리하는 문제를 고려할 필요가 없지만, script 커맨드의 경우는 응답이 항상 JSON 형식으로 도착하므로 들어오는 JSON 응답을 처리하려면 해당 처리를 할 수 있는 HTML 소스 코드를 직접 작성해두어야 합니다. 작성된 HTML 소스는 SD카드의 적당한 위치에 위치시키고 open 커맨드를 통해 웹브라우저로 불러옵니다.(HTML 파일은 반드시 원격지 HMI 에 있어야 하며 웹브라우저가 존재하는 로컬 PC에 존재하면 제대로 실행이 안될 수 있음) 쉬운 예제) 변수 a 값과 HMI 메모리의 5,6 번지의 값을 원격지에 있는 HMI로부터 받아서 실시간으로 (200ms 주기로) 웹브라우저에 표시합니다. \\ {{ :comfilehmi:webapi:sample1.htm | 쉬운 예제 HTML 파일 다운로드 받기}} \\ {{:comfilehmi:webapi:sample1.png|}} 고급 예제) 웹브라우저의 슬라이더로 원격지 HMI에 있는 변수 a의 값을 쓰고, 다시 그 값을 불러 와서 웹브라우저의 게이지 그래프에 표시하는 예제. 슬라이더의 값이 정한 범위(0~100)를 넘어가면 게이지가 빨간색으로 변합니다. \\ {{ :comfilehmi:webapi:sample2.htm | 고급 예제 HTML 파일 다운로드 받기}} \\ {{:comfilehmi:webapi:sample2.png|}}{{:comfilehmi:webapi:sample2b.png|}} <예제 테스트 절차> \\ 1. 다운로드 받은 sample1.htm 또는 sample2.htm 파일을 HMI의 storage card 폴더 밑에 복사한다.(SD카드의 루트 폴더) \\ 복사하기 전에, htm 소스 코드 내부에 원격 IP 주소 설정하는 부분 중 '서버 주소:포트 번호'를 환경에 맞게 변경해줘야 한다.('192.168.0.99:9138'이라고 되어 있는 부분) \\ 2. HMI의 런타임 [설정>서버>원격 제어 서버 구동]에 체크하고 네트워크탭을 해당 환경에 맞게 설정해준다. \\ 3. 웹브라우저를 실행하고 주소창에 URL을 입력한다. \\ 예) 192.168.0.99:9138/open//storage card/sample1.htm (서버 주소가 192.168.0.99이고 포트번호가 기본 포트 번호인 9138이고 설정된 비밀번호가 없는 경우) ===== 3. JSON 응답 형식 ===== ^ 필드명 ^ 타입 | 내용 | | success | boolean | 성공 여부. true이면 성공. false이면 실패 | | vars.{내부 변수명} | number | vars_to_json() 함수로 요청한 원격지 //내부 변수//의 값. | | vars.{내부 문자열 변수명} | string | vars_to_json() 함수로 요청한 원격지 //내부 문자열 변수//의 값. \\ //내부 문자열 변수//명은 '$'로 시작함. | | mem.{내부 메모리 시작 번지} | array | mem_to_json() 함수로 요청한 원격지 내부 메모리의 주소 연속적인 값들 | | error.code | number | 오류 코드 | | error.message | string | 오류 메세지. 언어는 프로젝트 기본 언어 설정에 따라 | | filenames | array | filenames_to_json() 함수로 요청한 원격지 HMI 특정 폴더 내의 파일명 목록 | | dirnames | array | dirnames_to_json() 함수로 요청한 원격지 HMI 특정 폴더 내의 폴더명 목록 | 예1) 성공했을 경우 { "success": true, "vars": { "temperature" : 16.7, "$city" : "Seoul" }, "mem" : { "20" : [31,43,21] } } 예2) 실패했을 경우 { "success" : false, "error" : { "code" : 4011, "message" : "Command syntax error." } } Web API 에러 코드와 에러 메세지 ^ 오류 코드 ^ 오류 메세지 ^ | 8047 | 응답받은 JSON의 형식이 잘못되었습니다. | | 4011 | 커맨드의 구문 오류입니다. 다음과 같이 사용하세요 : 서버 주소:포트번호/커맨드명/비밀번호/커맨드 내용 | | 4010 | 알 수 없는 커맨드입니다. | | 3010 | Web API 실행을 지원하지 않는 기기입니다. 지원되는 기기 예: CHC, HDM-C070RL | | 3009 | 현재 프로젝트 실행 모드가 아닌 HMI 기기에 접속을 시도했습니다. | | 3012 | 원격제어 비밀번호가 맞지 않습니다. | | 3013 | 스크립트의 구문 오류입니다. | [[comfilehmi:index|ComfileHMI]]