라이브러리 사용자 입장에서의 Getting Started (Using euphony)

[designe]

@euphony-io/euphonyforever-a 팀에 배정되는 첫번째 이슈입니다.

초보 개발자 입장에서도 Guide를 보며 쉽게 라이브러리를 사용할 수 있는 친절한 설명이 필요할 것 같습니다.

현재는 아래 정도로 README.md에 적혀 있어요.

정말 간단하게 Java에서의 사용법만 나와있는데
최근에는 kotlin 기반 안드로이드 앱이 많이 나오고 있기도 하고
이에 대한 guide도 필요한 상황입니다. (자바로 라이브러리가 구성되어 있더라도 Kotlin에서 쓰는 것이 가능합니다)

Java와 Kotlin 둘다 좀 더 디테일한 설명과
markdown을 이용해 사용자 입장에서 알아보게 정리하는 방법이 있을까요?

우선은 여기 issue를 통해서 팀원들과 커뮤니케이션을 하면서 전체 구성을 완성해보시구요.
내용도 어떻게 쓸지 각자 여기 남겨가면서 작성해보면 좋겠습니다.
markdown을 연습한다는 생각으로 많이 많이 써주시면 좋을 것 같아요.

PR은 이번주 토요일 이후에 진행해보시도록 할게요 :)
https://github.com/euphony-io/euphony#euphony-is-very-easy-to-use

[dlwlstks96]

초보 개발자를 위한 가이드이기에
깃에서 프로젝트를 clone 하는 법부터 명시해주면 좋지 않을까 싶습니다!

원하는 프로젝트의 URL 복사

내려 받을 폴더에서 git bash 창을 열고 git clone URL 입력

안드로이드 스튜디오 실행 후 File - New - Import Project - 프로젝트 선택
선택 시 위 사진처럼 정상적으로 import 완료

[dlwlstks96]

제가 안드로이드 스튜디오를 처음 접해봐서 다양한 시도 후
빌드에 성공한 것 같아 남깁니다!!

우선 제가 빌드에 실패했던 원인을 밝히며 그로 인한 실패 사례,
그리고 해결 방법을 사진으로 첨부하면 좋을 것 같습니다!

아래부터는 프로젝트를 정상적으로 import 후
implementation 'euphony.lib:euphony:0.7.1.6' 을 build.gradle에 작성해야 하는 차례입니다.

이때 저처럼 build.gradle(Project)에 작성할 경우

위와 같은 오류가 발생하게 됩니다.

때문에 readme에 적혀 있는 "in app module" 안내를 놓치지말고 정확한 위치에
작성해주어야합니다.

uses-permission android:name="android.permission.RECORD_AUDIO" / 또한
정확한 위치(AndroidManifest.xml)에 작성해줍니다.

그럼 기존 readme의 내용은 전부 완료한 것으로 생각됩니다!

[hyorin03]

[Kotlin]

in Transmitter

val mTxManager = EuTxManager()
mTxManager.euInitTransmit("Hello, Euphony") // To generate acoustic data "Hello, Euphony"
mTxManager.process(-1) // generate sound infinite.

README의 Java 버전 transmitter를 kotlin으로 변경하면 다음과 같습니다.
Transmitter의 코드 자체는 이 정도면 충분하다고 생각합니다.
다만 좀 더 자세히 풀어 쓸 필요성을 느끼는데 다들 어떻게 생각하시나요? 좋은 방식이 있으면 말해주시면 감사하겠습니다~!

• Euphony 라이브러리 기능을 테스트해보기 위해 프로젝트를 만들었습니다. (주소: euphony-test-sample)
  Transmitter 부분은 euphony-speaker를 참고하였습니다.

• 내일은 Receiver 부분 Kotlin 변환 진행하고자 합니다.
  Receiver는 권한 처리 등 Transmitter 보다 좀 더 까다로울 것 같고 좀 더 자세하게 README에 적어줘야 할 것 같은 느낌입니다.

[dlwlstks96]

[Kotlin]

in Transmitter

val mTxManager = EuTxManager()
mTxManager.euInitTransmit("Hello, Euphony") // To generate acoustic data "Hello, Euphony"
mTxManager.process(-1) // generate sound infinite.

README의 Java 버전 transmitter를 kotlin으로 변경하면 다음과 같습니다.
Transmitter의 코드 자체는 이 정도면 충분하다고 생각합니다.
다만 좀 더 자세히 풀어 쓸 필요성을 느끼는데 다들 어떻게 생각하시나요? 좋은 방식이 있으면 말해주시면 감사하겠습니다~!

• Euphony 라이브러리 기능을 테스트해보기 위해 프로젝트를 만들었습니다. (주소: euphony-test-sample)
  Transmitter 부분은 euphony-speaker를 참고하였습니다.
• 내일은 Receiver 부분 Kotlin 변환 진행하고자 합니다.
  Receiver는 권한 처리 등 Transmitter 보다 좀 더 까다로울 것 같고 좀 더 자세하게 README에 적어줘야 할 것 같은 느낌입니다.

넵 가이드를 전반적으로 조금 더 자세하게 풀어쓰면 좋을 것 같습니다!!

[hyorin03]

넵! 그리고 transmitter 부분에는 RECORD_AUDIO 권한 처리가 필요 없는 걸로 판단되어 이 부분도 따로 구분하여 작성하면 좋을 것 같습니다.

[dlwlstks96]

가이드에 나와있는대로 자바로 먼저 빌드를 해보려는 중
빌드 실패를 겪었습니다

혹시 팀원분들 중 해결 방법을 아시는 분 계신가해서 글 남깁니다!!

안드로이드 스튜디오 내 터미널을 이용하여 gradlew build 입력하면
위와 같은 오류가 뜹니다!

혹시 제가 해결 방법을 찾게 되면 공유하도록 하겠습니다!

자바로 빌드 성공 후 코틀린 언어로 가이드 작성할 수 있게끔 시도하겠습니다!

[hyorin03]

가이드에 나와있는대로 자바로 먼저 빌드를 해보려는 중
빌드 실패를 겪었습니다

혹시 팀원분들 중 해결 방법을 아시는 분 계신가해서 글 남깁니다!!

안드로이드 스튜디오 내 터미널을 이용하여 gradlew build 입력하면
위와 같은 오류가 뜹니다!

혹시 제가 해결 방법을 찾게 되면 공유하도록 하겠습니다!

자바로 빌드 성공 후 코틀린 언어로 가이드 작성할 수 있게끔 시도하겠습니다!

이 부분은 저도 확인을 안 해봐서 잘 모르겠는데 어떤 프로젝트 빌드하신 건가요?
저희가 맡은 부분은 사용자의 입장에서 라이브러리를 사용하는 부분이라 euphony-speaker와 euphony-listener를 빌드해 보고 사용해보시면 좋을 듯 합니다.

[dlwlstks96]

가이드에 나와있는대로 자바로 먼저 빌드를 해보려는 중
빌드 실패를 겪었습니다
혹시 팀원분들 중 해결 방법을 아시는 분 계신가해서 글 남깁니다!!

안드로이드 스튜디오 내 터미널을 이용하여 gradlew build 입력하면
위와 같은 오류가 뜹니다!

혹시 제가 해결 방법을 찾게 되면 공유하도록 하겠습니다!
자바로 빌드 성공 후 코틀린 언어로 가이드 작성할 수 있게끔 시도하겠습니다!

이 부분은 저도 확인을 안 해봐서 잘 모르겠는데 어떤 프로젝트 빌드하신 건가요?
저희가 맡은 부분은 사용자의 입장에서 라이브러리를 사용하는 부분이라 euphony-speaker와 euphony-listener를 빌드해 보고 사용해보시면 좋을 듯 합니다.

speaker, listener가 아닌 euphony 프로젝트 자체를 빌드 시도했던 것입니다.
말씀하신대로 speaker 먼저 빌드 시도해보았고 결과는 아래와 같았습니다!

위와 같은 에러가 다시 발생하였고

터미널창에 명시된 해결 방법을 위와 같이 작성했습니다.

이후 빌드 성공이라는 결과는 얻었으나 앞서 발생한 이슈와 동일하게
"lint 검사 단계"에서 오류가 발생하는 것 같습니다!
이번에 처음 접해보는 오류로 다른 사용자 또한 같은 상황을 겪을 수도 있음에
더욱 자세하게 원인과 해결 방법을 알아보도록 하겠습니다!

마지막으로 멘토님께 질문 드리고 싶습니다!
터미널창에 명시된 바와 같이 lintOptions에 abortOnError를 false 값으로 준다는 것은
오류를 무시하고 진행하겠다는 것으로 이해됩니다.
이렇게 빌드를 접근해도 문제가 없는 것인지 궁금합니다!

[designe]

@dlwlstks96
#16 (comment)
@euphony-io/eutamin-c 팀에서도 동일한 이슈가 나왔었으니 참조하면 좋을 것 같습니다 :)

[dlwlstks96]

@designe
넵 확인하였습니다!! 답변 감사드립니다!!

[dlwlstks96]

euphony를 실제 모바일에서 구동하는 방법

apk 파일을 추출하여 구동하기

• Build - Build Bundle/APK - Build APK 를 이용해 apk 파일을 추출합니다.

• 프로젝트 폴더 내 경로 app - build - outputs - apk - debug 에 apk 파일이
  생성된 것을 확인할 수 있습니다.

• 해당 apk 파일을 실제 모바일로 옮겨 설치 후 앱을 실행하면 euphony 앱이 정상 작동됩니다.

내일 usb로 모바일을 연결하여 구동하는 방법도 실제 연결 후 스크린샷과 함께 추가하겠습니다!

또한 Markdown을 이용한 작성법에 관해 참고하면 좋을 것 같은 링크 남겨두겠습니다!!
https://guides.github.com/features/mastering-markdown/
https://heropy.blog/2017/09/30/markdown/

[hyorin03]

[Kotlin]

In Receiver

val mRxManager = EuRxManager()
mRxManager.acousticSensor = AcousticSensor { letters ->
     //when data is received
}

//Listening Start
mRxManager.listen()
// if you want to finish listening, call the finish();
mRxManager.finish()

Receiver 부분도 Kotlin으로 변형했습니다. 다른 의견 있으면 편하게 말씀해주세요~
README에 코드에 대한 설명과 권한 설정이 필요한 점을 친절하게 풀어쓰면 좋을 것 같습니다.

[6loss0m]

라이브러리 사용자를 위해 기능(메소드) 설명이 추가적으로 필요한 것 같습니다.
우선 클래스를 중심으로 나중에는 세부적인 메소드 또한 추가할 계획입니다.

1. receiver

• AudioRecorder : 오디오 녹음
• EuDataDecoder : 데이터를 16진수로 변환
• EuFreqObject : 주파수 계산, 설정
• EuRxManager : 수신주파수 설정
• EuWindows : 그래프 표시 방법 설정
• KissFFT : 고속 푸리에 변환

2. transmitter

• EuCodeMaker : 인코딩 생성
• EuDataEncoder : 데이터인코딩
• EuFreqGenerator : 주파수 생성, 관리
• EuPlayer : 소리 재생, 정지
• EuTxManager : 문자 송출, 볼륨 조절

3. util

• ErrorHandler : 채널의 상태, 노이즈 정보
• EuAfRangeFinder : 채널 위치 조정
• EuCodec : 문자열을 byte로 변환
• EuOption : encoding, communication mode 설정
• PacketErrorDetector : parity와 관련된 설정

참고자료 없이 코드를 읽고 개인적으로 작성한거라 다른 의견이 있으시거나 틀린부분은 피드백해주시면 바로 수정 하겠습니다!!

[dlwlstks96]

@6loss0m 클래스별 설명 감사합니다!
참고하여 euphony 프로젝트를 이해하는데 큰 도움이 되었습니다!

저는 euphony 사용자가 간단한 부분부터 활용 및 수정할 수 있는
부분을 가이드해주면 좋을 것 같아 onClickListener 부분을 안내해보았습니다!

euphony 실행 버튼에 대한 직관적인 코드 부분

사용자가 euphony의 매우 간단한 부분들을 수정할 수 있게끔 하기 위한 안내

Transmitter(Speaker)에서의 음파 송출 버튼(Speak ON)

• MainActivity.java 파일 내 mSpeakBtn.setOnClickListener()
• Transmitter의 버튼 클릭 후 실행 과정을 사용자가 원하는대로 직관적으로 수정 및 간단한 기능을 추가해 볼 수 있다.
• ex) Dialog 띄우기

Receiver(Listener)에서의 음파 수신 버튼(Listen)

• MainActivity.java 파일 내 listenBtn.setOnClickListener()
• 위와 동일하게 사용자가 원하는대로 Receiver의 버튼 클릭 후 실행 과정을 직관적으로 수정 및 간단한 기능을 추가해 볼 수 있다.

[hyorin03]

I wrote it with @6loss0m .
This is the draft.

---

in Transmitter

마이크를 통한 Euphony 음파 발생 부분

1. EuTxManager 객체 생성

[Java]

EuTxManager mTxManager = new EuTxManager();

[Kotlin]

val mTxManager = EuTxManager()

2. 음파로 전송할 문장(데이터) 입력

[Java]

mTxManager.euInitTransmit("Hello, Euphony"); // To generate acoustic data "Hello, Euphony"

[Kotlin]

mTxManager.euInitTransmit("Hello, Euphony") // To generate acoustic data "Hello, Euphony"

3. 발생 횟수 설정 및 음파 발생

음파가 발생하는 횟수를 지정하고 음파를 발생시킨다. (0보다 작으면 무한)

[Java]

mTxManager.process(-1); // generate sound infinite.

[Kotlin]

mTxManager.process(-1) // generate sound infinite.

in Receiver

레코더를 통한 음파 수신 부분

RECORD_AUDIO 권한 필요

1. EuRxManager 객체 생성

[Java]

EuRxManager mRxManager = new EuRxManager();

[Kotlin]

val mRxManager = EuRxManager()

2. 음파를 받아오고 처리하는 Listener 설정

[Java]

mRxManager.setAcousticSensor(new AcousticSensor() {
		@Override
		public void notify(String letters) {
      //when data is received
    }
 });

[Kotlin]

mRxManager.acousticSensor = AcousticSensor { letters ->
    //when data is received
}

3-1. 음파 수신 시작

[Java]

mRxManager.listen(); // Listening Start

[Kotlin]

mRxManager.listen() // Listening Start

3-2. 음파 수신 종료

[Java]

mRxManager.finish(); // Listening finish

[Kotlin]

mRxManager.finish() // Listening finish

[6loss0m]

@designe 님께 질문이 있습니다!

KOR

라이브러리 사용 설명서 구조를 잡던 중 Receiver의 2번이 정확히 어떤 의도인지 알 수 없었습니다.

이에 대해 작성한 게 맞는지 검토 부탁 드립니다.

그 외에 피드백 주실 부분이 있으시다면 알려주세요. 감사합니다.

ENG

While creating the Library User's Guide, we did not know exactly what part No. 2 meant in Receiver.

Please review if it's correct to fill out this part.

If you have any other feedback, please let me know. Thank you.

[dlwlstks96]

@6loss0m
저도 그 부분에 대해 오랜 시간 고민하다가 인터넷에서 관련 글을 발견한 것 같아
부족하지만 링크 공유와 함께 작성해봅니다!

https://brunch.co.kr/@mystoryg/84 -> Handler 스레드 관련
https://recipes4dev.tistory.com/166 -> Handler 스레드 & Message 클래스 관련

private Handler mHandler = new Handler(){		
	public void handleMessage(Message msg){			
		switch(msg.what){
		case RX_DECODE:
			mAcousticSensor.notify(msg.obj + "");
			break;
		default:
			break;
		}
	}
};

위 코드는 EuRxManager에 있는 코드로 Handler 라는 스레드를 이용하여
Message 클래스에 정보를 담아 mAcousticSensor.notify()를 통해 전달하는 것으로 보입니다!
이후 mAcousticSensor의 notify()는 listener의 MainActivity에서 오버라이드 되어
전달 받은 정보(Message에 담긴 String)를 화면에 출력하는 것 같습니다!

@designe
혹여라도 틀린 부분 혹은 조금 더 자세한 부연 설명이 있다면 코멘트 해주시면 감사하겠습니다:)

[dlwlstks96]

We wrote a README.
Code analysis was done by @lin9703 @6loss0m , and translation and writing in the README was done by @dd-create @dlwlstks96.
At the team meeting, we decided to omit the description of Android Studio.

in Transmitter

Generate sound waves and transmits though a microphone.

1. Create EuTxManager type object which turns data into sound waves.

• Java

EuTxManager mTxManager = new EuTxManager();

• Kotlin

val mTxManager = EuTxManager()

2. Use euInitTransmit method, enter the data you want to transmit.

• Java

mTxManager.euInitTransmit("Hello, Euphony");

• Kotlin

mTxManager.euInitTransmit("Hello, Euphony")

3. With process method, set how many times to repeat the sound(data). (-1 is infinite)

• Java

mTxManager.process(-1);

• Kotlin

mTxManager.process(-1)

in Receiver

Part of receiving sound waves.

Requires permission of RECORD_AUIDO

• Write in AndroidManifest.xml

<uses-permission android:name="android.permission.RECORD_AUDIO" />

1. Create EuRxManager object that receives sound waves as data

• Java

EuRxManager mRxManager = new EuRxManager();

• Kotlin

val mRxManager = EuRxManager()

2. Listener settings that receive and process sound waves

• Java

mRxManager.setAcousticSensor(new AcousticSensor() {
		@Override
		public void notify(String letters) {
      //when data is received
    }
 });

• Kotlin

mRxManager.acousticSensor = AcousticSensor { letters ->
    //when data is received
}

3. Start receiving sound waves

• Java

mRxManager.listen(); // Listening Start

• Kotlin

mRxManager.listen() // Listening Start

4. End sound wave reception

• Java

mRxManager.finish(); // Listening finish

• Kotlin

mRxManager.finish() // Listening finish

In KOREAN

송신기

음파를 생성하고 마이크를 통해 전송합니다.

1. 데이터를 음파로 바꾸는 EuTxManager 객체를 생성

• Java

EuTxManager mTxManager = new EuTxManager();

• Kotlin

val mTxManager = EuTxManager()

2. euInitTransmit 메소드로 전송할 문장을 입력

• Java

mTxManager.euInitTransmit("Hello, Euphony");

• Kotlin

mTxManager.euInitTransmit("Hello, Euphony")

3. process 메소드로 문장(음파)을 몇 번 반복할지 설정 (-1은 무한반복)

• Java

mTxManager.process(-1);

• Kotlin

mTxManager.process(-1)

수신기

레코더를 통한 음파 수신 부분

RECORD_AUDIO 권한 필요

• AndroidManifest.xml에 작성한다.

<uses-permission android:name="android.permission.RECORD_AUDIO" />

1. 음파를 데이터로 받아오는 EuRxManager 객체를 생성

• Java

EuRxManager mRxManager = new EuRxManager();

• Kotlin

val mRxManager = EuRxManager()

2. 음파를 받아오고 처리하는 Listener를 설정

• Java

mRxManager.setAcousticSensor(new AcousticSensor() {
		@Override
		public void notify(String letters) {
      //when data is received
    }
 });

• Kotlin

mRxManager.acousticSensor = AcousticSensor { letters ->
    //when data is received
}

3. 음파 수신 시작

• Java

mRxManager.listen(); // Listening Start

• Kotlin

mRxManager.listen() // Listening Start

4. 음파 수신 종료

• Java

mRxManager.finish(); // Listening finish

• Kotlin

mRxManager.finish() // Listening finish

[hyorin03]

실수로 unassigned를 해서 다시 추가해주시면 감사하겠습니다. ㅠㅠ

[designe]

@designe 님께 질문이 있습니다!

KOR

라이브러리 사용 설명서 구조를 잡던 중 Receiver의 2번이 정확히 어떤 의도인지 알 수 없었습니다.

이에 대해 작성한 게 맞는지 검토 부탁 드립니다.

그 외에 피드백 주실 부분이 있으시다면 알려주세요. 감사합니다.

ENG

While creating the Library User's Guide, we did not know exactly what part No. 2 meant in Receiver.

Please review if it's correct to fill out this part.

If you have any other feedback, please let me know. Thank you.

@6loss0m
Sorry, I'm too late to reply your question! I didn't know you ask 😢
No.2 is super important on listener part because if it is not exist, listener couldn't get listening-data.
User can find out the result of sound wave listening by defining this interface to the listener.